Go 博客

迁移到 Go Modules

Jean Barkhuysen
2019 年 8 月 21 日

引言

本文是本系列文章的第二部分。

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

Go 项目使用多种多样的依赖项管理策略。Vendoring 工具，例如 dep 和 glide，很受欢迎，但它们的行为差异很大，并非总能很好地协同工作。有些项目将其整个 GOPATH 目录存储在单个 Git 仓库中。其他项目则完全依赖 go get，并期望将相对较新版本的依赖项安装在 GOPATH 中。

Go 1.11 中引入的 Go 模块系统提供了一种内置于 go 命令的官方依赖项管理解决方案。本文介绍了将项目转换为模块的工具和技术。

请注意：如果您的项目已经标记为 v2.0.0 或更高版本，那么在添加 go.mod 文件时，您需要更新模块路径。我们将在后续文章中解释如何在不破坏用户的情况下完成此操作，后续文章将重点介绍 v2 及更高版本。

在您的项目中迁移到 Go modules

项目在开始向 Go modules 过渡时可能处于以下三种状态之一

全新的 Go 项目。
已有非模块依赖项管理器的 Go 项目。
没有任何依赖项管理器的已有 Go 项目。

第一种情况在使用 Go Modules 中有所介绍；本文将讨论后两种情况。

使用依赖项管理器

要转换已使用依赖项管理工具的项目，请运行以下命令

$ git clone https://github.com/my/project
[...]
$ cd project
$ cat Godeps/Godeps.json
{
    "ImportPath": "github.com/my/project",
    "GoVersion": "go1.12",
    "GodepVersion": "v80",
    "Deps": [
        {
            "ImportPath": "rsc.io/binaryregexp",
            "Comment": "v0.2.0-1-g545cabd",
            "Rev": "545cabda89ca36b48b8e681a30d9d769a30b3074"
        },
        {
            "ImportPath": "rsc.io/binaryregexp/syntax",
            "Comment": "v0.2.0-1-g545cabd",
            "Rev": "545cabda89ca36b48b8e681a30d9d769a30b3074"
        }
    ]
}
$ go mod init github.com/my/project
go: creating new go.mod: module github.com/my/project
go: copying requirements from Godeps/Godeps.json
$ cat go.mod
module github.com/my/project

go 1.12

require rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
$

go mod init 创建一个新的 go.mod 文件，并自动从 Godeps.json、Gopkg.lock 或许多其他支持的格式中导入依赖项。go mod init 的参数是模块路径，即模块可能找到的位置。

这是暂停并运行 go build ./... 和 go test ./... 的好时机，然后再继续。后续步骤可能会修改您的 go.mod 文件，因此如果您喜欢迭代方法，这是您的 go.mod 文件最接近您迁移前依赖项规范的状态。

$ go mod tidy
go: downloading rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
go: extracting rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
$ cat go.sum
rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca h1:FKXXXJ6G2bFoVe7hX3kEX6Izxw5ZKRH57DFBJmHCbkU=
rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca/go.mod h1:qTv7/COck+e2FymRvadv62gMdZztPaShugOCi3I+8D8=
$

go mod tidy 查找模块中包传递导入的所有包。它为任何已知模块未提供的包添加新的模块需求，并移除不提供任何导入包的模块需求。如果某个模块提供的包仅被尚未迁移到模块的项目导入，则该模块需求将标记为 // indirect 注释。在将 go.mod 文件提交到版本控制之前，运行 go mod tidy 始终是一种好习惯。

最后，确保代码能够构建并且测试通过

$ go build ./...
$ go test ./...
[...]
$

请注意，其他依赖项管理器可能在单个包或整个仓库级别（而非模块级别）指定依赖项，并且通常不识别依赖项的 go.mod 文件中指定的需求。因此，您可能无法获得与之前完全相同的每个包版本，并且存在升级后遇到破坏性更改的风险。因此，重要的是在执行上述命令后对生成的依赖项进行审计。为此，请运行

$ go list -m all
go: finding rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
github.com/my/project
rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
$

