[RFC] About how to import *.proto files in different SDK of openSergo | 关于如何在 SDK 项目中比较方便地引用 proto

[jnan806]

现在 OpenSergo 正在快速推进中, 越来越多的 proto 文件会加入到项目中。
因此需要考虑如何去组织 opensergo/opensergo-proto 项目，使能在异构语言 SDK 以及不同功能模块的中能便捷的引入 proto 文件进行开发。

关于 SDK如何引用proto，我总结为两种模式：

• SDK引用proto文件，自己根据proto文件生成stub存根
• SDK引用stub存根，这些stub存根已经提前生成好并且发布到依赖库中

---

针对这个问题，有多种解决方案。

方案一：

模式："SDK引用stub存根模式"

如图所示，

• 将 *.proto文件移动至 /grpc目录下，作为grpc协议的公用内容
• 添加各语言的stub(存根)模块，
  - grpc-java ： 提供给opensergo-java-sdk 的 基于 grpc 协议的 stub模块
  - grpc-golang : 提供给opensergo-go-sdk 的 基于 grpc 协议的 stub模块
  - grpc-[其他语言]
• 在.github/workflows目录下编写脚本，在提交或者某个时刻触发部署，各语言根据 *.proto文件生成对应的stub代码，然后各自打成 stub依赖包，发布到中央仓库中
  - java 打成 jar 包，发布到 maven 仓库
  - golang 打成 mod 组件，发布到 github (建议单独创建opensergo-go组织作为go仓库，发布go相关组件)
• 各语言sdk或模块依赖对应的 stub进行开发
• 各生态组件依赖对应的 sdk进行开发

---

如果新增其他通讯协议，可以按照这个结构继续扩展，以xds为例

opensergo-proto
    | -- gpc
    | -- grpc-java
    | -- grpc-golang
    | -- grpc-[其他语言]
    | -- xds
    | -- xds-java
    | -- xds-golang
    | -- xds-[其他语言]

或者单独抽出独立的协议模块，以xds为例

opensergo-proto  (建议改成 opensergo-protocol-grpc)
    | -- grpc
    | -- grpc-java
    | -- grpc-golang
    | -- grpc-[其他语言]

opensergo-protocol-xds
    | -- xds
    | -- xds-java
    | -- xds-golang
    | -- xds-[其他语言]

[jnan806]

方案二：

模式："SDK引用proto文件模式"

利用git的git submodules功能，在SDK中引入opensergo/opensergo-proto项目，这样就可以直接引用proto文件。

优点：
1). 集成比较简单，只需要在git中添加submodules即可
2). SDK的目录结构比较清晰

缺点：
1). 需要在SDK中时常更新proto子模块，并且SDk中每次更新完proto子模块就需要重新生成 相关 gRpc代码
2). git submodules只能指定子模块的branch不能指定tag （这一点问题比较大）

[jnan806]

方案三： （来自OpenSergo双周会社区同学的提议）

模式：“SDK引用proto文件模式”

使用开源社区 https://github.com/bufbuild 的 https://github.com/bufbuild/buf 项目

关于 bufbild我简单概括下大致功能与步骤：

主要是用于方便快速生成proto文件不同语言的stub存根

• 本项目：
  1). 安装bufbuild软件
  2). 编写proto文件，并且发布到 bufbuild的BSR(类似NPM,Maven)
• SDk开发环境：
  1). 安装bufbuild软件
  2). 编写bufbuild执行所需的yml配置文件
  3). 执行bufbuild相关命令，编译生成stub存根

优点（基于本社区考虑）：
1). 拥有BSR机制(类似NPM,Maven)，能够处理proto文件中对第三方proto的依赖问题 （方案一和方案二均没有很好地解决第三方proto依赖问题）

缺点（基于本社区考虑）：
1). 对于本社区各个SDk的贡献者而言，需要额外了解并且更够使用bufbuild

---

我的改进思路：
结合方案一，实现 “SDK引用stub存根模式”

思路：主要利用bufbuild的依赖管理以及stub代码生成功能。

具体实现：通过github 的 workflow将proto对应的stub生成并输出到方案一中提及的各语言stub模块，而后将stub模块发布到远程仓库中。
对于没有远程仓库的语言的SDK，则采用方案三的“SDK引用proto文件模式”

[iamharvey]

也可以考虑做一个用于初始化opensergo application的CLi工具，比如：

opensergo init 

或

opensergo new app1

这个初始化项目的过程中，下载proto文件到本地，存根还是在本地通过protoc生成

对于SDK而言，及时同步proto版本还是很有必要的，而且还可以根据需要对其进行扩展，保持SDK的适度可扩展性。

[jnan806]

初步集成 buf/builddemo版本(集成buf.build,并且proto与stub分离版本)， 相关项目如下：

• proto文件管理项目: jnan806/opensergo-proto 的 buf.build 分支
• proto仓库：https://buf.build/opensergo (建议chrome浏览器，部分浏览器显示有bug)
• stub code生成发布平台: jnan806/opensergo-grpc-stub
• stub code应用项目:
  1. opensergo-grpc-java : jnan806/opensergo-java-sdk-review-sczyh30 的 buf.build-based-sczyh30 分支
     注意：在编译 jnan806/opensergo-java-sdk-review-sczyh30 时，应先将opensergo-grpc-stub中的opensergo-grpc-java本地安装mvn install
  2. opensergo-grpc-go : jnan806/opensergo-go-sdk 的 dependency_of_opensergo-protocol-grpc-go 分支
  3. opensergo-control-plane : jnan806/opensergo-control-plane 的 buf.build-based-initial_version 分支

[jnan806]

detail refer to #5