Go语言 – 第 6 页

文件	描述
LICENSE	模块的许可证。
go.mod	描述模块，包括它的模块路径（实际上就是它的名称）和它的依赖关系。有关更多信息，请参阅go.mod参考。模块路径将在`module`指令中给出，例如： `module example.com/mymodule` 有关选择模块路径的更多信息，请参阅管理依赖项。虽然你可以编辑go.mod文件，但你会发现通过`go`命令进行更改更可靠。
go.sum	包含表示模块依赖项的加密哈希值。Go工具使用这些哈希值来验证下载的模块，试图确认下载的模块是可信的。如果此确认失败，Go将显示一个安全性错误。当没有依赖项时，该文件将为空或不存在。你不应该编辑此文件，除非使用`go mod tidy`命令删除不需要的条目。
包目录和.go源代码文件	目录构成模块中的包，.go文件就是源代码文件。

你可以在命令行创建一个空的存储库，添加将成为首次提交的一部分的文件，并在提交时添加注释。下面是一个使用git的例子：

$ git init
$ git add --all
$ git commit -m "mycode: initial commit"
$ git push

选择存储库的范围

当代码应该独立于其他模块中的代码进行版本控制时，你在模块中发布该代码。

将存储库设计为在其根目录中托管单个模块将有助于简化维护，尤其是随着时间的推移，当你发布新的次版本和补丁版本、创建新的主版本分支等时候。但是，如果你的其他模块的代码依赖它，你可以改为在单个存储库中维护一组模块。

一个存储库管理一个模块的源代码

你可以维护一个包含单个模块源代码的存储库。在此模型中，你将go.mod文件放在存储库的根目录里，存储库的根目录里还有包子目录，包子目录里有Go源代码文件。

这是最简单的方法，随着时间的推移，你的模块可能更易于管理。它可以帮助你避免在模块目录名上附加版本号。

一个存储库管理多个模块的源代码

你可以用单个存储库发布多个模块。例如，你可能在一个存储库中包含多个模块的源代码，但希望分别对这些模块进行版本控制。

作为模块根目录的每个子目录都必须有自己的go.mod文件。

当发布一个模块时，在子目录中管理模块源代码需要更改版本标签的形式。你必须在标签版本号前面加上对应的模块根目录下的子目录的名称。有关版本号的更多信息，请参阅模块版本编号。

例如，对于下面的模块example.com/mymodules/module1的v1.2.3版本，你将拥有以下内容：

模块路径：example.com/mymodules/module1
版本标签：module1/v1.2.3
用户导入的包路径：example.com/mymodules/module1/package1
用户require指令中的模块路径：example.com/mymodules/module1 module1/v1.2.3

09/11/2022

开发一个主版本更新

本文翻译自《Developing a major version update》。

主版本更新的注意事项

为主版本的发布创建分支

当你在潜在的新版本中所做的更改不能保证模块用户的向后兼容性时，你必须把这些更改更新到主版本。例如，如果你更改模块的公开API会破坏使用该模块以前版本的客户端代码，你就应该通过开发一个新的主版本来实现这种更改。

注意：每个版本类型——主版本、次版本、补丁版本或预发布版本——对模块的用户来说都有不同的含义。这些用户依靠这些差异来了解版本对他们自己的代码所代表的风险级别。换句话说，在准备发布时，请确保其版本号准确地反映了自上一版本以来的更改的性质。有关版本号的更多信息，请参阅模块版本编号。

另请参阅

有关模块开发的概述，请参阅开发和发布模块。
有关手把手教学，请参阅模块发布和版本控制工作流程。

主版本更新的注意事项

仅在绝对必要时才更新到新的主版本。因为主版本更新对你和你模块的用户来说都意味着重大的变化。当你考虑进行主版本更新时，请考虑以下事项：

发布新的主版本对你以前的主版本的维护意味着什么，你需要向你的用户明确这一点。以前的版本是否已弃用？还是像以前一样支持？你会维护以前的版本，包括Bug修复吗？

准备好维护两个版本：旧版本和新版本。例如，如果你修复了一个Bug，你通常会将这些修复移植到另一个中。
请记住，从依赖管理的角度来看，新的主版本是一个新模块。在你发布新的主版本后，你的用户将需要更新以使用新模块，而不是简单地升级。这是因为新的主版本与之前的主版本具有不同的模块路径。例如，对于模块路径为example.com/mymodule的模块，v2版本将具有模块路径example.com/mymodule/v2。

