Go项目是否该拆模块取决于规模、协作与发布节奏；小项目硬拆增负担，大项目不拆致冲突；必须拆的三种场景：混用major版本路径、多团队发版周期不同、需独立发布SDK；拆分须满足三原则：独立go.mod且路径唯一、禁止跨internal依赖、v2+需显式改import路径；常见错误是混淆模块与包，导致路径重复、循环依赖或下载失败；验证方法包括go list、go mod graph和go get测试；模块名一旦发布不可轻易重命名或删除。
Go 项目是否该拆多个模块，取决于你的项目规模、团队协作方式和发布节奏——小项目硬拆反而增
go.mod 冲突、版本混乱和依赖传递失控。
什么时候必须拆模块（go module）
不是“想拆就拆”，而是遇到以下真实问题时，拆是唯一解：
-
go mod tidy报错类似require github.com/xxx/lib v1.2.0: version "v1.2.0" invalid: go.mod has post-v1 module path "github.com/xxx/lib/v2" at revision xxx—— 这说明你试图在同一个模块里混用不同 major 版本的路径，Go 不允许 - 团队中 A 组维护 API server，B 组维护 CLI 工具，两者共用一套内部工具函数，但发版周期完全不同：API 每周上线，CLI 每季度发一次。此时共享代码若不拆模块，
go.mod会强制 CLI 升级所有间接依赖，破坏稳定性 - 你想发布一个可被外部引用的 SDK（如
github.com/yourorg/sdk），但它的代码目前和主应用混在同一个仓库的internal/下，无法被go get独立拉取
模块拆分的三个硬性原则
Go 模块不是按功能目录随便切的，它本质是版本管理单元。拆之前先确认这三条是否满足：
- 每个模块必须有独立的
go.mod文件，且module声明路径需全局唯一（如module github.com/yourorg/core），不能是module core或相对路径 - 模块之间只能通过 import 路径依赖，禁止跨模块直接读写对方的
internal/目录（否则go build会报错use of internal package not allowed） - 如果模块 A 依赖模块 B，而 B 又发布了
v2，A 必须显式改 import 路径为github.com/yourorg/b/v2并更新go.mod—— Go 不支持语义化版本自动降级或升级
常见错误：把模块当包（package）来拆
很多人误以为 “多建几个 go.mod 就算模块化”，结果导致：
- 同一仓库内多个模块路径重复（如
github.com/yourorg/api和github.com/yourorg/api/v2同时存在，但没做 major 版本路径隔离） - 模块间循环依赖：A 模块 import B，B 模块又 import A 的某个子目录，
go build直接失败 - CI 构建时
go mod download失败，因为私有模块路径未配置GOPRIVATE，Go 默认走 proxy.golang.org 查找
正确做法是：先明确边界——哪些代码需要独立发版？哪些会被外部引用？哪些团队拥有完全控制权？只对满足任一条件的部分新建模块。
如何验证模块拆分是否合理
执行以下命令，结果全通过才算基本合格：
go list -m all | grep yourorg
看输出是否只包含你预期的模块路径（无意外嵌套或重复）；再试：
go mod graph | grep yourorg/core
确认依赖流向是单向的（core 不依赖 api，api 可依赖 core）；最后，在空目录下：
GO111MODULE=on go get github.com/yourorg/core@latest
能成功下载且不报 unknown revision 或 no matching versions，说明模块已可被外部消费。
最常被忽略的一点：模块名一旦发布到公共路径（哪怕只是公司内网 GitLab），就不能轻易重命名或删除——Go 的模块代理和校验和机制会让旧引用永久失效。拆之前，先想清楚这个模块未来三年会不会换名字、会不会合并进别的模块。
