2019 年 - 2019-03-19 使用 Go 模块 - 《开源翻译计划》

介绍
创建新模块
添加依赖
升级依赖
添加对新主要版本的依赖
将依赖项升级到新的主要版本
删除未使用的依赖项
总结

:::info 日期：2019 年 03 月 19 日
作者：Tyler Bui-Palsulich and Eno Compton
原文链接：https://go.dev/blog/using-go-modules :::

介绍

这篇文章是系列文章的第 1 部分

第 1 部分 - 使用 Go 模块（本文）
第 2 部分 - 迁移到 Go 模块
第 3 部分 - 发布 Go 模块
第 4 部分 - Go 模块：v2 及更高版本
第 5 部分 - 保持模块兼容

注意：有关使用模块管理依赖项的文档，请参阅管理依赖项。

Go 1.11 和 1.12 包括对模块的初步支持，Go 的新依赖管理系统使依赖版本信息明确且易于管理。这篇博文介绍了开始使用模块所需的基本操作。

模块是存储在文件树中的 Go 包的集合，在其根目录下有一个 go.mod 文件。 go.mod 文件定义了模块的模块路径，它也是用于根目录的导入路径，以及它的依赖项要求，这是成功构建所需的其他模块。每个依赖需求都被写成一个模块路径和一个特定的语义版本。

从 Go 1.11 开始，当当前目录或任何父目录有 go.mod 时，go 命令启用模块的使用，前提是该目录在 $GOPATH/src 之外。（在 $GOPATH/src 中，为了兼容性，即使找到了 go.mod，go 命令仍然以旧的 GOPATH 模式运行。有关详细信息，请参阅 go 命令文档。）从 Go 1.13 开始，模块模式将成为默认模式为所有的发展。

这篇文章介绍了在使用模块开发 Go 代码时出现的一系列常见操作：

创建一个新模块
添加依赖项。
升级依赖。
添加对新主要版本的依赖。
将依赖项升级到新的主要版本。
删除未使用的依赖项。

创建新模块

让我们创建一个新模块。

在 $GOPATH/src 之外的某处创建一个新的空目录，cd 进入该目录，然后创建一个新的源文件 hello.go：

package hello
func Hello() string {
    return "Hello, world."
}

让我们也在 hello_test.go 中编写一个测试：

package hello
import "testing"
func TestHello(t *testing.T) {
    want := "Hello, world."
    if got := Hello(); got != want {
        t.Errorf("Hello() = %q, want %q", got, want)
    }
}

此时，该目录包含一个包，但不包含模块，因为没有 go.mod 文件。如果我们在 /home/gopher/hello 中工作并现在运行 go test，我们会看到：

$ go test
PASS
ok      _/home/gopher/hello 0.020s
$

最后一行总结了整个包测试。因为我们在 $GOPATH 和任何模块之外工作，所以 go 命令不知道当前目录的导入路径，并根据目录名称创建一个假的：_/home/gopher/hello。

让我们使用 go mod init 将当前目录设为模块的根目录，然后再次尝试 go test

$ go mod init example.com/hello
go: creating new go.mod: module example.com/hello
$ go test
PASS
ok      example.com/hello   0.020s
$

恭喜！你已经编写并测试了你的第一个模块。

go mod init 命令写了一个 go.mod 文件：

$ cat go.mod
module example.com/hello
go 1.12
$

go.mod 文件只出现在模块的根目录中。子目录中的包具有由模块路径加上子目录路径组成的导入路径。例如，如果我们创建了一个子目录 world，我们就不需要（也不想）在那里运行 go mod init。该包将被自动识别为 example.com/hello 模块的一部分，导入路径为 example.com/hello/world。

添加依赖

Go 模块的主要动机是改善使用（即添加依赖）其他开发人员编写的代码的体验。

让我们更新我们的 hello.go 以导入 rsc.io/quote 并使用它来实现 Hello：

package hello
import "rsc.io/quote"
func Hello() string {
    return quote.Hello()
}

现在让我们再次运行测试

