Go 博客

Go 模块：v2 及其未来

Jean de Klerk 和 Tyler Bui-Palsulich
2019 年 11 月 7 日

简介

这篇文章是系列文章的第 4 部分。

• 第 1 部分 - 使用 Go 模块
• 第 2 部分 - 迁移到 Go 模块
• 第 3 部分 - 发布 Go 模块
• 第 4 部分 - Go 模块：v2 及其未来（本文）
• 第 5 部分 - 保持模块的兼容性

注意：有关开发模块的文档，请参阅 开发和发布模块。

随着成功的项目逐渐成熟并添加新的需求，过去的特性和设计决策可能不再合理。开发人员可能希望通过删除弃用的函数、重命名类型或将复杂的包拆分为可管理的片段来整合他们学到的经验教训。这些更改需要下游用户为其代码迁移到新的 API 而付出努力，因此在进行这些更改时，应仔细考虑好处是否大于成本。

对于仍处于实验阶段的项目（主版本为v0），用户期望偶尔出现重大更改。对于宣布稳定的项目（主版本为v1 或更高），重大更改必须在新的主版本中进行。本文探讨了主版本语义、如何创建和发布新的主版本，以及如何维护模块的多个主版本。

主版本和模块路径

模块形式化了 Go 中一个重要的原则，即 导入兼容性规则

If an old package and a new package have the same import path,
the new package must be backwards compatible with the old package.

根据定义，包的新主版本与先前版本不向后兼容。这意味着模块的新主版本必须具有与先前版本不同的模块路径。从v2 开始，主版本必须出现在模块路径的末尾（在go.mod 文件中的module 语句中声明）。例如，当github.com/googleapis/gax-go 模块的作者开发v2 时，他们使用了新的模块路径github.com/googleapis/gax-go/v2。希望使用v2 的用户必须将他们的包导入和模块要求更改为github.com/googleapis/gax-go/v2。

对主版本后缀的需求是 Go 模块与大多数其他依赖项管理系统不同的地方之一。需要后缀来解决 钻石依赖问题。在 Go 模块之前，gopkg.in 允许包维护者遵循我们现在称为导入兼容性规则的内容。使用 gopkg.in，如果您依赖于导入gopkg.in/yaml.v1 的包，以及另一个导入gopkg.in/yaml.v2 的包，则不会发生冲突，因为这两个yaml 包具有不同的导入路径 - 它们使用了版本后缀，与 Go 模块一样。由于 gopkg.in 与 Go 模块共享相同的版本后缀方法，因此 Go 命令接受gopkg.in/yaml.v2 中的.v2 作为有效的主版本后缀。这是为了与 gopkg.in 保持兼容的特殊情况：托管在其他域的模块需要斜杠后缀，例如/v2。

主版本策略

推荐的策略是在名为主版本后缀的目录中开发v2+ 模块。

github.com/googleapis/gax-go @ master branch
/go.mod    → module github.com/googleapis/gax-go
/v2/go.mod → module github.com/googleapis/gax-go/v2

这种方法与不了解模块的工具兼容：存储库中的文件路径与GOPATH 模式下go get 预期的路径相匹配。这种策略还允许所有主版本在不同的目录中一起开发。

其他策略可能会将主版本保留在不同的分支上。但是，如果v2+ 源代码位于存储库的默认分支（通常为master），则不了解版本的工具（包括GOPATH 模式下的go 命令）可能无法区分主版本。

本文中的示例将遵循主版本子目录策略，因为它提供了最大的兼容性。我们建议模块作者在有用户在GOPATH 模式下开发的情况下遵循此策略。

发布 v2 及其未来版本

本文使用github.com/googleapis/gax-go 作为示例

$ pwd
/tmp/gax-go
$ ls
CODE_OF_CONDUCT.md  call_option.go  internal
CONTRIBUTING.md     gax.go          invoke.go
LICENSE             go.mod          tools.go
README.md           go.sum          RELEASING.md
header.go
$ cat go.mod
module github.com/googleapis/gax-go

go 1.9

require (
    github.com/golang/protobuf v1.3.1
    golang.org/x/exp v0.0.0-20190221220918-438050ddec5e
    golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3
    golang.org/x/tools v0.0.0-20190114222345-bf090417da8b
    google.golang.org/grpc v1.19.0
    honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099
)
$

要开始开发github.com/googleapis/gax-go 的v2 版本，我们将创建一个新的v2/ 目录，并将我们的包复制到该目录中。

$ mkdir v2
$ cp -v *.go v2
'call_option.go' -> 'v2/call_option.go'
'gax.go' -> 'v2/gax.go'
'header.go' -> 'v2/header.go'
'invoke.go' -> 'v2/invoke.go'
$

现在，让我们通过复制当前的go.mod 文件并在模块路径中添加/v2 后缀来创建一个 v2 go.mod 文件

$ cp go.mod v2/go.mod
$ go mod edit -module github.com/googleapis/gax-go/v2 v2/go.mod
$

请注意，v2 版本被视为与v0 / v1 版本不同的模块：两者都可以在同一个构建中共存。因此，如果您的v2+ 模块有多个包，您应该更新它们以使用新的/v2 导入路径：否则，您的v2+ 模块将依赖于您的v0 / v1 模块。例如，要将所有github.com/my/project 引用更新为github.com/my/project/v2，您可以使用find 和sed

$ find . -type f \
    -name '*.go' \
    -exec sed -i -e 's,github.com/my/project,github.com/my/project/v2,g' {} \;
$

现在我们有了v2 模块，但我们希望在发布版本之前进行实验和进行更改。在我们发布v2.0.0（或任何没有预发布后缀的版本）之前，我们可以开发并进行重大更改，直到我们决定新的 API。如果我们希望用户在我们正式将其稳定化之前能够尝试新的 API，我们可以发布v2 预发布版本

$ git tag v2.0.0-alpha.1
$ git push origin v2.0.0-alpha.1
$

一旦我们对v2 API 感到满意，并确定我们不需要进行任何其他重大更改，我们就可以标记v2.0.0

$ git tag v2.0.0
$ git push origin v2.0.0
$

在这一点上，现在有两个主版本需要维护。向后兼容的更改和错误修复将导致新的次要版本和修补程序版本（例如，v1.1.0、v2.0.1 等）。

结论

主版本更改会导致开发和维护开销，并需要下游用户投资进行迁移。项目越大，这些开销往往就越大。主版本更改应仅在确定了令人信服的理由之后才能进行。一旦确定了进行重大更改的令人信服的理由，我们建议在 master 分支上开发多个主版本，因为它与更多现有工具兼容。

对v1+ 模块的重大更改应始终发生在新的vN+1 模块中。当发布新模块时，这意味着维护人员和需要迁移到新包的用户需要付出额外的工作。因此，维护人员应在发布稳定版本之前验证他们的 API，并仔细考虑除了v1 之外是否真的需要进行重大更改。