管理模块的源代码

本文翻译自《Managing module source》。

目录

Go工具如何查找你发布的模块

在存储库中组织代码

选择存储库的范围

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

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

当你开发要发布以供其他人使用的模块时,你可以通过遵循本篇文章中描述的存储库规约来确保其他开发人员更容易地使用你的模块。

本文描述了你在管理模块存储库时可能采取的操作。有关在版本之间进行修订时你将采取的工作流程步骤顺序的信息,请参阅模块发布和版本控制工作流程

此处描述的一些规约在模块中是必需的,而另一些则是最佳实践。本内容假设你熟悉管理依赖项中描述的基本模块使用实践。

Go支持以下用于发布模块的存储库:Git、Subversion、Mercurial、Bazaar和Fossil。

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

Go工具如何找到你发布的模块

在Go发布模块和获取代码的分布式系统中,你可以将代码保留在存储库中的同时发布模块。Go工具依赖于存储库路径和存储库标签的命名规则,它们指示模块的名称和版本号。当你的存储库符合这些要求时,你的模块代码可以通过Go工具(例如go get命令)从存储库下载。

当开发人员使用go get命令为其代码导入的包获取源代码时,该命令执行以下操作:

1 go get在Go源代码中的import语句的包路径中识别模块路径。

2 使用从模块路径派生的URL,该命令在模块代理服务器上或直接在其存储库中定位模块源代码。

3 通过将模块的版本号与存储库标签匹配来查找要下载的模块版本的源代码,以发现存储库中的代码。当尚不知道要使用的版本号时,go get将查找最新版本。

4 检索模块源代码并将其下载到开发人员的本地模块缓存。

在存储库中组织代码

通过遵循此处描述的规约,你可以保持简单的维护并改善开发人员对你的模块的使用体验。将模块代码放入存储库通常与使用其他代码一样简单。

下图说明了具有两个包的简单模块的源代码层次结构。

你的首次提交应包括下表中列出的文件:

文件描述
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

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注