proposal: auto-generate the code and documentation based on the proto files

[seeflood]

当前的瓶颈、痛点
API 需求多了、组件需求多了后，人不够，需求支持的慢

举例:

• OSS API
  feat: implement oss interface #556
  5.11 提，7月25合并，不断完善周边建设中，java sdk 没空写
• Notify API
  目前只写了几个 proto，没时间开发
• KMS API
  用户新需求

分析

需求响应时间= API 设计讨论时间  
		+ [	API 数 * API 方法数 (比如 OSS API 有 20+个方法） * (API 开发人时 + 写集成测试用例 + 手动联调时间)
				 + 组件数 * (组件开发人时 + 写组件测试用例 + 手动测试时间)
			] / 人数
		+ PR Review 时间

分析上述公式，我们就能意识到，现在的设计不 scale：
我们希望支持更多 API（API 数↑）、支持并集 API （API 方法数↑）、集成不同云服务（组件数↑），但是人没有变多。
以 notify API 为例：有 4个 API, 每个 API 有2个方法，每个 API 要对接 3个服务（阿里云/ aws/私有云服务）。

所以，本提案的设计目标是研发提效，即使需求变多、人没变多时，依然能快速响应需求

High level design
实现一套工具链，减少工作量。
开发者写完 proto 文件后，敲一个 make proto命令，就能自动生成除了组件外的代码、文档，让开发者只需要花时间写组件

• 调整代码结构，以便生成代码。 chore: modify code structure to make it easier to generate code.  #774

1. 实现一个代码生成器，自动根据 proto 或 open api spec 生成代码，包括:

SDK 相关代码:

• 多语言 sdk
  • go
  • java
  • js
• sdk examples
  • go
  • java
• 测试用例

API 插件相关代码:

• layotto api 插件代码
• 把 API 插件注册进 main
• 字段转换器，把grpc 的 struct 转换成 component 依赖的 struct
• 支持 grpc stream 相关代码

组件相关代码:

• component interface
• 自动根据 component interface 生成相关胶水层代码
  • registry.go
  • factory.go
  • types.go, 包含 component config 等
• ApplicationContext 新增组件
• 根据 examples 生成 mock component

layotto runtime 相关代码:

• pkg/runtime/config.go
• pkg/runtime/options.go
• pkg/runtime/runtime.go
• pkg/runtime/context_generated.go

2. 实现一个文档生成器，自动根据 proto 或 open api spec 生成文档，包括:

• 接口文档
• 把生成的接口文档添加进文档站点的侧边栏
• 双语 quickstart 文档
• 把 quickstart 文档加进 CI 自动化测试
• 把生成的 quickstart 文档添加进文档站点的侧边栏（包括中文和英文侧边栏）

3. 自动生成的东西不需要 review。优化掉上述公式中的“PR Review 时间”

4. 写组件时，不用写测试
   每类 API 公用同一份测试用例，每次写组件不需要写测试

5. 写组件时，自动联调
   自动化可移植性测试，每次写组件不用手动联调，让 CI 自动联调

详细设计
SDK:

• 放弃把 gRPC API 再包一层sdk，让用户直接用 proto 编译生成的客户端来调 Layotto
• 如果用户嫌 gRPC 版本冲突，就生成 http 调用的代码
• sdk 仓库维护一个脚本，自动下载、编译 proto 文件

文档:

• 生成接口文档
• 根据模板，生成 quickstart 文档

// TODO

[seeflood]

进展:

• 文档生成器已合并，见 https://mosn.io/layotto/#/zh/api_reference/how_to_generate_api_doc
• go 代码生成器开发完成，见 https://github.com/seeflood/protoc-gen-p6

todo:

• corner case处理：单个 proto 文件有多个 service 时
  a. 拆成两个 proto
  b. 禁止 proto 这么搞，要求全塞到一个 service 里
  选择 b

• 走一遍流程，测试

• 代码生成器支持一次传多个 proto 文件

• 代码生成器集成进 layotto make 脚本

• 在 make 脚本里自动 install protoc 插件

• 写个文档介绍 proto 编写规范、代码生成器用法

[seeflood]

Now the code generator has been merged.
Future works are recorded at:
https://github.com/seeflood/protoc-gen-p6/issues