04-无人售货柜多端分支策略后端微服务、安卓固件、小程序独立分支管理一、三端为什么要独立分支管理上一篇讲了通用的Git Flow分支模型。但落到无人售货柜这种多端项目上有一个绕不开的问题三端的代码仓库都不在一起发版节奏也不同怎么协调先看三端的基本情况维度SaaS后端安卓工控固件微信小程序技术栈SpringCloud Java安卓 Kotlin/C微信小程序 TypeScript仓库vending-backendvending-firmwarevending-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/OpenAPIRelease分支创建时通知安卓固件和小程序团队附带接口变更清单Master每次合并打Tag格式v{major}.{minor}.{patch}-backend2.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.yamlopenapi: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的小程序版本主版本majorAPI发生不兼容变更时升级如/api/v1/变成/api/v2/三端必须同步升级次版本minor新增功能但向下兼容后端先升级固件和小程序按需跟进修订版本patchBug修复各端独立升级即可3.3 版本对齐检查清单每次后端Release分支创建时执行版本对齐检查检查项负责人状态接口契约文件已更新后端☐接口变更清单已通知固件和小程序后端☐固件已拉取最新契约并完成适配固件☐小程序已拉取最新契约并完成适配小程序☐三端联调环境部署完成运维☐联调测试用例全部通过测试☐四、跨端联调的分支协调方案4.1 联调环境与分支映射联调环境固定使用三端的Develop分支部署环境后端固件小程序dev日常联调develop分支develop分支develop分支staging预发布release分支release分支release分支prod生产master Tagmaster Tagmaster 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自动化部署 灰度发布策略用流程和工具代替人工提醒这套方案不是理论模型是我们在无人售货柜项目实战中反复打磨出来的。刚开始会觉得流程重但一旦团队磨合到位你会发现——版本冲突这种事再也不用靠谁记得通知谁了流程会替你兜住。 04-无人售货柜多端分支策略：后端微服务、安卓固件、小程序独立分支管理
04-无人售货柜多端分支策略后端微服务、安卓固件、小程序独立分支管理一、三端为什么要独立分支管理上一篇讲了通用的Git Flow分支模型。但落到无人售货柜这种多端项目上有一个绕不开的问题三端的代码仓库都不在一起发版节奏也不同怎么协调先看三端的基本情况维度SaaS后端安卓工控固件微信小程序技术栈SpringCloud Java安卓 Kotlin/C微信小程序 TypeScript仓库vending-backendvending-firmwarevending-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/OpenAPIRelease分支创建时通知安卓固件和小程序团队附带接口变更清单Master每次合并打Tag格式v{major}.{minor}.{patch}-backend2.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.yamlopenapi: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的小程序版本主版本majorAPI发生不兼容变更时升级如/api/v1/变成/api/v2/三端必须同步升级次版本minor新增功能但向下兼容后端先升级固件和小程序按需跟进修订版本patchBug修复各端独立升级即可3.3 版本对齐检查清单每次后端Release分支创建时执行版本对齐检查检查项负责人状态接口契约文件已更新后端☐接口变更清单已通知固件和小程序后端☐固件已拉取最新契约并完成适配固件☐小程序已拉取最新契约并完成适配小程序☐三端联调环境部署完成运维☐联调测试用例全部通过测试☐四、跨端联调的分支协调方案4.1 联调环境与分支映射联调环境固定使用三端的Develop分支部署环境后端固件小程序dev日常联调develop分支develop分支develop分支staging预发布release分支release分支release分支prod生产master Tagmaster Tagmaster 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自动化部署 灰度发布策略用流程和工具代替人工提醒这套方案不是理论模型是我们在无人售货柜项目实战中反复打磨出来的。刚开始会觉得流程重但一旦团队磨合到位你会发现——版本冲突这种事再也不用靠谁记得通知谁了流程会替你兜住。