并将结果版本与您的旧依赖项管理文件进行比较，以确保所选版本是合适的。如果您发现版本不符合预期，可以使用 go mod why -m 和/或 go mod graph 找出原因，并使用 go get 升级或降级到正确的版本。（如果您请求的版本比之前选择的版本旧，go get 将根据需要降级其他依赖项以保持兼容性。）例如，

$ go mod why -m rsc.io/binaryregexp
[...]
$ go mod graph | grep rsc.io/binaryregexp
[...]
$ go get rsc.io/binaryregexp@v0.2.0
$

没有依赖管理器

没有依赖项管理器

$ git clone https://go.googlesource.com/blog
[...]
$ cd blog
$ go mod init golang.org/x/blog
go: creating new go.mod: module golang.org/x/blog
$ cat go.mod
module golang.org/x/blog

go 1.12
$

对于没有依赖项管理系统的 Go 项目，首先创建 go.mod 文件

如果没有来自先前依赖项管理器的配置文件，go mod init 将创建一个仅包含 module 和 go 指令的 go.mod 文件。在本例中，我们将模块路径设置为 golang.org/x/blog，因为这是它的自定义导入路径。用户可以使用此路径导入包，我们必须小心不要更改它。

module 指令声明模块路径，而 go 指令声明用于编译模块内代码的 Go 语言的预期版本。

$ go mod tidy
go: finding golang.org/x/website latest
go: finding gopkg.in/tomb.v2 latest
go: finding golang.org/x/net latest
go: finding golang.org/x/tools latest
go: downloading github.com/gorilla/context v1.1.1
go: downloading golang.org/x/tools v0.0.0-20190813214729-9dba7caff850
go: downloading golang.org/x/net v0.0.0-20190813141303-74dc4d7220e7
go: extracting github.com/gorilla/context v1.1.1
go: extracting golang.org/x/net v0.0.0-20190813141303-74dc4d7220e7
go: downloading gopkg.in/tomb.v2 v2.0.0-20161208151619-d5d1b5820637
go: extracting gopkg.in/tomb.v2 v2.0.0-20161208151619-d5d1b5820637
go: extracting golang.org/x/tools v0.0.0-20190813214729-9dba7caff850
go: downloading golang.org/x/website v0.0.0-20190809153340-86a7442ada7c
go: extracting golang.org/x/website v0.0.0-20190809153340-86a7442ada7c
$ cat go.mod
module golang.org/x/blog

go 1.12

require (
    github.com/gorilla/context v1.1.1
    golang.org/x/net v0.0.0-20190813141303-74dc4d7220e7
    golang.org/x/text v0.3.2
    golang.org/x/tools v0.0.0-20190813214729-9dba7caff850
    golang.org/x/website v0.0.0-20190809153340-86a7442ada7c
    gopkg.in/tomb.v2 v2.0.0-20161208151619-d5d1b5820637
)
$ cat go.sum
cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
cloud.google.com/go v0.34.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
git.apache.org/thrift.git v0.0.0-20180902110319-2566ecd5d999/go.mod h1:fPE2ZNJGynbRyZ4dJvy6G277gSllfV2HJqblrnkyeyg=
git.apache.org/thrift.git v0.0.0-20181218151757-9b75e4fe745a/go.mod h1:fPE2ZNJGynbRyZ4dJvy6G277gSllfV2HJqblrnkyeyg=
github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973/go.mod h1:Dwedo/Wpr24TaqPxmxbtue+5NUziq4I4S80YR8gNf3Q=
[...]
$

接下来，运行 go mod tidy 添加模块的依赖项

$ go build ./...
$ go test ./...
ok      golang.org/x/blog   0.335s
?       golang.org/x/blog/content/appengine [no test files]
ok      golang.org/x/blog/content/cover 0.040s
?       golang.org/x/blog/content/h2push/server [no test files]
?       golang.org/x/blog/content/survey2016    [no test files]
?       golang.org/x/blog/content/survey2017    [no test files]
?       golang.org/x/blog/support/racy  [no test files]
$

go mod tidy 添加了模块中包传递导入的所有包的模块需求，并生成了一个 go.sum 文件，其中包含每个库在特定版本时的校验和。最后，确保代码仍然可以构建并且测试仍然通过

