使用 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 配置