GOPATH 模式怎么迁移至 Modules 模式？

01

介绍

Go 项目使用多种依赖管理策略。诸如 dep 和 glide 很受欢迎，但是它们在使用上有很大差异，并且并不总是能很好地协同工作。某些项目将其整个 GOPATH 目录存储在单个 Git 存储库中。其他人只是依靠 go get 获取，并期望在 GOPATH 中安装相当新版本的依赖项。

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

请注意：如果您的项目已在 v2.0.0 或更高版本标记，则需要在添加 go.mod 文件时更新模块路径。因为 Go modules 的每个不同主要版本（v1、v2 等）使用不同的模块路径：从 v2 开始，路径必须以主要版本结束。

02

迁移至 Modules 模式

在开始过渡到 Go Modules 时，项目可能为三种状态之一：

• 一个全新的 Go 项目。

• 具有非模块依赖管理工具的已建立的 Go 项目。

• 没有任何依赖项管理工具的已建立的 Go 项目。

第一种状态已在「 Go Modules 介绍与基本操作 」中介绍；我们将在这篇文章中讨论后两种。

03

已使用依赖管理工具的项目

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

$ 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 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/[email protected]
$

04

未使用依赖管理工具的项目

对于未使用依赖项管理工具的 Go 项目，首先创建 go.mod 文件：

$ 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 mod init 将创建一个仅包含模块和 go 指令的 go.mod 文件。在此示例中，我们将模块路径设置为golang.org/x/blog 因为这是其自定义导入路径。用户可以使用此路径导入包，我们必须注意不要更改它。

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

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

$ 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.sum，其中包含每个库的校验。

通过成功运行 go build 和 go test 确保代码正确。

$ 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 添加依赖时，它会添加模块的最新版本。如果您的 GOPATH 包含后来发布中断更改的依赖项的较旧版本，您可能会在 go mod tidy、go build 或 go test 中看到错误。如果发生这种情况，请尝试使用 go get 降级到旧版本 (例如,  

go get github.com/broken/[email protected] )，或花一些时间使您的模块与每个依赖项的最新版本兼容。

05

在模块模式下测试

迁移到 Go 模块后，某些测试可能需要进行调整。如果测试需要在程序包目录中写入文件，则当程序包目录位于 module cache 时（只读），它可能会失败。特别是，这可能会导致全部测试失败。测试应将需要写入的文件复制到临时目录中。

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

如果测试期望测试中的 go 命令以 GOPATH 模式运行，则可能会失败。在这种情况下，您可能需要将 go.mod 文件添加到要测试的源树中，或显式设置GO111MODULE = off。

06

发布发行版本

最后，您应该标记（git tag vx.x.x）并发布新模块的发行版本（git push origin vx.x.x）。如果您尚未发布任何版本，但是这是可选的，但是如果没有正式发布，则下游用户将依赖使用伪版本的特定提交，这可能更难支持。

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

新的 go.mod 文件为模块定义了规范的导入路径，并添加了新的最低版本要求。如果您的用户已经在使用正确的导入路径，并且您的依赖项尚未进行重大更改，则添加go.mod文件是向后兼容的-但这是一项重大更改，并且可能会暴露现有问题。如果有现有的版本标签，则应增加次要版本。

07

导入和规范的模块路径

每个模块在其 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 comments，声明规范导入路径的机制，但是包作者并不总是提供它们。结果，在模块之前编写的代码可能已经为模块使用了非规范的导入路径，而没有出现不匹配的错误。使用模块时，导入路径必须与规范的模块路径匹配，因此您可能需要更新导入语句：例如，您可能需要将导入

“github.com/golang/lint”

更改为导入“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 后缀。

08

总结

对于大多数用户而言，转换为 Go Modules 应该是一个简单的过程。有时会由于非规范的导入路径或在依赖项中破坏更改而引起偶尔的问题。

免费领取资料

扫描下方二维码关注微信公众号「Golang 语言开发栈」，回复「 资料 」关键字，免费获取 Golang 语言学习资料，回复「 微信群 」关键字，申请加入微信群，和我一起学习 Golang。

参考资料：

https://blog.golang.org/migrating-to-go-modules