请注意，当 `go mod tidy` 添加需求时，它会添加模块的最新版本。如果您的 `GOPATH` 包含某个依赖项的旧版本，而该依赖项随后发布了破坏性更改，您可能会在 `go mod tidy`、`go build` 或 `go test` 中看到错误。如果发生这种情况，尝试使用 `go get` 降级到旧版本（例如，`go get github.com/broken/module@v1.1.0`），或者花时间使您的模块与每个依赖项的最新版本兼容。

模块模式下的测试

迁移到 Go modules 后，某些测试可能需要进行调整。

如果某个测试需要在包目录中写入文件，当包目录位于模块缓存（只读）中时，测试可能会失败。特别是，这可能会导致 go test all 失败。测试应将其需要写入的文件复制到临时目录，而不是直接写入包目录。

如果某个测试依赖相对路径（../package-in-another-module）来定位和读取另一个包中的文件，当该包位于另一个模块中时（该模块位于模块缓存的版本化子目录或 replace 指令中指定的路径），测试将失败。如果是这种情况，您可能需要将测试输入复制到您的模块中，或者将测试输入从原始文件转换为嵌入在 .go 源文件中的数据。

如果某个测试期望测试中的 `go` 命令在 GOPATH 模式下运行，它可能会失败。如果是这种情况，您可能需要在待测试的源代码树中添加 `go.mod` 文件，或显式设置 `GO111MODULE=off`。

发布版本

$ git tag v1.2.0
$ git push origin v1.2.0

最后，您应该为您的新模块标记并发布一个发布版本。如果您尚未发布任何版本，这是可选的，但如果没有官方发布，下游用户将依赖使用伪版本的特定提交，这可能更难以支持。

您的新 `go.mod` 文件定义了模块的规范导入路径，并添加了新的最低版本需求。如果您的用户已经使用了正确的导入路径，并且您的依赖项没有进行破坏性更改，那么添加 `go.mod` 文件是向后兼容的——但这一个重大的变化，可能会暴露现有问题。如果您有现有的版本标签，您应该增加次版本号。请参阅发布 Go Modules 了解如何增加和发布版本。

导入和规范模块路径

每个模块在其 go.mod 文件中声明其模块路径。引用模块内包的每个 import 语句都必须以模块路径作为包路径的前缀。但是，go 命令可能通过许多不同的远程导入路径遇到包含该模块的仓库。例如，golang.org/x/lint 和 github.com/golang/lint 都解析到包含托管在 go.googlesource.com/lint 的代码的仓库。该仓库中包含的go.mod 文件声明其路径为 golang.org/x/lint，因此只有该路径对应于一个有效的模块。

Go 1.4 提供了一种使用// import 注释声明规范导入路径的机制，但包作者并非总是提供它们。因此，在模块之前编写的代码可能使用了非规范的模块导入路径，而不会因此类不匹配而引发错误。使用模块时，导入路径必须与规范模块路径匹配，因此您可能需要更新 import 语句：例如，您可能需要将 import "github.com/golang/lint" 更改为 import "golang.org/x/lint"。

模块的规范路径与其仓库路径不同的另一种情况发生在主版本为 2 或更高的 Go 模块。主版本大于 1 的 Go 模块必须在其模块路径中包含主版本后缀：例如，版本 `v2.0.0` 必须带有 `/v2` 后缀。但是，`import` 语句可能引用了模块内没有该后缀的包。例如，`v2.0.1` 版本的 `github.com/russross/blackfriday/v2` 的非模块用户可能将其导入为 `github.com/russross/blackfriday`，并且需要更新导入路径以包含 `/v2` 后缀。

结论

对于大多数用户而言，转换为 Go modules 应该是一个简单的过程。偶尔可能由于非规范导入路径或依赖项中的破坏性更改而出现问题。未来的文章将探讨发布新版本、v2 及更高版本以及调试奇怪情况的方法。

要提供反馈并帮助塑造 Go 依赖项管理的未来，请向我们发送错误报告或体验报告。

感谢您的所有反馈以及对改进模块的帮助。
下一篇文章：Go Module Mirror 和 Checksum 数据库已启动
上一篇文章：2019 年贡献者峰会