go mod init 模块路径必须与远程仓库URL一致，单体项目仅允许一个根go.mod，慎用replace（尤其本地路径），internal仅对跨模块有效，MVS不保证最新版本。
go mod init 时模块路径必须和代码仓库路径一致
模块路径写错会导致后续所有依赖解析异常，比如本地开发时用 go mod init myproject，但实际仓库地址是 github.com/org/myproject，那么其他团队成员 import 时会因路径不匹配而无法解析包，go build 直接报 cannot find module 错误。
实操建议：
- 初始化前先确认远程仓库 URL，用完整路径执行：
go mod init github.com/org/myproject - 如果已初始化错误，别手动改
go.mod中的module行——先删掉go.mod和go.sum，再重新go mod init - CI/CD 流水线中应校验
go list -m输出是否与 Git remote URL 的路径部分完全一致
大型单体项目中不要在根目录下放多个 go.mod
常见错误是为不同子服务（如 /user、/order）各自运行 go mod init，导致项目里出现多个模块。Go 工具链会把它们当成独立模块处理，跨目录 import 时可能触发 require 冲突或版本不一致，go test ./... 也会漏掉某些路径。
正确做法是整个单体项目只保留一个根 go.mod，子目录通过目录结构自然形成子包路径（如 github.com/org/myproject/user），所有内部依赖走相对路径引用。
例外情况只有两种：需要独立发布为 SDK 的 /pkg 目录；或明确要隔离构建的 /cmd/admin 这类可执行入口——这时才在对应目录下加 go.mod，并用 replace 指向主模块本地路径。
慎用 replace，尤其是指向本地路径的 replace
replace 是临时调试利器，但上线前没清理会导致构建不可复现。典型问题是：开发时用 replace github.com/org/lib => ../lib 调试，结果 go build 在 CI 上失败，因为 CI 环境根本没有 ../lib 这个路径。
安全用法：
- 仅在
go.mod里声明，不提交到主分支；CI 流水线中用go mod edit -dropreplace=xxx清除 - 指向远程 commit hash 或 tag 更稳妥，例如：
replace github.com/org/lib => github.com/org/lib v1.2.3 - 绝对避免
replace指向./或../——这类路径在 vendor 或远程构建时必然失效
internal 目录不是万能隔离层，得配合模块路径设计
很多人以为只要把代码放进 /internal 就能阻止外部引用，但 Go 编译器只检查导入路径是否含 /internal/ 字符串。如果模块路径是 example.com/app，而你建了 example.com/app/internal/utils，那其他模块仍可通过 import "example.com/app/internal/utils" 引入——只要路径合法，编译器不会拦。
真正起作用的是：模块路径本身不能以 /internal/ 结尾，且所有 internal 子目录必须位于该模块根目录下。也就是说，internal 隔离只对“跨模块”有效，对同一模块内的包无效。
所以大型单体里，要把真正不想被外部调用的逻辑，放进和主模块同级的 /internal 下（如 github.com/org/myproject/internal/auth），而不是放在某个子包自己的 internal 里。
最常被忽略的一点：MVS（最小版本选择）算法在依赖树很深时可能选中一个看似“旧”但满足所有约束的版本，它不保证是最新的，也不保证是语义上最兼容的——有时候你需要显式 require 一个中间版本来打破冲突链，而不是盲目 go get -u。
