go.mod文件必须置于模块根目录且module路径须与import路径严格一致，否则报“cannot find module”；internal包仅限父级或同级导入，跨internal引用违反封装；多服务应各持独立go.mod以保障可发布性与演进独立性。
go.mod 文件必须放在模块根目录，且路径要与 import 路径一致
Go 模块的导入路径由 go.mod 中的 module 声明决定，不是文件系统路径。如果项目根目录下执行 go mod init myproject，但代码里写 import "github.com/yourname/myproject/internal/order"，就会报错 cannot find module providing package。
- 正确做法：初始化时用真实远程路径，例如
go mod init github.com/yourname/myproject - 错误常见于本地开发：把模块建在
~/dev/myproject，却用go mod init myproject—— 这会导致所有import语句失效 - 一旦
go.mod写入，就不能随意改module行；否则已有依赖（尤其本地replace）会断掉
避免在 internal/ 下直接 import 同一项目的其他 internal/ 包
Go 的 internal 机制靠编译器强制校验：只有父目录或同级子目录能导入 internal/xxx。若 cmd/api 和 cmd/worker 都 import internal/order 是合法的；但 internal/order import internal/payment 就违反了封装边界，也破坏了模块职责分离。
- 真正需要复用的逻辑应下沉到
pkg/目录，并导出明确接口 -
internal/应只包含“本模块专用”的实现细节，比如某个服务的 handler、repository、domain 层的具体结构体 - 跨业务域调用（如订单服务调支付服务）必须走 API 或 gRPC，而不是直接 import 对方
internal包
第三方依赖版本冲突时优先用 require + replace，而非间接升级
当两个不同模块都依赖 github.com/some/lib，但版本不兼容（比如 v1.2.0 vs v2.5.0），go mod tidy 会按最小版本选择（MVS）自动选一个版本，但可能引发运行时 panic —— 特别是涉及 go.sum 校验失败或接口变更时。
- 先运行
go list -m all | grep some/lib看实际选用版本 - 若需强制统一，用
require github.com/some/lib v2.5.0显式声明，再加replace github.com/some/lib => github.com/some/lib v2.5.0确保所有引用都走这个版本 - 慎用
indirect标记的依赖：它们是被子依赖带进来的，一旦上游模块删掉该依赖，你的构建就可能突然失败
多模块项目中，每个微服务应有独立 go.mod，而非共用顶层模块
把所有服务塞进一个大模块（比如 github.com/yourorg/backend），看似省事，但会导致：go mod tidy 时互相污染、发布版本无法单独控制、CI 构建粒度粗、无法按服务灰度升级依赖。
- 正确结构：每个服务目录下都有自己的
go.mod，例如services/order/go.mod、services/payment/go.mod - 公共库放
pkg/并发布为独立模块（如github.com/yourorg/pkg），其他服务通过require引入 - 本地开发调试时，用
replace github.com/yourorg/pkg => ../pkg指向本地路径，上线前删掉replace行
go.mod 路径、import 路径、CI 发布流程对齐。一旦这三者脱节，任何自动化工具都会开始报错。
