独立 Go 服务迁进 monorepo:先定平面,再瘦 shared

独立 Go 服务迁进 monorepo:先定平面,再瘦 shared

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 面爆炸,无法按层回滚

可复述硬规则(删掉比喻也成立):

  1. 先定平面:对公 HTTP、服务间 RPC、异步消息、第三方 webhook / WebSocket——迁仓不改语义平面。
  2. 共享只放真正跨服务稳定的东西;业务生成物与领域模型留在各服务模块。
  3. 写清非目标,防止迁仓变成架构革命。

心智模型:合租公寓

各服务是带门锁的房间;shared/ 是客厅公用家具——只有人人都用、且合同稳定的东西才配进客厅。

独立仓迁入 monorepo:各服务是带门锁的房间,shared 是客厅公用家具
独立仓迁入 monorepo:各服务是带门锁的房间,shared 是客厅公用家具 · 点击查看 SVG 原图
公寓零件对应什么合仓时别做什么
带门锁的房间独立 go.mod 的服务模块为「统一」拆掉门锁、强行单 module 巨仓(除非团队真的小且接受边界模糊)
客厅家具配置脚手架、错误码、日志、通用中间件、唯一的 RPC / IDL base把某房间的沙发(业务 stub、领域 DTO)搬进客厅
物业门牌规则跨服务 IDL / 契约约定用门牌规则去改临街橱窗的接线方式
临街橱窗对公 HTTP / OpenAPI不必改成和内线电话(RPC)同一套 codegen 流水线

类比局限:合租公寓管 边界与共享面;解释不了「这个服务该不该拆、该不该上新框架」——产品与架构选型另开讨论,别塞进「搬家 PR」里一起吵。


硬规则:三件事先写进迁仓文档

迁仓文档第一章就该能被外人读懂:要什么、不要什么、平面怎么分。

  1. 目标(举例,按你的场景裁剪)
    统一工具链;共享稳定基建;本地 go.work 一次打开多服务;CI 只维护一条主路径。

  2. 非目标(防范围蠕变——写进文档比写进群聊有效)

    • 不对 BFF / 对公 HTTP 上「全量 IDL 注解 codegen」;
    • 不把所有生成代码中央化到 shared/;
    • 不借迁仓换 RPC 框架或重写对外 API。
  3. 四平面(下一节展开)
    每个入口标属于哪一平面;迁目录、改 module 路径时,语义合同不变。

没有非目标的迁仓计划,很容易在 review 里被问成:「那顺便把 HTTP 也 codegen 了吧?」——答不上来就会默认答应。


四平面:迁仓不改语义合同

合仓改的是「代码住哪、谁跟谁共用基建」,不是「对外还算不算 HTTP、对内还算不算 RPC」。

四平面:对公 HTTP、服务间 RPC、异步消息、第三方 webhook 与 WebSocket
四平面:对公 HTTP、服务间 RPC、异步消息、第三方 webhook 与 WebSocket · 点击查看 SVG 原图
平面职责(人话)迁仓时默认态度
对公 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 白名单:允许基建与唯一 RPC base;禁止业务 DTO 与 per-service 生成物
shared 白名单:允许基建与唯一 RPC base;禁止业务 DTO 与 per-service 生成物 · 点击查看 SVG 原图
允许进 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. 旧仓只读归档;发布与密钥指向新路径后,再关旧流水线(约定切断日)

层序建议:

  1. 工具链可绿(不引入业务行为变化);
  2. shared 对齐(瘦接入,不顺便扩白名单);
  3. 服务目录迁入(平面标签跟着走);
  4. CI / 发布切流(旧路径有明确下线日)。

中间态优先:可编译、可测、可回滚。名义 monorepo 却长期双 CI,等于迁仓失败被日程表掩盖。


常见坑

多数事故不是「Go 语法」,而是共享面与平面被一起揉碎。

现象常见真相更稳的做法
改一个字段,三个无关服务 CI 全红业务 DTO 进了 shared撤回共享;合同留在所属服务
迁仓 PR 三千行还含新 RPC 框架搬家 + 架构革命绑死框架升级另开切片;迁仓 PR 只搬家
webhook / WS 路由「失踪」误以为 monorepo 只认 RPC按四平面登记入口;删除要显式审查
同名 base 修了 A 份、线上跑 B 份两套公共生成物并存合并为唯一 base;删除死副本
合仓半年仍双发布旧流水线没有切断日文档写死日期;密钥与镜像只指向新路径

反模式一句话:为统一而统一,比暂时不统一更贵。


选型结论

带走这五条就够和同事对齐:

  1. 迁仓文档第一章写清目标 / 非目标 / 四平面——没有非目标,范围必蠕变。
  2. 多服务 Go monorepo 默认 go.work + 多 module;shared 保持瘦;单 module 巨仓要显式接受代价。
  3. 生成代码:base 唯一;per-service 留守——禁止业务合同进客厅。
  4. 迁仓不改语义平面:对公 HTTP、RPC、消息、webhook / WS 各自保留合同。
  5. 按层合入,可回滚;旧 CI 有切断日——与分层 commit 审查切片同一套依赖序思维。

合仓成功的标志不是「目录都在一个 git 里」,而是:一套工具链、一块瘦共享面、平面合同还在、旧路径真的死了。