浅析 golang module

什么是 module?module 解决了什么问题?

module 代表一个版本管理单元,它包括一个或者多个 packages。

一般来说,一个版本控制仓库(比如 golang.org/x/text )包含一个 module(也可以包含多个 module,但是通常会带来一些复杂性)。

module 在 Go1.11 版本发布,它的前身是 vgo。 在 Go1.9.7+ 版本和 1.10.3+ 版本做了对 module 的部分向后兼容。

module 机制会在项目的根目录中添加 go.mod, 该文件用来记录项目依赖的 modules 的版本。

module 的出现主要是为了解决以下问题:

1. 版本依赖管理

设想一下,如果有 3 个包, 分别为 foo1, foo2, foo3。

foo1 依赖 foo3 的版本 v1.0.1 (后续简写为 [email protected]), foo2 依赖 [email protected]

现在我们需要实现一个功能,需要同时使用 foo1 和 foo2 两个包, 那我们应该使用什么版本的 foo3 呢?

2. 解除对 GOPATH 的依赖

在 Go1.11 版本之前,所有的 go 代码都要放到 $GOPATH/src 目录下面, 以便 import 能找到对应的包。

而 module 的出现,可以让我们将 go 代码放到任何地方。


语义导入版本控制

语义导入版本控制 (Semantic Import Versioning),是使用 module 必须要遵循的一些规定。

简单说来,就是需要 modules 的不同版本满足一些兼容规则。 比如: v1.5.4 版本需要向前兼容 v1.5.0、v1.4.0 甚至 v1.0.0 版本, 但不用兼容 v0.0.9 版本。

另外语义导入版本控制还约定了版本不能向前兼容时,modules 下的包的导入路径的变化。

下面详细介绍具体要满足哪些规则, 以及 golang 工具链是如何选择版本的:

1. semver 规范

semver 是一个语义化版本规范,是 modules 需要遵从的。

sember 的版本格式为:主版本号.次版本号.修订号,版本号递增规则如下:

  • 主版本号:当你做了不兼容的 API 修改
  • 次版本号:当你做了向下兼容的功能性新增,
  • 修订号:当你做了向下兼容的问题修正。

例如: 现在最新的版本号如果是 v1.4.9。 在此基础上,

  • 如果要对接口作出参数或返回值调整,导致依赖这个项目的代码需要修改它们的代码。那么下一个版本号应该是 v2.0.0
  • 如果是增加新的功能,不影响旧接口。那么下一个版本号应该是 v1.5.0
  • 如果是修改了一些 bug,而且可以向前兼容。那么下一个版本号应该是 v1.4.10

具体规则可以参考 https://semver.org/

2. Go 官方的 导入兼容规则

如果新 package 和旧 package 拥有相同的导入路径, 那么新的 package 要兼容旧的 package。

举个例子,比如你开发了一个 module (github.com/you/foo) 提供给用户使用,最初的时候你给这个 module 打了一个版本为 v1.0.0。并且直到 v1.5.9 为止没有出现过不能向前兼容的情况。

但现在,你要发布一个全新的版本,从而不能向前兼容。所以 semver 规则,你需要将版本号定义成 v2.0.0。

然而, 导入兼容规则 又给你加了一个新的限制,你的新版本不能向老版本兼容,所以你必须修改包路径为 github.com/you/foo/v2 (后文会详细介绍怎么修改包路径)。

3. 版本选择算法

在介绍版本选择算法之前, 让我们先了解一下 module 是怎么存储版本信息的:

如果你在自己的 module 中 import 了一个公共 moduel (github.com/other/bar),那么你第一次执行 go build或者 go test 的时候,go 会帮你自动找出并且下载 github.com/other/bar 的最新版本。并且在 go.mod 中记录当前依赖的版本, 如 require github.com/other/bar v1.4.9。 如果你事先手动在 go.mod 中增加了 require github.com/other/bar v1.4.8, 那么此时你执行 go build 或者 go test 时, go 会使用 v1.4.8 版本的 module 来编译。

