跳到主要内容

Module Manager（模块管理）

Go Modules 用 go.mod 描述模块路径、Go 版本和依赖，用 go.sum 保存下载内容的校验记录。模块是发布和构建边界，包是源码组织和可见性边界；两者都参与导入路径解析。

创建模块​

在项目根目录执行：

go mod init example.com/hello
go get golang.org/x/text@v0.16.0
go mod tidy

go mod tidy 会根据源码、测试和构建标签整理依赖。提交 go.mod 和 go.sum，不要手工改写校验和；依赖版本应通过审查后的命令更新。

版本选择与路径​

Go 使用语义化版本和最小版本选择（MVS）解析依赖图：主模块声明的最低直接依赖版本会与传递依赖一起参与选择。模块主版本大于 1 时，导入路径通常包含 /v2 等后缀；包名、模块路径和仓库 URL 不是同一个概念。

常用排查命令：

go list -m all
go mod graph
go mod why -m example.com/dependency
go mod verify

replace 适合本地开发或明确的临时分支；提交到生产构建前必须说明原因并有测试和移除计划。exclude、retract 和升级操作都应在变更记录中解释影响。

供应链与私有模块​

CI 应固定 Go 工具链、代理配置和依赖更新流程，审查新增依赖的维护状态、许可证、安全公告和传递依赖。私有模块需要配置 GOPRIVATE、代理和凭据，令牌不能写入 go.mod、日志或仓库。

常见错误​

  • 在错误目录执行 go mod init，使模块根目录与仓库结构不一致。
  • 只提交 go.mod 而遗漏 go.sum。
  • 用 replace 掩盖不兼容版本，却没有测试和迁移计划。
  • 把模块路径、包导入路径和文件夹名称当成同一个身份。
  • 只看直接依赖，忽略 MVS 选择的传递依赖和许可证风险。

Go Modules 与 npm 的 package.json/lockfile 有相似职责，但模块路径直接参与导入和版本解析，不能只凭目录名称推断身份。

小结​

  • go.mod 声明模块和依赖意图，go.sum 记录校验信息。
  • 用 go mod tidy 保持依赖与源码一致，用 go mod verify 校验下载内容。
  • 依赖管理同时是构建可复现和供应链安全问题。