$ go test
go: finding rsc.io/quote v1.5.2
go: downloading rsc.io/quote v1.5.2
go: extracting rsc.io/quote v1.5.2
go: finding rsc.io/sampler v1.3.0
go: finding golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
go: downloading rsc.io/sampler v1.3.0
go: extracting rsc.io/sampler v1.3.0
go: downloading golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
go: extracting golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
PASS
ok      example.com/hello   0.023s
$

go 命令使用 go.mod 中列出的特定依赖模块版本解析导入。当遇到 go.mod 中没有任何模块提供的包的导入时，go 命令会自动查找包含该包的模块并将其添加到 go.mod，使用最新版本。（“最新”定义为最新标记的稳定（非预发布）版本，或者最新标记的预发布版本，或者最新的未标记版本。）在我们的示例中，go test 将新导入 rsc.io/quote 解析为模块 rsc.io/quote v1.5.2。它还下载了 rsc.io/quote 使用的两个依赖项，即 rsc.io/sampler 和 golang.org/x/text。 go.mod文件中只记录了直接依赖：

$ cat go.mod
module example.com/hello
go 1.12
require rsc.io/quote v1.5.2
$

第二个 go test 命令不会重复这项工作，因为 go.mod 现在是最新的并且下载的模块在本地缓存（在 $GOPATH/pkg/mod 中）：

$ go test
PASS
ok      example.com/hello   0.020s
$

请注意，虽然 go 命令可以快速轻松地添加新的依赖项，但并非没有代价。您的模块现在实际上依赖于关键领域的新依赖项，例如正确性、安全性和适当的许可，仅举几例。有关更多注意事项，请参阅 Russ Cox 的博客文章“我们的软件依赖问题”。

正如我们在上面看到的，添加一个直接依赖通常也会带来其他间接依赖。命令 go list -m all 列出当前模块及其所有依赖项：

$ go list -m all
example.com/hello
golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
rsc.io/quote v1.5.2
rsc.io/sampler v1.3.0
$

在 go list 输出中，当前模块，也称为主模块，总是在第一行，后面是按模块路径排序的依赖项。

golang.org/x/text 版本 v0.0.0-20170915032832-14c0d48ead0c 是一个伪版本的例子，它是特定未标记提交的 go 命令的版本语法。

除了 go.mod，go 命令还维护一个名为 go.sum 的文件，其中包含特定模块版本内容的预期加密哈希值：

$ cat go.sum
golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c h1:qgOY6WgZO...
golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c/go.mod h1:Nq...
rsc.io/quote v1.5.2 h1:w5fcysjrx7yqtD/aO+QwRjYZOKnaM9Uh2b40tElTs3...
rsc.io/quote v1.5.2/go.mod h1:LzX7hefJvL54yjefDEDHNONDjII0t9xZLPX...
rsc.io/sampler v1.3.0 h1:7uVkIFmeBqHfdjD+gZwtXXI+RODJ2Wc4O7MPEh/Q...
rsc.io/sampler v1.3.0/go.mod h1:T1hPZKmBbMNahiBKFy5HrXp6adAjACjK9...
$

go 命令使用 go.sum 文件来确保这些模块的未来下载检索与第一次下载相同的位，以确保您的项目所依赖的模块不会因恶意、意外或其他原因而意外更改。 go.mod 和 go.sum 都应该检查到版本控制中。

升级依赖

使用 Go 模块，版本使用语义版本标签进行引用。语义版本包含三个部分：主要、次要和补丁。比如v0.1.2，大版本是0，小版本是1，补丁版本是2。我们来看看几个小版本的升级。在下一节中，我们将考虑主要版本升级。

从 go list -m all 的输出中，我们可以看到我们使用的是 golang.org/x/text 的未标记版本。让我们升级到最新的标记版本并测试一切是否仍然有效：

$ go get golang.org/x/text
go: finding golang.org/x/text v0.3.0
go: downloading golang.org/x/text v0.3.0
go: extracting golang.org/x/text v0.3.0
$ go test
PASS
ok      example.com/hello   0.013s
$

呜呼！一切都会过去。让我们再看看 go list -m all 和 go.mod 文件：

