使用 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/proto/[email protected]

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

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

配置 git config

git config --global url."[email protected]".instead of "http://git.mycompany.com"
git config --global url."[email protected]".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 管理（1） - 使用规范

前言