多模块项目需明确模块边界，按业务领域拆分，如auth、payment等独立模块，每个模块有独立go.mod和版本演进，通过replace支持本地开发，CI中去除replace保证构建一致性，测试隔离，避免跨模块依赖，核心是清晰边界与团队共识。
Go 1.11 引入模块（module）后，单模块项目很清晰，但多模块项目（尤其是 monorepo 风格）需要主动设计结构和依赖策略——Go 本身不强制 monorepo 或 polyrepo，关键在于 模块边界是否清晰、版本是否可独立演进、构建与测试是否隔离。
明确模块边界：按领域/生命周期拆分，而非按技术层
一个常见误区是把 api/、service/、dao/ 拆成不同模块。这会导致循环依赖、发布耦合、语义版本失控。正确做法是：
- 每个模块代表一个有独立业务语义和发布节奏的组件，例如
github.com/yourorg/auth、github.com/yourorg/payment、github.com/yourorg/notifier - 模块内可自由组织包结构（如 internal、api、domain），但对外只暴露
public API（即非internal/下的导出符号） - 避免跨模块直接引用内部实现，通过接口抽象 + 依赖注入解耦；必要时用
go:generate或共享types模块（需谨慎）
monorepo 中的 go.mod 布局：根模块 + 子模块并存
在单一代码仓库中，可以同时存在多个 go.mod 文件，形成“模块森林”。典型布局如下：
myorg/ ├── go.mod # 根模块（可选，仅用于集成测试或工具链，不发布） ├── cmd/ │ └── app/ # 主程序，依赖多个子模块 │ ├── go.mod # module github.com/myorg/cmd/app │ └── main.go ├── auth/ │ ├── go.mod # module github.com/myorg/auth │ ├── api/ │ └── internal/ ├── payment/ │ ├── go.mod # module github.com/myorg/payment │ └── ... └── internal/ # 纯私有共享逻辑（无 go.mod），仅被同 repo 包引用
注意：子模块的 module path 必须是全局唯一且稳定（如 github.com/myorg/auth），不能用相对路径或本地别名；CI/CD 发布时，每个子模块可独立打 tag 并推送到对应路径。
立即学习“go语言免费学习笔记（深入）”；
管理跨模块依赖：用 replace + 本地开发，用 version + 远程发布
开发阶段频繁修改多个模块时，直接 go get 远程版本会卡住迭代。推荐组合策略：
- 在主应用（如
cmd/app/go.mod）中，用replace指向本地路径：replace github.com/myorg/auth => ../auth - 确保所有子模块
go.mod的require声明使用真实远程路径（如github.com/myorg/auth v0.3.1），而非本地路径 - CI 流水线中移除
replace（可用go mod edit -dropreplace），再go build和go test，保证环境一致性 - 发布新版本时，先
git tag -a v0.4.0 -m "auth: add oauth2 refresh"并 push，再在其他模块中go get github.com/myorg/auth@v0.4.0
测试与构建隔离：每个模块自包含测试，避免跨模块 test 依赖
模块的 go test 应能独立运行，不依赖其他模块的源码或二进制：
- 单元测试放在模块内（
auth/xxx_test.go），只测本模块逻辑 - 集成测试可单独建
tests/目录（带自己的go.mod），显式require多个模块，模拟真实调用链 - 禁止在
auth/中写import "github.com/myorg/payment"来测交互——应通过接口 mock 或启动真实服务（如用testcontainers-go） - CI 中可并行执行各模块的
go test ./...，加速反馈
基本上就这些。Go 的多模块不是靠工具自动管理，而是靠团队对边界和契约的共识。模块越小越灵活，但也越容易碎片化；建议从 3–5 个核心领域模块起步，随演进而拆，不为拆而拆。