$ go list -m all
example.com/hello
golang.org/x/text v0.3.0
rsc.io/quote v1.5.2
rsc.io/sampler v1.3.0
$ cat go.mod
module example.com/hello
go 1.12
require (
    golang.org/x/text v0.3.0 // indirect
    rsc.io/quote v1.5.2
)
$

golang.org/x/text 包已升级到最新的标记版本 (v0.3.0)。 go.mod 文件也已更新为指定 v0.3.0。间接注释表示该模块不直接使用某个依赖项，而是其他模块依赖项间接使用该依赖项。有关详细信息，请参阅 go 帮助模块。

现在让我们尝试升级 rsc.io/sampler 次要版本。以同样的方式开始，通过运行 go get 并运行测试：

$ go get rsc.io/sampler
go: finding rsc.io/sampler v1.99.99
go: downloading rsc.io/sampler v1.99.99
go: extracting rsc.io/sampler v1.99.99
$ go test
--- FAIL: TestHello (0.00s)
    hello_test.go:8: Hello() = "99 bottles of beer on the wall, 99 bottles of beer, ...", want "Hello, world."
FAIL
exit status 1
FAIL    example.com/hello   0.014s
$

哦，哦！测试失败说明最新版本的rsc.io/sampler与我们的使用不兼容。让我们列出该模块的可用标记版本：

$ go list -m -versions rsc.io/sampler
rsc.io/sampler v1.0.0 v1.2.0 v1.2.1 v1.3.0 v1.3.1 v1.99.99
$

我们一直在使用 v1.3.0； v1.99.99 显然不好。也许我们可以尝试使用 v1.3.1 代替：

$ go get rsc.io/sampler@v1.3.1
go: finding rsc.io/sampler v1.3.1
go: downloading rsc.io/sampler v1.3.1
go: extracting rsc.io/sampler v1.3.1
$ go test
PASS
ok      example.com/hello   0.022s
$

请注意 go get 参数中的显式 @v1.3.1。通常，传递给 go get 的每个参数都可以采用显式版本；默认值为@latest，它解析为之前定义的最新版本。

添加对新主要版本的依赖

让我们向我们的包中添加一个新函数：func Proverb 通过调用由模块 rsc.io/quote/v3 提供的 quote.Concurrency 返回一个 Go 并发谚语。首先我们更新 hello.go 以添加新函数：

package hello
import (
    "rsc.io/quote"
    quoteV3 "rsc.io/quote/v3"
)
func Hello() string {
    return quote.Hello()
}
func Proverb() string {
    return quoteV3.Concurrency()
}

然后我们在 hello_test.go 中添加一个测试：

func TestProverb(t *testing.T) {
    want := "Concurrency is not parallelism."
    if got := Proverb(); got != want {
        t.Errorf("Proverb() = %q, want %q", got, want)
    }
}

然后我们可以测试我们的代码：

$ go test
go: finding rsc.io/quote/v3 v3.1.0
go: downloading rsc.io/quote/v3 v3.1.0
go: extracting rsc.io/quote/v3 v3.1.0
PASS
ok      example.com/hello   0.024s
$

请注意，我们的模块现在依赖于 rsc.io/quote 和 rsc.io/quote/v3：

$ go list -m rsc.io/q...
rsc.io/quote v1.5.2
rsc.io/quote/v3 v3.1.0
$

Go 模块的每个不同主要版本（v1、v2 等）使用不同的模块路径：从 v2 开始，路径必须以主要版本结束。在示例中，rsc.io/quote 的 v3 不再是 rsc.io/quote：而是由模块路径 rsc.io/quote/v3 标识。这种约定称为语义导入版本控制，它为不兼容的包（具有不同主要版本的包）提供不同的名称。相比之下，rsc.io/quote 的 v1.6.0 应该向后兼容 v1.5.2，因此它重用名称 rsc.io/quote。（在上一节中，rsc.io/sampler v1.99.99 应该向后兼容 rsc.io/sampler v1.3.0，但错误或客户端对模块行为的错误假设都可能发生。）