当你开发新的主版本时，你还必须在导入新模块里的包的那些代码里，修改导入路径。如果你的模块的用户想要升级到新的主版本，他们也必须更改他们的导入路径。

为主版本的发布创建分支

在准备开发新的主版本时，最直接的处理源代码的方式是从存储库创建先前主版本的最新版本的分支。

例如，在命令提示符下，你可以cd到模块的根目录，然后在那里创建一个新的v2分支。

$ cd mymodule
$ git checkout -b v2
Switched to a new branch "v2"

创建源代码的分支后，需要对新版本的源代码进行以下更改：

在新版本的go.mod文件中，将新的主版本号附加到模块路径，如下例所示：

现有版本：example.com/mymodule

新版本：example.com/mymodule/v2

在Go代码中，更新从该模块导入包的每个导入路径，将主版本号附加到模块路径部分。

旧的导入语句：import“example.com/mymodule/package1”

新的导入语句：import“example.com/mymodule/v2/package1”

有关发布步骤，请参见发布一个模块。

02/11/202204/11/2022

模块发布和版本控制工作流程

本文翻译自《Module release and versioning workflow》。

当你开发供其他开发人员使用的模块时，你可以遵循有助于使用该模块的开发人员获得可靠、一致的体验的工作流程。本主题描述了该工作流程中的高级步骤。

有关模块开发的概述，请参阅开发和发布模块。

也请参阅

如果你只想在代码中使用外部包，请务必查看管理依赖项。
对于每个新版本，你都用其版本号表示对模块的更改。有关更多信息，请参阅模块版本编号。

常见的工作流程步骤

以下序列说明了一个新模块的发布和版本控制的工作流程步骤。有关每个步骤的更多信息，请参阅本主题中的各个章节。

1 开始一个模块并组织它的源代码，使开发人员更容易使用，使你更容易维护。

如果你是开发模块的新手，请查看教程：创建Go模块。

在Go的去中心化模块发布系统中，如何组织代码很重要。有关更多信息，请参阅管理模块源代码。

2 开始编写调用未发布模块中的函数的本地客户端代码。

在发布模块之前，它不能用于使用go get等命令的典型的依赖管理工作流程。在此阶段测试模块代码的一个好方法是，在本地目录中调用并测试它的代码。

有关本地开发的更多信息，请参阅下文的针对未发布的模块进行编程小节。

3 当模块的代码准备好供其他开发人员试用时，你可以开始发布alphas和beta等v0预发布版。有关详细信息，请参见下文的发布预发布(pre-release)版本小节。

4 发布一个v0版本，不保证稳定，但用户可以试用。有关详细信息，请参见下文的发布第一个（不稳定的）版本小节。

5 发布v0版本后，你可以（而且应该！）继续发布它的新版本。

这些新版本可能包括bug修复（补丁版本）、对模块公开API的添加（次要版本），甚至是破坏性的更改。因为v0版本不保证稳定性或向后兼容性，所以你可以对其版本进行重大更改。

有关详细信息，请参见下文的发布Bug修复小节和发布不破坏API的更改小节。

6 当你准备好发布稳定版本时，你可以将预发布版本发布为alphas版本或beta版本。有关详细信息，请参见下文的发布预发布(pre-release)版本小节。

7 发布v1作为第一个稳定版本。

这是第一个对模块稳定性做出承诺的版本。有关详细信息，请参见下文的发布第一个稳定版本小节。

8 在v1版本中，继续修复bug，并在必要时添加模块的公共API。

有关详细信息，请参见下文的发布Bug修复小节和发布不破坏API的更改小节。

9 当无法避免时，在一个新的主版本中发布破坏性的更改。

主版本更新——例如从v1.x.x到v2.x.x——对于模块的用户来说可能是一个非常具有破坏性的升级。这应该是最后的手段。有关更多信息，请参阅下文的发布破坏API的更改小节。

针对未发布的模块进行编程

当你开始开发模块或模块的新版本时，你还没有发布它。在发布模块之前，你将无法使用Go命令将该模块添加为依赖项。相反，当你在另一个模块中编写调用这个未发布模块的函数的客户端代码时，你首先需要在本地文件系统里引用该模块的副本。

你可以使用客户端模块的go.mod文件中的replace指令从本地引用该模块。有关更多信息，请参阅在本地目录中需求模块代码。

发布预发布(pre-release)版本

你可以发布预发布版本，使模块可供其他人试用并向你提供反馈。预发布版本不保证稳定性。

预发布版本号后附有预发布标识符。有关版本号的更多信息，请参见模块版本号。

以下是两个例子：

v0.2.1-beta.1
v1.2.3-alpha

