单模块结构在项目初期看似省事，但会引发依赖冲突、构建粒度失控和权限边界模糊三大硬伤；Go Modules本就支持“每个可发布单元一个go.mod”，强行统一违背其设计初衷。
为什么不能只用一个 go.mod 管理整个项目
单模块结构在项目初期看似省事，但一旦业务线变多、团队分工细化，就会暴露三个硬伤：依赖冲突（比如 cmd/app1 需要 github.com/some/lib v1.5，而 cmd/app2 必须用 v2.0）、构建粒度失控（改一个内部工具包，却要重编所有服务）、权限边界模糊（pkg/utils 被误当成私有包直接调用，破坏封装）。Go 的模块机制本就支持「每个可发布单元一个 go.mod」，强行塞进一个模块，等于放弃 Go Modules 的核心价值。
replace 不是临时补丁，而是本地模块协作的必经路径
当 cmd/app1 依赖 internal/service，而后者又尚未发布到远程仓库时，直接 go get 会失败。此时必须在 cmd/app1/go.mod 中显式声明：
replace example.com/myproject/internal/service => ../internal/service
注意几个关键点：
-
replace的路径必须是相对当前go.mod文件的文件系统路径，不是导入路径 - 被替换的模块（如
example.com/myproject/internal/service）自身也必须有独立的go.mod，且module声明需与replace左侧完全一致 - 上线前必须删掉
replace，改用真实版本号（如require example.com/myproject/internal/service v0.3.1），否则 CI 构建会失败
哪些目录该有自己的 go.mod，哪些不该
判断标准只有一个：是否具备「独立构建、独立发布、独立版本演进」的能力。具体来说：
立即学习“go语言免费学习笔记（深入）”；
-
cmd/xxx：必须有，每个可执行程序都是独立交付物 -
pkg/xxx：必须有，目标是供外部项目go get，需定义清晰的 API 和语义化版本 -
internal/xxx：建议有，即使不对外发布，也能锁死其依赖、避免被意外 import 到项目外 -
api/或config/：不该有，它们只是数据或定义，不包含可编译的 Go 代码 - 根目录：可以没有，除非你真要把它当作一个“聚合模块”发布（极少必要）
常见错误是给 internal 目录加了 go.mod，但里面包的导入路径仍写成 myproject/internal/service —— 这会导致 Go 工具链无法识别为模块内路径，报 cannot find module providing package。
CI 构建时如何避免本地 replace 污染生产环境
CI 流水线里最常踩的坑，就是把开发机上写的 replace 带进了镜像。解决方法很直接：
- 所有
replace只允许出现在cmd/或pkg/子模块的go.mod中，绝不允许出现在根目录或internal/模块里 - CI 构建前，先运行
go list -m all | grep 'replace'，非零退出即告警 - 对
cmd/app1这类主模块，CI 使用cd cmd/app1 && go build -mod=readonly，强制拒绝任何go.mod修改
真正难处理的从来不是怎么拆模块，而是模块间接口的稳定性 —— 一旦 internal/service 的某个函数签名变了，所有依赖它的 cmd/ 都得同步改。所以比模块划分更早该做的是：用 interface 定义契约，把实现细节关进 internal 的门里。
