使用 gitlab 实现 proto 文件的 semantic version 管理(1) - 使用规范

前言

历史缘由我司的后端团队在同时使用 3 种语言：Python、Go、Java。为了实现团队的水平拆分和业务逻辑的收敛，咱们会在不一样的业务线间使用 unary 模式的 gRPC 来进行同步通讯。 例如报名业务中会存在一个查询某个用户全部报名记录的接口，这个接口是 Python 语言开发的，在不一样的业务场景上 Go、Java 都会调用这个接口。这就致使该接口的 protobuf 文件由 Python 开发者维护，同时 Go 和 Java 的 client 须要同步变动以使用最新版本的接口。一旦接口须要升级，协调 server 端有发布和升级，proto 文件仓库的变动，client 端变动发布就变成了一个很麻烦的事情。咱们须要一个方便透明的规范来协调各端。

一. 解决方案对比和选择

1. 可选方案

A. 在不一样的 server / client 代码项目中复制 proto 文件并各自生成
B. 使用 git submodule 使用同一个仓库的 proto 文件
C. 使用 semantic version 并使用第三方的方式管理 proto 文件

2. 损益分析

二. 如何建立新的 Proto 仓库

1. 建立新的 Proto 仓库

• 每一个后端项目对应新建一个 proto 仓库，proto 文件再也不跟项目代码放到一块儿。
• proto 三方仓库分 dev/master 两个分支；
• master 分支只能经过提 merge request 的方式提交新代码
• 全部 release 都从 master 打 tag 生成

2. Proto 语言文件的规范

• proto 文件遵循只增不减的原则
• proto 文件中的接口遵循只增不减的原则
• proto 文件中的 message 字段遵循只增不减的原则
• proto 文件中的 message 字段类型和序号不得修改

四. Proto 文件仓库的使用流程

1. Proto 文件仓库的修改

• 从 master 检出分支，feature/abc123，添加字段或者接口而后合并到 dev
• 从 dev 提 merge request 到 master 分支
• 合并 merge 以后稍等 3 分钟（gitlab CI 会自动生成各类语言的包并发布）就会获得一个版本号： v1.1.3243 （去 git.mycompany.com/proto/{project}/-/releases 查看发布的的版本）项目 、版本

2. 在各个语言的包管理工具中使用对应的 version 引用生成的 proto 文件

• 在 Go 项目中修改 go mod ，添加第三方依赖并指定版本

`
import (
gitlab.company.com/proto/abc v1.1.3243
)
`

• Python 使用 proto 项目对应版本

`
pip install https://gitlab.mycompany.com/...
`

• Java 直接使用私有 maven 仓库中的包和对应版本

3. Go mod 中 proto 包的 import 和使用

• 配置 git config

`
git config --global url."git@git.mycompany.com".instead of "http://git.mycompany.com"
git config --global url."git@git.mycompany.com".instead of "https://git.mycompany.com"
`

• 设置 Go 环境  

  • 升级 go 版本到 1.13 或以上版本
  • 配置环境变量：

`
GOPROXY="https://goproxy.io,direct"
            
GOPRIVATE="git.mycompany.com"
`

• 使用 go build -v  能够方便的排查和定位问题

---------------------------------EOF

相关文章：
使用 gitlab 实现 proto 文件的 semantic version 管理(2) - 配置 Gitlab CI 实现自动打包

使用 gitlab 实现 proto 文件的 semantic version 管理(3) - Go App 的 Dockerfile 配置