在提供预发布版本时，请记住，使用预发布版本的开发人员需要使用go get命令按版本号明确指出它。这是因为，在默认情况下，go命令在定位你需求的模块时更喜欢正式的发布版本而不是预发布版本。因此，开发人员必须通过显式地指出来获得预发布版本，如下例所示：

go get example.com/[email protected]

你可以通过给存储库中的模块代码加标签来发布预发布版本，并在标签中指定预发布标识符。有关更多信息，请参阅发布模块。

发布第一个（不稳定的）版本

当你发布预发布版本时，你可以发布不保证稳定性或向后兼容性的发布版本，但给你的用户一个试用该模块并向你提供反馈的机会。

不稳定版本是指版本号在v0.x.x范围内的版本。v0版本不保证稳定性或向后兼容性。但它为你提供了一种方法，可以在使用v1和更高版本做出稳定性承诺之前获得反馈并改进你的API。有关更多信息，请参见模块版本编号。

与其他已发布版本一样，你可以在发布稳定的v1版本之前进行更改代码时增加v0版本号的次版本号和补丁版本号部分。例如，在发布v.0.0.0版本之后，你可能会发布带有第一组Bug修复的v0.0.1版本。这是一个示例版本号：

v0.1.3

你可以通过给存储库中的模块代码加标签来发布不稳定版本，并在标签中指定v0版本号。有关更多信息，请参阅发布模块。

发布第一个稳定版本

你的第一个稳定版本将具有v1.x.x版本号。第一个稳定版本是在预发布版本和v0版本之后发布的，你可以通过它们获得反馈、修复Bug并为用户稳定模块。

在v1版本中，你向使用你的模块的开发人员做出以下承诺：

他们可以升级到主版本号后续的次版本和补丁版本，而不会破坏自己的代码。
你不会对模块的公共API进行进一步的更改——包括它的函数和方法签名——这会破坏向后兼容性。
你不会删除任何导出的类型，因为这会破坏向后兼容性。
未来对API的更改（例如向结构体添加新字段）将向后兼容，并将包含在新的次版本中。
Bug修复（例如安全修复）将包含在补丁版本中或作为次版本的一部分。

注意：虽然你的第一个主版本可能是v0版本，但v0版本并没有稳定性或向后兼容性保证。因此，当你从v0升级到v1时，你无需注意破坏向后兼容性，因为v0版本被认为是不稳定的。

有关版本号的更多信息，请参阅模块版本编号。下面是一个稳定版本号的例子：

v1.0.0

你通过给存储库中的模块代码加标签来发布第一个稳定版本，并在标签中指定v1版本号。有关更多信息，请参阅发布模块。

发布Bug修复

你可以发布一个版本，其中的更改仅限于Bug修复。这称为补丁版本。

补丁版本仅包含较小的更改。特别是，它没有对模块的公开API进行任何更改。使用代码的开发人员可以安全地升级到这个版本，而无需更改他们的代码。

注意：你的补丁版本应该尽量不要将任何该模块自己的依赖项升级超过补丁版本。否则，升级到该模块补丁版本的人可能会意外地对他们使用的间接依赖项进行更具侵入性的更改。

补丁版本会增加模块版本号的补丁部分。有关更多信息，请参阅模块版本编号。

在以下示例中，v1.0.1是一个补丁版本。

旧版本：v1.0.0

新版本：v1.1.0

你可以通过给存储库中的模块代码加标签来发布次要版本，增加标签中的次要版本号。有关更多信息，请参阅发布模块。

发布破坏API的更改

你可以通过发布主(major)版本来发布破坏向后兼容的版本。

主版本不保证向后兼容性，通常是因为它包含对模块公开API的更改，这些更改会破坏调用模块先前版本的代码。

考虑到主版本升级可能对依赖于模块的代码产生的破坏性影响，如果可以的话，你应该避免主版本更新。有关主版本更新的更多信息，请参阅开发主版本更新。有关避免进行破坏性更改的策略，请参阅博客文章保持模块兼容。

如果发布其他类型的版本需要使用版本号来给模块代码加标签，那么发布主版本更新需要更多的步骤。

1 在开始开发新的主版本之前，在你的存储库中为新版本的源代码创建一个位置。

一种方法是在存储库中创建一个新的分支，专门用于新的主版本及其后续的次版本和补丁版本。有关更多信息，请参见管理模块源代码。 2 在模块的go.mod文件中，修改模块路径以附加新的主版本号，如下例所示：

example.com/mymodule/v2