go 命令允许构建最多包含任何特定模块路径的一个版本，这意味着每个主要版本中最多一个：一个 rsc.io/quote，一个 rsc.io/quote/v2，一个 rsc.io/quote/ v3，等等。这为模块作者提供了关于单个模块路径可能重复的明确规则：程序不可能同时使用 rsc.io/quote v1.5.2 和 rsc.io/quote v1.6.0。同时，允许模块的不同主要版本（因为它们具有不同的路径）使模块使用者能够逐步升级到新的主要版本。在这个例子中，我们想使用来自 rsc/quote/v3 v3.1.0 的 quote.Concurrency 但还没有准备好迁移我们对 rsc.io/quote v1.5.2 的使用。增量迁移的能力在大型程序或代码库中尤为重要。

将依赖项升级到新的主要版本

让我们完成从使用 rsc.io/quote 到仅使用 rsc.io/quote/v3 的转换。由于主要版本更改，我们应该预期某些 API 可能已被删除、重命名或以其他方式以不兼容的方式更改。阅读文档，我们可以看到 Hello 变成了 HelloV3：

$ go doc rsc.io/quote/v3
package quote // import "rsc.io/quote/v3"
Package quote collects pithy sayings.
func Concurrency() string
func GlassV3() string
func GoV3() string
func HelloV3() string
func OptV3() string
$

我们可以更新我们在 hello.go 中使用 quote.Hello() 以使用 quoteV3.HelloV3() ：

package hello
import quoteV3 "rsc.io/quote/v3"
func Hello() string {
    return quoteV3.HelloV3()
}
func Proverb() string {
    return quoteV3.Concurrency()
}

然后此时，不再需要重命名的导入，因此我们可以撤消它：

package hello
import "rsc.io/quote/v3"
func Hello() string {
    return quote.HelloV3()
}
func Proverb() string {
    return quote.Concurrency()
}

让我们重新运行测试以确保一切正常：

$ go test
PASS
ok      example.com/hello       0.014s

删除未使用的依赖项

我们已经删除了对 rsc.io/quote 的所有使用，但它仍然出现在 go list -m all 和我们的 go.mod 文件中：

$ go list -m all
example.com/hello
golang.org/x/text v0.3.0
rsc.io/quote v1.5.2
rsc.io/quote/v3 v3.1.0
rsc.io/sampler v1.3.1
$ cat go.mod
module example.com/hello
go 1.12
require (
    golang.org/x/text v0.3.0 // indirect
    rsc.io/quote v1.5.2
    rsc.io/quote/v3 v3.0.0
    rsc.io/sampler v1.3.1 // indirect
)
$

为什么？因为构建单个包，例如使用 go build 或 go test，可以轻松判断何时缺少某些内容并需要添加，但无法确定何时可以安全删除某些内容。只有在检查模块中的所有包以及这些包的所有可能的构建标记组合后，才能删除依赖项。普通的构建命令不会加载这些信息，因此它不能安全地删除依赖项。

go mod tidy 命令会清理这些未使用的依赖项：

$ go mod tidy
$ go list -m all
example.com/hello
golang.org/x/text v0.3.0
rsc.io/quote/v3 v3.1.0
rsc.io/sampler v1.3.1
$ cat go.mod
module example.com/hello
go 1.12
require (
    golang.org/x/text v0.3.0 // indirect
    rsc.io/quote/v3 v3.1.0
    rsc.io/sampler v1.3.1 // indirect
)
$ go test
PASS
ok      example.com/hello   0.020s
$

总结

Go 模块是 Go 依赖管理的未来。模块功能现在可用于所有受支持的 Go 版本（即 Go 1.11 和 Go 1.12）。

这篇文章介绍了这些使用 Go 模块的工作流程：

go mod init 创建一个新模块，初始化描述它的 go.mod 文件。
go build、go test 和其他包构建命令根据需要向 go.mod 添加新的依赖项。
go list -m all 打印当前模块的依赖项。
go get 更改依赖项的所需版本（或添加新的依赖项）。
go mod tidy 删除未使用的依赖项。

我们鼓励您开始在本地开发中使用模块，并将 go.mod 和 go.sum 文件添加到您的项目中。为了提供反馈并帮助塑造 Go 依赖管理的未来，请向我们发送错误报告或体验报告。

感谢您的所有反馈并帮助改进模块。