必须拆多个module仅当满足特定条件：子模块需被外部直接import并独立发版、构建产物或ci流程隔离、团队按模块协作、或存在不可调和的版本冲突；replace仅限本地调试，禁止提交生产，且须配合go mod tidy在根目录及各子模块分别执行以确保依赖一致。
大型 Go 项目里模块依赖混乱、版本不一致、本地开发时子模块改了却没生效——这些问题根源不在工具链，而在 go.mod 的组织逻辑和 replace 的使用边界没理清。
什么时候必须拆多个 module？
不是“代码多了就拆”，而是满足以下任一条件才值得引入多 module 结构：
- 某个子模块（比如
pkg/auth）要被外部项目直接import，且需独立发版（如v1.2.0） -
cmd/service-a和cmd/service-b构建产物不同、部署方式不同、CI 流程隔离 - 团队按模块分组协作，要求
service/user的 PR 不触发service/order的测试 - 某模块依赖旧版
golang.org/x/net，而其他模块需新版，单go.mod无法满足
如果只是想“分目录”，用 internal/ + 单 module 就够了；硬拆反而增加 replace 维护成本。
replace 指令只该用在本地开发阶段
replace 是临时桥接手段，不是长期依赖方案。它只在你本地调试时把远程路径映射到本地文件系统，CI 或生产构建时不会生效。
- 根目录
go.mod中写replace github.com/yourorg/pkg => ./pkg，但发布前必须删掉这行，否则别人go mod download会失败 - 子模块自己的
go.mod里禁止写replace—— 它应声明真实依赖，比如require github.com/sirupsen/logrus v1.9.0 - 若子模块 A 依赖子模块 B，A 的
go.mod应写require yourorg/project/pkg v0.0.0，而非replace，靠根目录统一管理映射
常见错误：go build 成功但 docker build 失败，往往是因为 Dockerfile 里没运行 go mod tidy 清掉 replace 后的真实依赖。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
internal 包和 module 边界必须对齐
internal 的可见性规则由 Go 编译器强制执行，但它只认文件系统路径，不认 module 名。如果模块划分和 internal 目录错位，会导致意外可导入或编译报错。
- 正确：模块
myproject/service/user下有internal/db，只有该模块内代码能 importmyproject/service/user/internal/db - 错误：把
internal/db放在根目录，然后让service/user和service/order都去 import —— 这违反了 internal 设计初衷，也容易引发循环依赖 - 更隐蔽的坑：两个 module 共享同一
internal/util目录，结果一个 module 升级了 util 函数签名，另一个没同步，CI 里go test ./...看似通过，运行时报 panic
结论：每个 module 应有自己的 internal，跨 module 共享逻辑必须抽成独立 module 放 pkg/，走标准 require 引入。
go mod tidy 必须在根目录和子模块分别执行
go mod tidy 不会自动递归处理子模块，它只作用于当前目录下的 go.mod。忽略这点，会导致依赖版本不一致或 go.sum 校验失败。
- 开发时：改完
pkg/utils后，在pkg/utils目录下跑一次go mod tidy，更新其go.sum - 集成前：回到根目录，再跑一次
go mod tidy，确保所有replace映射后的依赖被统一解析 - CI 流水线中：建议显式指定
GO111MODULE=on，并在每个 module 目录下单独go build，避免依赖污染
最常被跳过的环节是子模块的 go mod tidy —— 它不报错，但会让 go.sum 里残留旧校验和，导致不同环境构建结果不一致。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