既然模块路径是模块的标识，此更改有效地创建了一个新模块。它还更改了包路径，确保开发人员不会无意中导入破坏其代码的版本。相反，那些想要升级的用户将显式地用新路径替换旧路径。

3 在你的代码中，更改你正在更新的模块里的任何包的导入路径，包括你正在更新的模块里的包。你需要这样做，因为你更改了模块路径。

4 与任何新版本一样，在发布正式版本之前，你应该发布预发布版本以获得反馈和Bug报告。

5 通过在存储库中给模块代码加标签，增加标签中的主版本号（例如从v1.5.2到v2.0.0），发布新的主版本。

有关详细信息，请参见发布一个模块。

01/11/202201/11/2022

教程：多模块工作空间入门

本文翻译自《Tutorial: Getting started with multi-module workspaces》。

先决条件

为代码创建模块

创建工作空间

下载并修改golang.org/x/example模块

了解有关工作空间的详细信息

本教程介绍Go中多模块工作空间的基础知识。使用多模块工作空间，你可以告诉Go命令，你正在同时在多个模块中编写代码，并且可以轻松地在这些模块中构建和运行代码。

在本教程中，你将在共享的多模块工作空间中创建两个模块，对这些模块进行更改，并在一个构建中查看这些更改的结果。

注意：有关其他教程，请参见教程。

先决条件

安装Go 1.18或更高版本。
编辑代码的工具。任何文本编辑器都可以正常工作。
命令行终端。Go在Linux和Mac上的任何终端以及Windows中的PowerShell或cmd上都能很好地工作。

本教程需要go1.18或更高版本。确保你已经使用Go.dev/dl上的链接安装了Go 1.18或更高版本。

为你的代码创建一个模块

首先，为你要编写的代码创建一个模块。

1 打开命令提示符并切换到你的家目录。在Linux或Mac上：

$ cd ~

在Windows上：

C:\> cd %HOMEPATH%

（译者注：或者执行C:\> cd %USERPROFILE%）

本教程的其余部分将显示$作为提示符。你使用的命令也可以在Windows上使用。

2 在命令提示符下，为代码创建一个名为workspace的目录。

$ mkdir workspace
$ cd workspace

3 初始化模块

我们的示例将创建一个依赖于golang.org/x/example的新模块hello。

创建hello模块：

$ mkdir hello
$ cd hello
$ go mod init example.com/hello
go: creating new go.mod: module example.com/hello

使用go get添加golang.org/x/example依赖项。

$ go get golang.org/x/example

在hello目录中创建hello.go，并输入以下内容：

package main

import (
    "fmt"

    "golang.org/x/example/stringutil"
)

func main() {
    fmt.Println(stringutil.Reverse("Hello"))
}

现在，运行hello程序：

$ go run example.com/hello
olleH

创建工作空间

在这一步中，我们将创建一个go.work文件来指定带有模块的工作空间。

初始化工作空间

在workspace目录中，运行：

$ go work init ./hello

go work init命令告诉go为包含./hello目录中的模块的工作空间创建一个go.work文件。

go命令生成一个如下所示的go.work文件：

go 1.18

use ./hello

go.work文件的语法与go.mod相似。

go指令告诉Go应该使用哪个版本的Go来解释Go文件。它类似于go.mod文件中的go指令。

use指令告诉Go在构建时hello目录中的模块应该是主(main)模块。

因此，在workspace的任何子目录中，该模块都将处于活动状态。

运行workspace目录下的程序

在workspace目录中，运行：

$ go run example.com/hello
olleH

Go命令把包含在工作空间中的所有模块作为主模块。这允许我们引用一个模块中的包，甚至模块外的包。在模块或工作空间之外运行go run命令会导致错误，因为go命令不知道要使用哪些模块。

接下来，我们将golang.org/x/example模块的本地副本添加到工作空间。然后，我们将向stringutil包添加一个新函数，我们可以使用它来代替Reverse。

下载并修改golang.org/x/example模块

在这一步中，我们将下载包含golang.org/x/example模块的Git存储库的副本，将其添加到工作空间，然后向其中添加一个我们将在hello程序中使用的新函数。

1 克隆存储库在workspace目录中，运行git命令来克隆存储库：

$ git clone https://go.googlesource.com/example
Cloning into 'example'...
remote: Total 165 (delta 27), reused 165 (delta 27)
Receiving objects: 100% (165/165), 434.18 KiB | 1022.00 KiB/s, done.
Resolving deltas: 100% (27/27), done.

2 将模块添加到工作空间

$ go work use ./example

go work use命令将一个新模块添加到go.work文件中。它现在看起来像这样：