那版本选择算法是什么呢?让我们先回到之前提出的那个问题:

如果有 3 个包, 分别为 foo1, foo2, foo3。 foo1 依赖 [email protected], foo2 依赖 [email protected]。 现在我们需要实现一个功能,需要同时使用 foo1 和 foo2 两个包, 那我们应该使用什么版本的 foo3 呢?

这里我们假设 foo1,foo2,foo3 都使用了 module,并且我们实现的这个功能也使用了 module (假设我们的 module 名字叫做 bar )

对于这种情况,在 foo1 的根目录下, 有一个 go.mod 文件, 包括一行依赖信息; require foo3 v1.0.1。 在 foo2 的根目录下, 有一个 go.mod 文件, 包括一行依赖信息; require foo3 v1.0.2

那么在编译我们自己的 module bar 时, 会使用哪个版本的 foo3 呢? 答案是 v1.0.2。

将 golang 选择 foo3 的版本的算法叫做 最小版本选择算法

它选出来的版本是所有 go.mod 文件(在这里包括 foo1, foo2 和 bar 下的 go.mod 文件) 中明确指定的最大版本。

这里的最小的意思是 foo1 和 foo2 给出的依赖的版本都是最小化了的, 比如 foo1 依赖 [email protected], 那么根据 semver 规则, foo1 在 [email protected] 下也可以正常工作, 因为 [email protected] 是向前兼容了 [email protected] 的。

那么如果 foo2 依赖的是 [email protected], 我们编译 bar 时,会使用哪个版本的 foo3 呢? 答案是:v1.0.1 和 v2.1.1 。

注意: 根据 导入兼容规则, v1.0.1 和 v2.1.1 使用的是不同的路径,一个是 v1.0.1 使用的是 foo3,而 v2.1.1 使用的是 foo3/v2。 所以可以同时存在于一次编译中。 而且 v2.1.1 是不能兼容 v1.0.1 的,所以 foo1 没法使用 v2.1.1 版本,因此也必须同时使用 foo3 的两个版本。

关于 最小版本选择算法 的详细信息,参考: https://research.swtch.com/vgo-mvs

4. “伪”版本

如果一个 module 没有有效的 semver 版本,那么 go.mod 将通过一个叫做 “伪版本“ 的东西来记录版本。

”伪版本“ 的通常形式是 vX.0.0-yyyymmddhhmmss-abcdefabcdef。 比如 golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c

其中 v0.0.0 表示 semver 版本号, 20170915032832 表示这个版本的时间。 14c0d48ead0c 表示这次提交的 hash。


怎么使用?中国用户会遇到哪些问题?如何解决这些问题?

这一节主要介绍怎么使用 go module,以及墙内用户怎么解决墙外的下载问题。

先看一下官方给的一个例子:

# 在 $GOPATH 外部创建一个目录
$ mkdir -p /tmp/scratchpad/hello
$ cd /tmp/scratchpad/hello

# 初始化 module
$ go mod init github.com/you/hello

go: creating new go.mod: module github.com/you/hello

# 依赖 module 写一段代码
$ cat < hello.go
package main

import (
    "fmt"
    "rsc.io/quote"
)

func main() {
    fmt.Println(quote.Hello())
}
EOF

# 编译执行 
$ go build 
$ ./hello

Hello, world.

1. 命令介绍

  • go mod init github.com/my/mod 用来初始化一个 module 并且生成一个 go.mod 文件。
$ go mod init github.com/my/hello
go: creating new go.mod: module github.com/my/hello

$ cat go.mod
module github.com/my/hello

go 1.12
  • go get github.com/some/pkg 下载最新版本的 module 以及它的所有依赖,并且在 go.mod 中增加对应的 require。 go get 不需要被显示执行,在执行 go buildgo test 的时候,它会根据依赖自动执行。
