04-无人售货柜多端分支策略：后端微服务、安卓固件、小程序独立分支管理
04-无人售货柜多端分支策略：后端微服务、安卓固件、小程序独立分支管理
一、三端为什么要独立分支管理？
上一篇讲了通用的Git Flow分支模型。但落到无人售货柜这种多端项目上，有一个绕不开的问题：三端的代码仓库都不在一起，发版节奏也不同，怎么协调？
先看三端的基本情况：
| 维度 | SaaS后端 | 安卓工控固件 | 微信小程序 |
|---|---|---|---|
| 技术栈 | SpringCloud + Java | 安卓 + Kotlin/C++ | 微信小程序 + TypeScript |
| 仓库 | vending-backend | vending-firmware | vending-miniapp |
| 发布周期 | 每两周 | 每月（OTA推包） | 随时（审核1-2天） |
| 回滚成本 | 低（灰度切流） | 高（重新打包推包） | 中（重新提交审核） |
| 依赖关系 | 提供API契约 | 消费后端API | 消费后端API |
三端各自独立仓库，如果各管各的分支，不做版本对齐，就回到了第1篇讲的"版本冲突血案"——后端API变了，安卓固件不知道。
核心思路是：三端各自遵循Git Flow模型，但通过版本号对齐机制和跨端联调协议来协调。
二、三端独立仓库的分支模型
2.1 后端微服务仓库：vending-backend
后端是API的"契约提供方"，分支模型最严格：
master ●─────●─────●─────●─────● (Tag: v1.0.0 → v1.1.0 → v1.2.0) \ ↑ / ↑ / develop ●●●●●●●●●●●●●●●●●●●●●●●●●●● \ ↑ / ↑ / feature ●●●●●●● ●●●●●●● ↑ release ●●●●●●● (release/v1.2.0)后端关键规则：
- API变更必须走Feature分支，且在Feature分支中同步更新接口文档（Swagger/OpenAPI）
- Release分支创建时通知安卓固件和小程序团队，附带接口变更清单
- Master每次合并打Tag，格式
v{major}.{minor}.{patch}-backend
2.2 安卓工控固件仓库：vending-firmware
固件端是"协议消费者"，分支模型需要适配OTA推包的特殊性：
master ●─────●─────●─────● (Tag: v1.0.0-firmware → v1.1.0-firmware) \ ↑ / ↑ develop ●●●●●●●●●●●●●●●●●●●● \ ↑ / feature ●●●●●●● \ ↑ / hotfix ●●●●●●● (紧急修复，从master拉出)固件端关键规则：
- 固件版本号与后端API版本号绑定，Tag格式
v{major}.{minor}.{patch}-firmware，其中major版本与后端API大版本一致 - 固件Release分支必须基于后端已发布或已进入Release阶段的对应API版本
- 额外维护一个
hotfix分支通道，因为固件Bug往往需要紧急OTA推包，不能等下个迭代
2.3 微信小程序仓库：vending-miniapp
小程序相对灵活，但也要遵循规范：
master ●─────●─────●─────● (Tag: v1.0.0-miniapp → v1.1.0-miniapp) \ ↑ / ↑ develop ●●●●●●●●●●●●●●●●●●●● \ ↑ / feature ●●●●●●●小程序关键规则：
- 小程序发布走微信审核，不能像后端那样灰度，所以Release分支的测试必须更充分
- 小程序的API调用层做版本号协商：小程序启动时请求后端
/api/version接口，获取后端当前版本号，如果版本不兼容则提示用户更新小程序
三、版本对齐机制：三端怎么"对表"？
分支模型解决的是单端内部的管理问题，版本对齐解决的是跨端的协议匹配问题。
3.1 接口契约文件统一管理
在后端仓库中维护一份接口契约文件（推荐OpenAPI/Swagger格式），路径docs/api-contract.yaml：
openapi:3.0.0info:title:无人售货柜APIversion:1.2.0paths:/api/v1/door/open:post:summary:开门接口requestBody:content:application/json:schema:type:objectproperties:cabinet_id:type:stringdescription:货柜编号responses:'200':description:成功content:application/json:schema:type:objectproperties:code:type:integerdata:type:objectproperties:door_id:type:stringdoor_status:type:stringenum:[opened,closed]open_time:type:integerdescription:开门时间戳这份文件就是三端的"契约"。后端每次接口变更，修改这份文件，commit message中标注[API-CONTRACT]前缀。安卓固件和小程序团队通过CI流水线自动拉取这份文件，生成各端的API客户端代码。
3.2 版本号三段式对齐
采用主版本.次版本.修订版本的三段式版本号，三端各自维护但主版本号保持一致：
v1.2.0-backend → 后端v1.2.0正式版 v1.2.0-firmware → 适配后端v1.2.0的固件版本 v1.2.0-miniapp → 适配后端v1.2.0的小程序版本- 主版本（major）：API发生不兼容变更时升级，如
/api/v1/变成/api/v2/，三端必须同步升级 - 次版本（minor）：新增功能但向下兼容，后端先升级，固件和小程序按需跟进
- 修订版本（patch）：Bug修复，各端独立升级即可
3.3 版本对齐检查清单
每次后端Release分支创建时，执行版本对齐检查：
| 检查项 | 负责人 | 状态 |
|---|---|---|
| 接口契约文件已更新 | 后端 | ☐ |
| 接口变更清单已通知固件和小程序 | 后端 | ☐ |
| 固件已拉取最新契约并完成适配 | 固件 | ☐ |
| 小程序已拉取最新契约并完成适配 | 小程序 | ☐ |
| 三端联调环境部署完成 | 运维 | ☐ |
| 联调测试用例全部通过 | 测试 | ☐ |
四、跨端联调的分支协调方案
4.1 联调环境与分支映射
联调环境固定使用三端的Develop分支部署：
| 环境 | 后端 | 固件 | 小程序 |
|---|---|---|---|
| dev（日常联调） | develop分支 | develop分支 | develop分支 |
| staging（预发布） | release分支 | release分支 | release分支 |
| prod（生产） | master + Tag | master + Tag | master + Tag |
联调环境通过Docker Compose编排，一键拉起后端服务+模拟固件环境+Mock小程序，开发者本地即可联调。
4.2 跨端联调的标准流程
以一次接口变更为例：
第1步：后端创建feature/door-api-field-refactor分支 修改接口实现 + 更新api-contract.yaml 推送到远程 第2步：后端通知固件和小程序（通过MR Comment或企业微信通知） 附带接口变更说明和契约文件diff 第3步：固件拉取最新api-contract.yaml 基于develop拉出feature/firmware-door-api-adapt分支 使用Swagger Codegen生成新的API客户端代码 适配新字段 第4步：小程序同理拉出feature/miniapp-door-api-adapt分支 适配新接口 第5步：三个Feature分支同时合并到各自的develop分支 CI自动部署dev联调环境 第6步：三端在dev环境联调 后端调接口 → 固件解析返回值 → 小程序展示状态 联调通过后各自进入Release流程4.3 紧急修复的跨端协调
线上出Bug需要紧急修复时，流程如下：
后端从master拉bugfix分支 → 修复 → 合并master打Tag v1.2.1-backend ↓ 判断是否影响固件/小程序 ↓ ┌─── 是 ───┐ ┌─── 否 ───┐ ↓ ↓ ↓ ↓ 固件拉bugfix 小程序拉bugfix 仅后端发版 合并master 合并master 通知两端 Tag v1.2.1 Tag v1.2.1 无需动作 -firmware -miniapp关键原则：后端紧急修复后，必须评估是否影响下游端。如果接口返回值变了，固件和小程序必须同步修复；如果只是后端内部逻辑修复（如数据库SQL优化），不影响接口，则通知两端即可。
五、实战：完整一次三端发版的全流程
以v1.3.0版本发布为例，完整走一遍：
【W1 周一】迭代规划 - 后端：新增商品识别结果上报接口 - 固件：对接YOLO识别结果，调用新接口上报 - 小程序：商品识别结果展示页面 【W1-W2】各端开发 后端: feature/product-recognize-api (vending-backend仓库) 固件: feature/yolo-result-report (vending-firmware仓库) 小程序: feature/recognize-result-display (vending-miniapp仓库) 后端更新api-contract.yaml，通知两端 【W2 周四】Feature合并到Develop 三端各自合并到develop分支 CI自动部署dev环境，三端联调 【W2 周五】联调修复 发现固件上报的图片格式和后端预期不一致 固件在develop上直接修复（小改动），重新联调通过 【W3 周一】创建Release分支 三端各自从develop拉出release/v1.3.0 后端: release/v1.3.0 (vending-backend) 固件: release/v1.3.0 (vending-firmware) 小程序: release/v1.3.0 (vending-miniapp) 【W3 周二-周三】回归测试 测试团队在staging环境（Release分支部署）做全量回归 小程序提交微信审核（利用审核等待期做最终确认） 【W3 周四】发版 三端Release分支合并到master 打Tag: v1.3.0-backend / v1.3.0-firmware / v1.3.0-miniapp 后端灰度发布，固件OTA灰度推包（先推10台货柜） 小程序微信审核通过后发布 【W3 周五】版本对齐确认 确认线上三端版本号一致: v1.3.0 删除所有Release和Feature分支 开始下一迭代规划六、总结：多端分支管理的核心原则
回顾整个方案，核心原则就三条：
- 各自独立、统一模型：三端各自仓库，但都遵循Git Flow分支模型，保证单端内部的规范
- 契约驱动、版本对齐：用接口契约文件做三端的"协议纽带"，用版本号做"对表基准"
- 流程兜底、工具保障：版本对齐检查清单 + CI自动化部署 + 灰度发布策略，用流程和工具代替人工提醒
这套方案不是理论模型，是我们在无人售货柜项目实战中反复打磨出来的。刚开始会觉得流程"重"，但一旦团队磨合到位，你会发现——版本冲突这种事，再也不用靠"谁记得通知谁"了，流程会替你兜住。