go 1.18

use (
    ./hello
    ./example
)

该模块现在包括example.com/hello模块和golang.org/x/example模块。

这将允许我们使用我们将在stringutil模块的副本中编写的新代码，而不是使用go get命令下载的模块缓存中的该模块版本。（译者注：这说明go.work文件中use的模块被使用的优先级高于本地模块缓存中和网络上的同名模块。）

3 添加新函数

我们将在golang.org/x/example/stringutil包中添加一个将字符串大写的新函数。

在workspace/example/stringutil目录中创建一个名为toupper.go的新文件，其中包含以下内容：

package stringutil

import "unicode"

// ToUpper把参数字符串s里的所有rune字符变为大写
func ToUpper(s string) string {
    r := []rune(s)
    for i := range r {
        r[i] = unicode.ToUpper(r[i])
    }
    return string(r)
}

4 修改hello程序以使用该函数

修改workspace/hello/hello.go的内容，包含以下内容：

package main

import (
    "fmt"

    "golang.org/x/example/stringutil"
)

func main() {
    fmt.Println(stringutil.ToUpper("Hello"))
}

运行工作空间里的代码

在workspace目录里，运行

$ go run example.com/hello
HELLO

Go命令找到在命令行上给出的，由go.work文件指定的，在hello目录中的example.com/hello模块。并类似地解析由go.work文件导入的golang.org/x/example模块。

可以使用go.work来代替添加replace指令跨多个模块工作。

由于这两个模块位于同一个工作空间中，因此很容易在一个模块中进行更改并在另一个模块中使用它。

更进一步

现在，要正确发布这些模块，我们需要发布golang.org/x/example模块，例如v0.1.0。这通常是通过在模块的版本控制存储库里给提交(commit)加标签来完成的。

有关更多详细信息，请参阅模块发布工作流程文档。发布完成后，我们可以在hello/go.mod中增加对golang.org/x/example模块的需求：

cd hello
go get golang.org/x/[email protected]

这样，go命令就可以正确地解析工作空间之外的模块。

学习更多工作空间相关的知识

go命令除了我们之前在教程中见过的go work init之外，还有多个子命令用于处理工作空间：

go work use [-r] [dir]为dir添加一个use指令到go.work文件，如果dir参数指定的目录存在的话，如果dir参数指定的目录不存在，该命令就会删除对应的use指令。dir的工作文件（如果存在），如果参数目录不存在，则删除use目录。-r标志递归地检查dir参数指定的目录的子目录。
go work edit编辑go.work文件，类似于go mod edit。
go work sync将工作空间构建列表中的依赖项同步到每个工作空间模块中。

有关工作空间和go.work文件的详细信息，请参见《Go模块文档》中的工作空间(workspace)小节。

25/09/202227/10/2022

syscall包

本文翻译自《The syscall package》。

作者：Rob Pike 日期：2014

