
Hello,我是小兔大白糖。 团队已经有一个「多服务 monorepo」,外面还挂着一个独立 Go 仓——合进来似乎只是搬家:统一 lint、共用 errno / logger、IDL 对齐。真翻车的往往不是「目录没拷对」,而是把不该共享的合同塞进客厅,或把迁仓顺手做成一次架构革命。写成这篇,给要做 Go 多服务合仓 / monorepo 迁入选型 的初中级后端同学:不是某仓库的迁移动作清单,而是业界常见的心智模型与检查表。
说明:下文的「房间 / 客厅」「四平面」「shared 白名单」是教学框架,不是某厂官方规范。目录名(如
shared/、services/)为脱敏示意;不绑定具体仓库、厂商框架迁移动作墙或内部工单。
估计阅读时间:8 分钟
目录
为什么现在要关心
迁仓的目标是统一工具链与稳定共享面,不是借搬家重做整套对外协议。
独立仓挂在外面时,动机通常很实在:
| 你想要的 | 常见翻车点 |
|---|---|
| 统一 Makefile / lint / CI | 迁完仍两套流水线、两套 module,名义 monorepo |
| 共享 errno、logger、中间件 | 业务 DTO / 单服务生成物也塞进 shared/,一改全仓抖 |
| IDL / codegen 对齐 | 强行把对公 HTTP 改成和内部 RPC「同一套接线工单」 |
| 一处改、多服务受益 | 顺手上新 RPC 框架,review 面爆炸,无法按层回滚 |
可复述硬规则(删掉比喻也成立):
- 先定平面:对公 HTTP、服务间 RPC、异步消息、第三方 webhook / WebSocket——迁仓不改语义平面。
- 共享只放真正跨服务稳定的东西;业务生成物与领域模型留在各服务模块。
- 写清非目标,防止迁仓变成架构革命。
心智模型:合租公寓
各服务是带门锁的房间;shared/ 是客厅公用家具——只有人人都用、且合同稳定的东西才配进客厅。
| 公寓零件 | 对应什么 | 合仓时别做什么 |
|---|---|---|
| 带门锁的房间 | 独立 go.mod 的服务模块 | 为「统一」拆掉门锁、强行单 module 巨仓(除非团队真的小且接受边界模糊) |
| 客厅家具 | 配置脚手架、错误码、日志、通用中间件、唯一的 RPC / IDL base | 把某房间的沙发(业务 stub、领域 DTO)搬进客厅 |
| 物业门牌规则 | 跨服务 IDL / 契约约定 | 用门牌规则去改临街橱窗的接线方式 |
| 临街橱窗 | 对公 HTTP / OpenAPI | 不必改成和内线电话(RPC)同一套 codegen 流水线 |
类比局限:合租公寓管 边界与共享面;解释不了「这个服务该不该拆、该不该上新框架」——产品与架构选型另开讨论,别塞进「搬家 PR」里一起吵。
硬规则:三件事先写进迁仓文档
迁仓文档第一章就该能被外人读懂:要什么、不要什么、平面怎么分。
-
目标(举例,按你的场景裁剪)
统一工具链;共享稳定基建;本地go.work一次打开多服务;CI 只维护一条主路径。 -
非目标(防范围蠕变——写进文档比写进群聊有效)
- 不对 BFF / 对公 HTTP 上「全量 IDL 注解 codegen」;
- 不把所有生成代码中央化到
shared/; - 不借迁仓换 RPC 框架或重写对外 API。
-
四平面(下一节展开)
每个入口标属于哪一平面;迁目录、改 module 路径时,语义合同不变。
没有非目标的迁仓计划,很容易在 review 里被问成:「那顺便把 HTTP 也 codegen 了吧?」——答不上来就会默认答应。
四平面:迁仓不改语义合同
合仓改的是「代码住哪、谁跟谁共用基建」,不是「对外还算不算 HTTP、对内还算不算 RPC」。
| 平面 | 职责(人话) | 迁仓时默认态度 |
|---|---|---|
| 对公 HTTP | 给 App / Web / 合作方的同步接口;常见 OpenAPI 或手写路由 | 保留合同;不要为「仓库统一」强行改成内部 RPC 同款生成流水线 |
| 服务间 RPC | 内网调用、强类型 IDL、超时与错误码约定 | 对齐 唯一 base / 公共类型;各服务自己的 gen 留守本模块 |
| 异步消息 | 最终一致、削峰、解耦 | 主题名与载荷版本照旧;别在迁仓 PR 里顺便改语义 |
| 第三方 webhook / WebSocket | 回调入口、长连接入口 | 极易被误删:「monorepo 只认 RPC」是假规则 |
四平面可以共处同一服务进程,但审查问题不同:迁目录时先问「这个 handler 属于哪一平面」,再问「它该不该碰 shared/」。
代价先说清:坚持平面分离,短期会觉得「少统一了一点」;把平面揉碎换统一,长期是协议债和一次改坏全入口。
常见模式对比
多服务已经在 monorepo 里时,Go 侧常见默认是 go.work + 每服务独立 module;合入按层推进。
| 模式 | 做法 | 优点 | 代价 / 副作用 | 何时更合适 |
|---|---|---|---|---|
| A. 目录挪进来完事 | 拷到 services/,改 import 路径 | 最快看见绿构建 | 共享与 CI 仍分叉;名义合仓 | 应急、证明「能编过」 |
| B. go.work + 多 module | 根 workspace;每服务独立 go.mod;瘦 shared/ | 边界清楚;可按服务裁剪 CI | 要理清 replace / 版本策略并写进文档 | Go 多服务 monorepo 常见基线 |
| C. 单 module 巨仓 | 全仓一个 go.mod | 无 replace 心智负担 | 边界模糊;无关改动易拖慢 CI / 测试 | 小团队、短中期、服务很少 |
| D. 仓外发共享库 | 服务仍独立仓,抽 versioned lib | 发布边界极强 | 版本协调税;破坏性改要多仓 bump | 服务边界极强、合仓政治成本高 |
教学倾向:宿主已是多服务 monorepo → 优先 B;用 A 只做探针,用 C 要团队书面接受「边界靠约定不靠 module」。D 不是失败,是另一条产品线——别把「发版共享库」和「合进 monorepo」混成同一个 PR 目标。
shared 白名单:能进客厅的才进
进 shared/ 的默认标准:跨 ≥2 个服务使用,且合同变更频率低、变更时愿意全仓一起抖。
| 允许进 shared(示意) | 禁止进 shared(示意) |
|---|---|
| 日志、错误码、通用中间件、配置脚手架 | 某业务领域的 DTO / 聚合根 |
| 唯一的 RPC / IDL base(公共元数据、基础错误类型等) | kitex_gen/<svc>、*_gen/<svc> 一类 per-service 生成树 |
| 真正跨服务的小工具(且无业务语义) | 「说不定别的服务以后会用」的预共享 |
硬规则人话:base 唯一;per-service 生成物留守。 两套 base 并存时,修 bug 改错份是确定性事故,不是小概率。
代价:shared 保持瘦,意味着有时要在两个服务里复制一小段「看起来像样板」的代码——这通常比错误共享更便宜。共享的副作用是耦合税:任何合同变更的 blast radius 变成全仓。
按层合入检查清单
按层合入 = 先工具链与 shared,再搬服务目录,最后切断旧 CI——每层可回滚。
这和「大变更按层拆 commit」同构:一层只回答一个审查问题。可对照:大变更按层拆 commit:一个审查问题一层。
教学检查表(脱敏伪流程,非某仓库 runbook):
1. 根 Makefile / lint / CI 能 build 新服务路径
2. go.work 纳入新 module;replace / 版本策略写进文档
3. 共用:logger / errno / mw;不共用:业务 gen、领域模型
4. 对公 OpenAPI / 手写 HTTP 保留;服务间走 RPC / 消息
5. 删未注册的生成物与死路由——不要「全部带着迁」
6. 旧仓只读归档;发布与密钥指向新路径后,再关旧流水线(约定切断日)层序建议:
- 工具链可绿(不引入业务行为变化);
- shared 对齐(瘦接入,不顺便扩白名单);
- 服务目录迁入(平面标签跟着走);
- CI / 发布切流(旧路径有明确下线日)。
中间态优先:可编译、可测、可回滚。名义 monorepo 却长期双 CI,等于迁仓失败被日程表掩盖。
常见坑
多数事故不是「Go 语法」,而是共享面与平面被一起揉碎。
| 现象 | 常见真相 | 更稳的做法 |
|---|---|---|
| 改一个字段,三个无关服务 CI 全红 | 业务 DTO 进了 shared | 撤回共享;合同留在所属服务 |
| 迁仓 PR 三千行还含新 RPC 框架 | 搬家 + 架构革命绑死 | 框架升级另开切片;迁仓 PR 只搬家 |
| webhook / WS 路由「失踪」 | 误以为 monorepo 只认 RPC | 按四平面登记入口;删除要显式审查 |
| 同名 base 修了 A 份、线上跑 B 份 | 两套公共生成物并存 | 合并为唯一 base;删除死副本 |
| 合仓半年仍双发布 | 旧流水线没有切断日 | 文档写死日期;密钥与镜像只指向新路径 |
反模式一句话:为统一而统一,比暂时不统一更贵。
选型结论
带走这五条就够和同事对齐:
- 迁仓文档第一章写清目标 / 非目标 / 四平面——没有非目标,范围必蠕变。
- 多服务 Go monorepo 默认 go.work + 多 module;shared 保持瘦;单 module 巨仓要显式接受代价。
- 生成代码:base 唯一;per-service 留守——禁止业务合同进客厅。
- 迁仓不改语义平面:对公 HTTP、RPC、消息、webhook / WS 各自保留合同。
- 按层合入,可回滚;旧 CI 有切断日——与分层 commit 审查切片同一套依赖序思维。
合仓成功的标志不是「目录都在一个 git 里」,而是:一套工具链、一块瘦共享面、平面合同还在、旧路径真的死了。