Go模块参考

Go DOC

Go Modules Reference

模块是Go管理依赖的方式。

本文档是Go模块系统的详细参考手册。有关创建Go项目的介绍，请参见如何编写Go代码。有关使用模块、将项目迁移到模块以及其他主题的信息，请参阅从使用Go模块开始的博客系列。

一、模块、包和版本

模块（module）是一起发布、版本化和分发的包的集合。模块可以直接从版本控制存储库或模块代理服务器下载。

模块由模块路径标识，该路径在go.mod文件中声明，文件中还有关于模块依赖项的信息。模块根目录(module root directory)是包含go.mod 文件的目录。主模块(main module)是包含调用go命令的目录的模块。

模块中的每个包(package )都是同一目录中一起编译的源文件的集合。包路径是模块路径连接上包含包的子目录(相对于模块根目录)。例如，模块“golang.org/x/net”包含目录“html”中的一个包。该包的路径是“golang.org/x/net/html”。

1.1 模块路径

模块路径(module path)是模块的规范名称，在模块的go.mod文件中使用module指令声明。模块的路径是模块内包路径的前缀。

模块路径应该描述模块的功能以及在哪里可以找到它。通常，模块路径由存储库根路径、存储库中的目录(通常为空)和主版本后缀(仅适用于主版本2或更高版本)组成。

1.2 版本

版本（version ）标识了模块的不可变快照，它可以是发布版，也可以是预发布版。每个版本都以字母v开头，后面跟着一个语义版本。有关如何格式化、解释和比较版本的详细信息，请参阅语义版本控制2.0.0。

总而言之，语义版本由三个非负整数(从左到右为主(major)版本、次(minor)版本和补丁(patch )版本)组成， 用,分隔。补丁版本后面可以跟着一个以连字符开头的可选预发布字符串（pre-release string）。预发布字符串或补丁版本后面可能跟着以加号开头的构建元数据字符串。如v0.0.0、v1.12.134、v8.0.5-pre、v2.0.9+meta为有效版本。

如果一个版本的主版本为0或有预发布后缀，则该版本被认为是不稳定的。不稳定的版本不受兼容性要求的约束。例如，v0.2.0可能与v0.1.0不兼容，v1.5.0-beta可能与v1.5.0不兼容。

Go可以使用不遵循这些约定的标记、分支或修订访问版本控制系统中的模块。但是，在主模块中，go命令将自动将不符合该标准的修订名称转换为规范版本。go命令还将在此过程中删除构建元数据的后缀(+incompatible除外)。这可能会导致一个伪版本，一个预发布版本，它编码了一个修订标识符(比如Git提交哈希)和一个来自版本控制系统的时间戳。例如，命令go get golang.org/x/net@daa7c041将把提交散列daa7c041转换为伪版本v0.0.0-20191109021931-daa7c04131f5。在主模块之外需要规范版本，如果在 go.mod中出现了像master这样的非规范版本，go命令将报告错误。

1.3 伪版本

伪版本（Pseudo-versions）是一种特别格式化的预发布版本，它在版本控制存储库中编码关于特定修订的信息。例如，v0.0.0-20191109021931-daa7c04131f5是伪版本。

伪版本可能是指没有语义版本标签的版本。它们可以用于在创建版本标记之前测试提交，例如，在开发分支上。

每个伪版本有三个部分:

• 基本版本前缀(vX.0.0 or vX.Y.Z-0)，它来源于修订之前的语义版本标记，如果没有这样的标记，则来源于vX.0.0。
• 时间戳(yyyymmddhhmmss)，它是创建修订的UTC时间。在Git中，这是提交时间，而不是作者时间。
• 修订标识符(abcdefabcdef)，这是提交散列的12个字符前缀，或者在Subversion中是一个零填充的修订号。

二、go.mod 文件详解

语法

go.mod语法在下面使用Extended Backus-Naur Form (EBNF)指定。有关EBNF语法的详细信息，请参阅Go语言规范中的符号部分。
例如：

module 指令(module directive)

module 指令定义了主模块的路径。一个go.mod文件必须只包含一个module 指令。

ModuleDirective = "module" ( ModulePath | "(" newline ModulePath newline ")" ) newline .

module golang.org/x/net

go 指令

go指令指示一个模块是假设特定go版本的语义编写的。版本必须是有效的Go发布版本:一个正整数后跟一个点和一个非负整数(例如，1.9,1.14)。

go指令最初是为了支持向后不兼容的go语言更改(参见go 2转换)。自引入模块以来，没有不兼容的语言变化，但go指令仍然影响新语言特性的使用:

require 指令

require指令声明给定模块依赖项的最低要求版本。对于每个所需的模块版本，go命令加载go.mod 文件，并从该文件中合并需求。一旦加载了所有需求，go命令使用最小版本选择(MVS)来解析它们，以生成构建列表。

replace 指令

replace指令用在其他地方找到的内容替换模块的特定版本或模块的所有版本的内容。替换可以指定为另一个模块路径和版本，也可以指定为特定于平台的文件路径。

如果箭头(=>)左边有一个版本，则只替换该模块的特定版本;其他版本将正常访问。如果省略左边的版本，则替换该模块的所有版本。

Example:

replace golang.org/x/net v1.2.3 => example.com/fork/net v1.4.5

replace (
    golang.org/x/net v1.2.3 => example.com/fork/net v1.4.5
    golang.org/x/net => example.com/fork/net v1.4.5
    golang.org/x/net v1.2.3 => ./fork/net
    golang.org/x/net => ./fork/net
)

术语表

build list

用于构建命令(如go build、go list或go test)的模块版本列表。构建列表是由主模块的go.mod file 在传递所需的模块中使用最小版本选择go.mod file 决定的。构建列表包含模块图中所有模块的版本，而不仅仅是与特定命令相关的版本。

pre-release version 预发布版本

紧跟着补丁版本带有破折号，后面跟着一系列以点分隔的标识符，例如 v1.2.3-beta4。

预发布版本被认为是不稳定的，并且不被认为与其他版本兼容。预发布版本排在相应的发布版本之前: v1.2.3-pre排在v1.2.3之前。参见发布版本。

release version 发布版本

没有预发布后缀的版本。例如，v1.2.3，而不是v1.2.3-pre。

patch version 补丁版本

语义版本中的第三个数字(v1.2.3中的3)。在没有对模块的公共接口进行更改的版本中，补丁版本必须递增。

pseudo-version 伪版本

对版本控制系统的修订标识符(如Git提交哈希)和时间戳进行编码的版本。例如v0.0.0-20191109021931-daa7c04131f5。用于与非模块存储库的兼容性，以及在标记版本不可用时的其他情况下。

main module

调用go命令的模块。主模块是由在当前目录 或父目录中go.mod 文件定义的。参见模块、包和版本。

repository root path

模块路径中与版本控制存储库的根目录相对应的部分。

semantic version tag

版本控制存储库中将版本(version )映射到特定修订的标记。参见将版本映射到提交。

minimal version selection (MVS)

用于确定构建中将使用的所有模块的版本的算法