Protream's Notes

Go 模块是Go 语言的依赖管理系统,它从 Go 1.11 版本开始引入。本文讲解 go mod 的使用细节。

基本命令

初始化模块

在项目根目录下运行:

go mod init [module-path]

这会创建一个go.mod文件。[module-path]通常是你的代码仓库地址,如"github.com/yourusername/yourproject"。

添加依赖

当你在代码中import一个外部包时,只需运行:

go get [package-name]

或者直接运行:

go mod tidy

这会自动下载依赖,并更新go.mod文件。

升级/降级依赖

要升级到最新版本:

go get -u [package-name]

指定版本

go get [package-name]@[version]

复制依赖到本地

go mod vendor

清理模块缓存

go clean -modcache

go mod tidy

go mod tidy是Go模块系统中一个非常有用的命令,它可以自动管理你的项目依赖。这个命令主要做以下几件事:

1. 添加缺失的依赖:
   • 它会分析你的源代码,找出所有被引用但尚未在go.mod文件中列出的包。
   • 然后,它会自动下载这些包,并将它们添加到go.mod文件中。
2. 移除未使用的依赖:
   • 它会检查go.mod文件中列出的所有依赖,看是否在代码中被实际使用。
   • 如果发现某个依赖没有被使用,它会从go.mod文件中移除该依赖。
3. 更新go.sum文件:
   • go.sum文件包含了所有依赖的加密哈希值,用于验证下载的包的完整性。
   • go mod tidy会更新这个文件,确保它与当前的依赖列表匹配。

go.mod

一个典型的 go.mod 文件可能看起来像这样：

module github.com/username/project

go 1.16

require (
    github.com/gin-gonic/gin v1.7.4
    github.com/go-sql-driver/mysql v1.6.0
)

replace github.com/user/project => ../project

exclude github.com/user/project v1.10.0

retract v1.0.0

组成

模块声明

• 这通常是文件的第一行。
• 格式：module <module-path>
• 例如：module github.com/username/project

Go 版本声明

• 指定模块的 Go 语言版本。
• 格式：go <version>
• 例如：go 1.16

依赖项声明

• 列出模块的直接依赖。
• 格式：require <module-path> <version>
• 例如：require github.com/gin-gonic/gin v1.7.4

替换指令

• 用于替换依赖的来源或版本。
• 格式：replace <old-module-path> => <new-module-path>
• 例如：replace github.com/user/project => ../project

排除指令

• 用于排除某个依赖的特定版本。
• 格式：exclude <module-path> <version>
• 例如：exclude github.com/user/project v1.10.0

retract 指令（Go 1.16+）

• 用于指定获取依赖时的重试策略。
• 格式：retract <version> 或 retract [<version>, <version>]
• 例如：retract v1.0.0
• retract指令不会物理删除代码或标签,它只是一个警告机制。
• 使用go get或go mod tidy时,Go工具会避免选择被retract的版本。

替换指令的使用场景

本地开发和测试

• 场景: 你正在开发一个依赖库,同时也在开发使用该库的主项目。
• 使用: 你可以使用replace将依赖指向本地文件系统的路径。
• 示例:

replace github.com/myuser/mylib => ../mylib

• 好处: 允许你在本地修改库代码并立即在主项目中测试,而无需推送到远程仓库。

使用未发布的版本

• 场景: 你需要使用某个依赖的最新开发版本,但该版本还未正式发布。
• 使用: 可以将依赖指向特定的git commit。
• 示例:

replace github.com/user/project => github.com/user/project@commit-hash

• 好处: 能够使用和测试最新的功能或修复。

依赖分叉(Fork)

• 场景: 你fork了一个项目并做了修改,想在你的项目中使用这个修改后的版本。
• 使用: 将原依赖替换为你fork的版本。
• 示例:

replace github.com/original/repo => github.com/youruser/repo v1.0.0

• 好处: 可以使用自定义的或修复bug的fork版本。

版本兼容性问题

• 场景: 项目的某个依赖与另一个依赖不兼容。
• 使用: 可以replace到一个兼容的版本。
• 示例:

replace golang.org/x/crypto v1.4.5 => golang.org/x/crypto v1.4.0

• 好处: 解决依赖冲突,确保项目可以正常构建。

私有模块

• 场景: 你需要使用一个私有仓库中的模块。
• 使用: 可以replace到一个可访问的地址。
• 示例:

replace github.com/company/privatemodule => gitlab.com/company/privatemodule v1.0.0

• 好处: 允许使用私有模块,同时保持go.mod文件的通用性。

临时修复

• 场景: 依赖库中有一个bug,但维护者还没有修复。
• 使用: 可以replace到一个包含修复的临时分支。
• 示例:

复制

replace github.com/user/project => github.com/youruser/project@bugfix-branch

• 好处: 快速应用修复,而不必等待官方更新。