Go 博客

使用 Go 模块

Tyler Bui-Palsulich 和 Eno Compton
2019 年 3 月 19 日

引言

此文章是系列文章的第一部分。

第一部分 — 使用 Go 模块（本文）
第二部分 — 迁移到 Go 模块
第三部分 — 发布 Go 模块
第四部分 — Go 模块：v2 及更高版本
第五部分 — 保持模块兼容

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

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

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

从 Go 1.11 开始，当当前目录或任何父目录存在 go.mod 文件时，go 命令会启用模块的使用，前提是该目录不在 $GOPATH/src 中。（在 $GOPATH/src 内部，为了兼容性，go 命令仍然在旧的 GOPATH 模式下运行，即使找到了 go.mod。详情请参阅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 中任何模块未提供的包的 import 时，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。indirect 注释表示依赖项并非由本模块直接使用，而是由其他模块依赖项间接使用。详情请参阅 go help modules。

现在我们尝试升级 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 通过调用 quote.Concurrency 返回 Go 并发谚语，该函数由模块 rsc.io/quote/v3 提供。首先，我们更新 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 中依赖管理的未来，请向我们发送错误报告或经验报告。

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

下一篇文章：在 Go 1.12 中调试您部署的内容
上一篇文章：新的 Go 开发者网络
博客索引