状态：此提案[Go 1.4版本采用] (https://go.dev/doc/go1.4#major_library_changes)。

问题

现在的syscall包有几个问题：

1.膨胀。它包含许多系统调用和常量的定义，用于大量且不断增长的体系结构和操作系统。

2.测试。很少有接口有明确的测试，跨平台测试是不可能的。

3.管理。许多更改列表到来，以支持范围广泛的包和系统。这些变化的优点很难判断，所以基本上任何事情都会发生。该软件包是标准存储库中维护最差、测试最差、文档最差的软件包，并且还在继续恶化。

4.文档。称为syscall的单个包对于每个系统都不同，但godoc仅显示其本机环境的变体。此外，无论如何，文档都非常缺乏。大多数函数根本没有文档注释。

5.兼容性。尽管有最好的意图，但该软件包不符合Go 1兼容性保证，因为操作系统的变化方式超出了我们的控制范围。最近对FreeBSD的更改就是一个例子。

这个提议是试图改善这些问题。

提议

该提案有几个组成部分。没有特别的顺序：

1.Go 1的兼容性规则意味着我们不能直接解决问题，比如通过使包内部化。因此，我们建议从Go 1.3开始冻结该包，这意味着取消从那时起进行的一些更改。

2.支持Go未来版本所需的系统调用接口的任何更改都将通过为Go 1.4提议的内部包机制完成。

3.syscall包将不会在未来的版本中更新，甚至不会跟上它引用的操作系统的变化。例如，如果内核常量的值在未来的NetBSD版本中发生变化，则不会更新syscall包以反映这一点。

4.将创建一个新的子存储库go.sys。

5.在go.sys内部，将有三个独立于syscall的包，分别称为plan9、unix和windows，并且当前syscall包的内容将被适当地分解并安装在这些包中。（这种划分表达了系统之间的基本接口差异，允许一些源代码级别的可移植性，但在包中仍然需要构建标签来分离架构和变体（darwin，linux））。这些是我们希望所有外部Go包在需要支持系统调用时迁移到的包。因为它们是不同的，所以它们更容易管理，更容易使用godoc进行检查，并且可能更容易保持良好的文档记录。这种布局还使如何编写跨平台代码更加清晰：通过将系统相关元素分离为单独导入的组件。

6.go.sys存储库将随着操作系统的发展而更新。

7.标准syscall包的文档将引导用户访问新的存储库。尽管syscall包将继续存在并且可行，但所有新的公共开发都将在go.sys中进行。

8.核心存储库将不依赖于go.sys包，尽管某些子存储库（例如go.net）可能会依赖。

9.与任何标准存储库一样，go.sys存储库将由Go团队管理。将其从主存储库中分离出来使得自动化一些维护变得更加实际可行，例如通过对系统包含文件的详尽处理来自动创建包。

10.自1.3以来在syscall包中发生的任何非必要的提示更改都将迁移到go.sys子存储库。

请注意，由于兼容性保证，我们无法在任何有意义的范围内清理现有的syscall包。但是，我们可以冻结并实际上弃用它。

时间线

我们建议在Go 1.4的2014年9月1日截止日期之前完成这些更改。

21/09/202214/01/2023

Go 1和Go程序的未来

本文翻译自《Go 1 and the Future of Go Programs》。

介绍

期望

子存储库

操作系统

工具

介绍

Go版本1的发布，简称Go 1，是该语言发展的一个重要里程碑。Go 1是一个稳定的平台，用于Go语言编写的程序和项目的生长。

Go 1定义了两件事：第一，语言的规范；其次，一组核心API的规范，即Go库的“标准包”。Go 1版本的发行，包括以两个编译器套件（gc和gccgo）形式的实现，以及它们的核心库。

其目的是，编写遵循Go 1规范的程序将在该规范的整个生命周期内继续正确编译和运行，不变。在某个不确定的时间点，可能会出现Go 2规范，但在此之前，即使将来出现Go 1的“单点”版本（Go 1.1、Go 1.2等），今天工作的Go程序也应该继续工作。

兼容性是在源代码级别保证。版本之间不保证编译后的二进制包的兼容性。单点版本发布后，需要重新编译Go源代码以链接到新版本。

API可能会增长，获取新的包和功能，但不会破坏现有的Go 1代码。

期望

尽管我们预计绝大多数程序会随着时间的推移保持这种兼容性，但无法保证未来的任何更改都不会破坏任何程序。本文档试图设定对未来Go 1软件兼容性的期望。今天编译和运行的程序在未来的单点版本发布后可能会以多种方式失败。虽然它们都不太可能，但值得记录。

安全。规范或实现中的安全问题可能会暴露出来，其解决方法需要破坏兼容性。我们保留解决此类安全问题的权利。
未定义的行为。Go规范试图明确该语言的大多数属性，但某些方面未定义。依赖于这种未指定行为的程序可能会在未来的版本中中断运行。
规范错误。如果有必要解决规范中的不一致或不完整问题，解决该问题可能会影响现有程序的意义或合法性。我们保留解决此类问题的权利，包括更新实现。除安全问题外，不会对规范进行不兼容的更改。
Bug。如果编译器或库存在违反规范的Bug，则如果修复了Bug，则依赖于该Bug行为的程序可能会中断运行。我们保留修复此类Bug的权利。
结构体字面量。为了在以后的版本中添加功能，可能需要在API中向导出的结构体添加字段。使用无键结构体字面量（例如pkg.T{3, “x”}）来创建这些类型的值的代码在此类更改后将无法编译。但是，使用键控结构体字面量(pkg.T{A: 3, B: “x”}) 的代码将在此类更改后继续编译通过。我们将以允许键控结构体字面量保持兼容的方式更新此类数据结构，尽管非键控结构体字面量可能无法编译通过。（还有更复杂的情况涉及嵌套的数据结构或接口，但它们具有相同的解决方法。）因此，我们建议其类型在单独的包中定义的复合文字应使用键控表示法。
方法。与结构体字段一样，可能需要向类型添加方法。在某些情况下，例如当该类型与另一种类型一起嵌入到结构中时，添加新方法可能会通过与其他嵌入类型的现有方法产生冲突来破坏结构。我们无法防范这种罕见的情况，也不保证出现这种情况时的兼容性。
点导入。如果程序使用import . "path"导入标准包，未来版本中导入包中定义的其他名称可能与程序中定义的其他名称冲突。在测试之外，我们不建议使import . "path"，使用它可能会导致程序在未来的版本中无法编译通过。
使用unsafe包。导入并使用unsafe包可能依赖Go实现的内部特性。我们保留对可能破坏此类程序的实现进行更改的权利。

当然，对于所有这些可能性，如果它们出现，我们将尽可能在不影响现有代码的情况下更新规范、编译器或库。

这些相同的考虑适用于连续的点版本发布。例如，在Go 1.2下运行的代码应该与Go 1.2.1、Go 1.3、Go 1.4等版本兼容，尽管不一定与Go 1.1兼容，因为它可能使用仅在Go 1.2中添加的新特性。

在版本之间添加的特性，在源存储库中可用，但不是打了编号的二进制发布版本的一部分，说明它正在积极开发中。在使用此类功能的软件发布之前，我们不承诺其兼容性。

最后，虽然这不是正确性问题，但程序的性能可能会受到其所依赖的编译器或库的实现变化的影响。不能保证给定程序在版本之间的性能。

尽管这些期望适用于Go 1本身，但我们希望对基于Go 1的外部软件的开发做出类似的考虑。

子存储库

主go树(main go tree)的子存储库中的代码，例如golang.org/x/net，可能会在更宽松的兼容性要求下开发。但是，子存储库将被适当地打标签以识别与Go 1点版本兼容的版本。

操作系统

无法保证与外部各方更改的操作系统接口的长期兼容性。因此，syscall包不在此处所做保证的范围内。从Go 1.4版本开始，syscall包被冻结。系统调用接口的任何演变都必须在其他地方得到支持，例如在go.sys子存储库中。有关详细信息和背景，请参阅此文档。

工具

最后，Go工具链（编译器、链接器、构建工具等）正在积极开发中，可能会改变行为。这意味着，例如，依赖于工具位置和属性的脚本可能会被单点发布版本破坏。

除了这些注意事项，我们相信Go 1将成为Go及其生态系统发展的坚实基础。

16/09/2022

Context和结构体

本文翻译自《Contexts and structs》。

Jean de Klerk, Matt T. Proud

24 February 2021

介绍

在许多Go API，尤其是现代API中，函数和方法的第一个参数通常是context.Context。上下文提供了一种跨API边界和进程之间传输截止时间(deadline)、调用者取消(caller cancellation)和请求范围内的其他值的方法。当库直接或传递地与远程服务器（例如数据库、API等）交互时，通常会使用它。

Context（上下文）的文档指出：Context不应该存储在结构体类型中，而是传递给每个需要它的函数。

本文扩展了该建议的原因和示例，描述了为什么传递Context而不是将其存储在另一种类型中很重要。它还强调了在结构体类型中存储Context可能有意义的一个罕见情况，以及如何安全地这样做。

首选作为参数传递的context

为了理解不将context存储在结构体中的建议，让我们考虑首选的把context作为参数的方法：

// Worker获取work并将其添加到远程工作编排服务器。
type Worker struct { /* … */ }

type Work struct { /* … */ }

func New() *Worker {
  return &Worker{}
}

func (w *Worker) Fetch(ctx context.Context) (*Work, error) {
  _ = ctx // 每次调用ctx用于取消、截止时间和元数据。
}

func (w *Worker) Process(ctx context.Context, work *Work) error {
  _ = ctx // 每次调用ctx用于取消、截止时间和元数据。
}

在这里，(*Worker).Fetch和(*Worker).Process方法都直接接受context。通过这种作为参数传递的设计，用户可以设置每次调用的截止时间、取消和元数据。而且，很清楚如何使用传递给每个方法的context.Context：没有悬念传递给一个方法的context.Context将被任何其他方法使用。这是因为context被限定为尽可能小的操作，这极大地增加了这个包中context的实用性和清晰度。

在结构体中存储context会导致混乱

让我们用不受欢迎的在结构体中使用context(context-in-struct)方法再次检查上面的Worker示例。它的问题在于，当你将context存储在结构体中时，你会模糊调用者的生命周期，或者更糟的是以不可预知的方式将两个作用域混合在一起：

type Worker struct {
  ctx context.Context
}

func New(ctx context.Context) *Worker {
  return &Worker{ctx: ctx}
}

func (w *Worker) Fetch() (*Work, error) {
  _ = w.ctx // 共享的w.ctx用于取消、截止时间和元数据。
}

func (w *Worker) Process(work *Work) error {
  _ = w.ctx // 共享的w.ctx用于取消、截止时间和元数据。
}

(*Worker).Fetch和(*Worker).Process方法都使用存储在Worker中的context。这可以防止Fetch和Process的调用者（它们本身可能有不同的context）指定截止时间、请求取消以及在每个调用的基础上附加元数据。例如：用户无法为(*Worker).Fetch提供截止时间，或仅取消(*Worker).Process调用。调用者的生命周期与共享的context混合在一起，并且context的作用域局限于创建的Worker的生命周期。

与通过参数传递(pass-as-argument)的方法相比，API也更容易让用户感到困惑。用户可能会问自己：

由于New需要一个context.Context，构造函数做的工作是否需要取消或截止时间？
传递给New的context.Context是否适用于(*Worker).Fetch和(*Worker).Process？两者都不？这一个但不是另一个？

API需要大量文档来明确告诉用户context.Context的用途。用户可能还必须阅读源代码，而不是能够依赖API传达的信息。

最后，这么设计一个生产级服务可能非常危险，它的每个请求都没有context，因此不能充分执行取消。如果无法设置每次调用的最后时间，你的进程可能会积压并耗尽其资源（例如内存）！

规则的例外：保持向后兼容性

当引入context.Context的Go 1.7发布时，大量API必须以向后兼容的方式添加context支持。例如，net/http的Client方法，像Get和Do，是context的绝佳候选者。使用这些方法发送的每个外部请求都将受益于context.Context附带的截止时间、取消和元数据支持。

有两种方法可以向后兼容的方式添加对context.Context的支持：在结构体中包含context，我们稍后会看到，以及复制函数，复制的函数接受context.Context并将Context作为其函数名后缀。复制方法应优先于在结构体中使用context，并在《保持模块兼容》中进一步讨论。但是，在某些情况下它是不切实际的：例如，如果你的API公开了大量函数，那么复制它们可能是不可行的。

net/http包选择了在结构体中使用context的方法，它提供了一个有用的案例研究。让我们看看net/http的Do。在引入context.Context之前，Do定义如下：

// Do发送一个HTTP请求并返回一个HTTP响应 [...]
func (c *Client) Do(req *Request) (*Response, error)

在Go 1.7之后，如果不是因为它会破坏向后兼容性，Do可能看起来像下面这样：

// Do发送一个HTTP请求并返回一个HTTP响应 [...]
func (c *Client) Do(ctx context.Context, req *Request) (*Response, error)

但是，保持向后兼容性并遵守Go 1的兼容性承诺对于标准库至关重要。因此，维护者选择在http.Request结构里添加context.Context以允许支持context.Context而不会破坏向后兼容性：

// Request代表服务器接收到的HTTP请求或将由客户端发送的HTTP请求。
// ...
type Request struct {
  ctx context.Context

  // ...
}

// NewRequestWithContext在给定method、URL和可选body的情况下返回一个新请求。
// [...]
// 给定的ctx用于Request的生命周期。
func NewRequestWithContext(ctx context.Context, method, url string, body io.Reader) (*Request, error) {
  // 为简洁起见，本文进行了简化。
  return &Request{
    ctx: ctx,
    // ...
  }
}

// Do发送一个HTTP请求并返回一个HTTP响应 [...]
func (c *Client) Do(req *Request) (*Response, error)

当改造你的API以支持context时，将context.Context添加到结构体中可能是有意义的，如上所述。但是，请记住首先考虑复制你的函数，这允许在不牺牲实用性和理解性的情况下以向后兼容的方式改进context.Context。例如：

// Call在内部使用context.Background；要指定context，请使用CallContext。
func (c *Client) Call() error {
  return c.CallContext(context.Background())
}

func (c *Client) CallContext(ctx context.Context) error {
  // ...
}

总结

context可以轻松地将重要的跨库和跨API信息传播到调用堆栈。但是，它必须一致且清晰地使用，以保持可理解、易于调试和有效。

当作为方法中的第一个参数而不是存储在结构类型中传递时，用户可以充分利用其可扩展性，以便通过调用堆栈构建强大的取消、截止时间和元数据信息树。而且，最重要的是，当它作为参数传入时，可以清楚地理解它的作用域，从而在堆栈上下都有清晰的理解和可调试性。

在设计带有context的API时，请记住以下建议：将context.Context作为参数传入；不要将它存储在结构体中。

标签： Go语言

管理依赖项

管理模块的源代码

发布一个模块