$ go get github.com/sirupsen/logrus
go: finding github.com/sirupsen/logrus v1.3.0
go: finding github.com/davecgh/go-spew v1.1.1
go: finding golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33
go: finding github.com/stretchr/objx v0.1.1
go: finding golang.org/x/crypto v0.0.0-20180904163835-0709b304e793
go: finding github.com/konsorten/go-windows-terminal-sequences v1.0.1
go: finding github.com/pmezard/go-difflib v1.0.0
go: finding github.com/stretchr/testify v1.2.2
go: downloading github.com/sirupsen/logrus v1.3.0
go: extracting github.com/sirupsen/logrus v1.3.0
go: downloading golang.org/x/crypto v0.0.0-20180904163835-0709b304e793
go: extracting golang.org/x/crypto v0.0.0-20180904163835-0709b304e793
go: downloading golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33
go: extracting golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33

执行完之后, modules 的文件被下载到 $GOPATH/pkg/mod 下,并且按照 [email protected] 的方式命名。

$ ls ~/go/pkg/mod/github.com/sirupsen
[email protected]

ls ~/go/pkg/mod/golang.org/x/
[email protected]   [email protected]      [email protected]

go.mod 中增加了对应的 require:

$ cat go.mod
module github.com/my/hello

go 1.12

require github.com/sirupsen/logrus v1.2.0 // indirect
  • go get github.com/some/[email protected] 下载指定版本的 module 以及它的所有依赖。
$ go get github.com/sirupsen/[email protected]
go: finding github.com/sirupsen/logrus v1.2.0
go: downloading github.com/sirupsen/logrus v1.2.0
go: extracting github.com/sirupsen/logrus v1.2.0

此时在 $GOPATH/pkg/mod 中下载了对应的文件,并且 go.mod 的 require 发生了变化:

$ cat go.mod
module github.com/my/hello

go 1.12

require github.com/sirupsen/logrus v1.2.0 // indirect
  • go get -u github.com/some/pkg 更新次版本号,由于主版本号的不兼容,所以不会更新主版本号。
  • go get -u=patch 更新修订号
  • go list -m all 查看所有依赖的 module 以及版本
  • go list -u -m all 查看可用的次版本号修订号的更新
  • go mod tidy 删除 go.mod 中没用到的 module

3. goproxy 的使用

国内用户在用 golang 的时候经常会遇到一个问题,就是下不下来代码。 在以前, 我们下载不了 googlesource.com 上的 go packages,通常都可以到 github 上面去克隆,然后放到 golang.org目录下面就可以了。

但是 go module 的出现使我们的操作要变得很复杂了 (可以想象一下, 先 git clone, 然后 git checkout v1.1.1, 最后 copy 到 mod/[email protected] 下)。

最简单的方式是 export GOPROXY=https://goproxy.io。 设置 go 代理,一切搞定!这样下载的时候都通过 goproxy 来下载。


怎么发布不兼容版本?

根据前文的介绍,如果新版本不能兼容旧版本,那么就要使用新的主版本号和新的导入路径 。

要提供新的主版本号并不困难,打个 tag 就是。

那么怎么来提供新的导入路径呢?有两种方式:

1. 就地修改

只需要将 go.mod 中的 module github.com/you/mod 修改成 github.com/you/mod/v2 。然后修改本 module 内的所有 import 语句,添加 /v2。如 import "github.com/you/mod/v2/mypkg"。

注意: 在 module 的 git(或者其他的版本控制) 仓库中,存在所有的提交, 所以其他依赖 v1..版本的 module 会自动使用旧版本。而依赖 v2.. 版本的 module 将会从 github.com/you/mod/ 中下载对应的版本,并且将 github.com/you/mod/ 下的所有包的路径对应成 github.com/you/mod/v2。

2. 创建子目录

另外一种方式是在 module 下创建一个 v2 目录, 然后将所有文件移动 v2 中,并且修改 go.mod 。 同时也需要修改所有相关的 import 语句。

你可能感兴趣的:(浅析 golang module)