go module是go官方推荐的依赖管理机制，需显式初始化、用go get精准控制版本、提交go.sum保障校验、多模块项目应分治且避免循环依赖。
Go Module 是 Go 语言官方推荐的依赖管理机制，自 Go 1.11 引入、Go 1.16 默认启用后，已成为现代 Go 项目的基础能力。用好它，能显著减少依赖冲突、提升构建可重现性、简化协作流程。
明确启用和初始化模块
新项目务必显式初始化模块，避免隐式 GOPATH 模式干扰：
- 在项目根目录执行 go mod init example.com/myapp，模块路径应体现真实代码归属（如公司域名或 GitHub 组织）
- 不建议使用本地路径（如 go mod init myapp），否则后续发布或他人引用时会出错
- 初始化后立即运行 go mod tidy，自动下载依赖、清理未使用项并生成 go.sum
精准控制依赖版本与替换
避免盲目升级或手动修改 go.mod 文件，优先使用 Go 命令驱动变更：
- 升级单个依赖：go get github.com/sirupsen/logrus@v1.9.3
- 降级或锁定版本：同样用 go get 指定具体 tag/commit，Go 自动更新 go.mod 和 go.sum
- 仅在必要时替换依赖（如调试 fork 分支）：go mod edit -replace github.com/old/pkg=github.com/new/pkg@main，随后 go mod tidy
- 慎用 replace 指向本地路径（如 ./local-fork），上线前必须移除，否则 CI 构建失败
保持 go.sum 可信且最小化干扰
go.sum 是依赖校验核心，不是“可选配置”：
- 提交 go.sum 到版本库——它保障所有人拉取相同二进制依赖，防止供应链投毒
- 不要手动编辑 go.sum；若校验失败，先确认网络/代理是否导致下载了错误包，再运行 go mod download 或 go mod verify 排查
- CI 环境中建议加 go mod verify 步骤，作为构建前完整性检查
合理组织多模块项目
大型项目拆分子模块时，避免“扁平化”陷阱：
- 每个子模块应有独立 go.mod，路径与其所在目录逻辑一致（如 api/go.mod 的 module 名为 example.com/myapp/api）
- 主模块通过 import 路径引用子模块（如 import "example.com/myapp/api"），而非相对路径
- 跨模块共享代码？优先提取为独立可复用模块（带完整版本号），而非用 replace 或 symlink
- 避免循环依赖：A 模块导入 B，B 又导入 A —— 编译直接报错，需重构接口或引入中间抽象层
依赖管理不是一劳永逸的设置，而是贯穿开发、测试、发布的持续实践。坚持命令驱动、版本显式、校验必提、模块分治，Go Module 就能真正成为效率杠杆，而不是半夜排查依赖问题的源头。
