go modules 初体验

引言

通过上一篇文章《go modules 基础》的学习，很多读者已经掌握了 go 原生的包依赖管理方案的基本知识，于是在实践中尝试 go modules 机制的想法已箭在弦上，不得不发。

本文开启 go modules 的实战部分，将带领读者通过一段轻松的旅途，初步体验一下 go modules（简称 go mod）的强大。

go mod 工程的搭建

我们考虑在本地搭建一个 go mod 工程，工程名为 hello-gomod，而工程所在的位置应该是任意的，且不受原有 GOPATH mode 的影响。

本地 GOPATH 的路径：

$ echo $GOPATH
/Users/zhangxiaolong/Desktop/D/go-workspace

我们先在 D 盘建立一个新目录 gomod（与 GOPATH 的路径无关），然后在 gomod 目录下建立一个目录 hello-gomod（工程名）。

打开 shell 终端，在 hello-gomod 目录下运行 go mod init 命令：

$ go mod init github.com/agiledragon/hello-gomod
go: creating new go.mod: module github.com/agiledragon/hello-gomod
$ cat go.mod 
module github.com/agiledragon/hello-gomod

go 1.14

我们发现在 hell-gomod 目录下生成了一个文件 go.mod，该文件中的内容为：

第一行为该工程的模块名 github.com/agiledragon/hello-gomod。一般模块命名为该工程所在代码仓库的路径，比如作者一般将代码工程放在 github 上的个人目录下
第二行为本地 go 语言的版本。作者本地的 go 语言版本为 1.14，go mod 机制已成熟

在该工程下新建一个包 calculator，并实现一个简单的函数 add：

package calculator

func Add(a, b int) int {
    return a + b
}

在 main 包中调用 math 包的 Add 函数：

package main

import (
    "fmt"

    "github.com/agiledragon/hello-gomod/calculator"
)

func main() {
    r := 1
    r = calculator.Add(1, 2)
    fmt.Println(r)
}

可见，在本工程中导入工程内部的包时的路径为："模块名" + "/" + "内部包的相对路径"。

至此，hello-gomod 工程下的目录结构为：

$ find . -print | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
.
|____go.mod
|____calculator
| |____add.go
|____main.go

注：Mac 下默认没有 tree 命令，我们通过 find 命令来模拟。

在 hello-gomod 目录下运行工程：

$ go run main.go 
3

注：该模块还没有依赖任意的第三方包，所以在工程目录下没有生成 go.sum 文件，同时 go.mod 文件也没有任何变化。

go mod 工程的测试

为了提高代码质量，我们计划为 calculator 包添加单元测试，于是新建了在 calculator 包下新建了测试文件 add_test.go，并写了一个简单的测试用例：

package calculator

import (
    "testing"

    "github.com/smartystreets/goconvey/convey"
)

func TestAdd(t *testing.T) {
    convey.Convey("TestAdd", t, func() {
        convey.Convey("normal case", func() {
            convey.So(3, convey.ShouldEqual, Add(1, 2))
        })
    })
}

我们直接运行该测试：

$ go test -v ./calculator/
go: downloading github.com/smartystreets/goconvey v1.6.4
go: downloading github.com/jtolds/gls v4.20.0+incompatible
go: downloading github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d
=== RUN   TestAdd

  TestAdd 
    normal case ✔


1 total assertion

--- PASS: TestAdd (0.00s)
PASS
ok      github.com/agiledragon/hello-gomod/calculator   (cached)

我们发现测试运行成功，并且 go test 命令在正式测试前下载了所有的依赖项。

我们再运行一下测试：

$ go test -v ./calculator/
=== RUN   TestAdd

  TestAdd 
    normal case ✔


1 total assertion

--- PASS: TestAdd (0.00s)
PASS
ok      github.com/agiledragon/hello-gomod/calculator   0.006s

我们发现本次 go test 运行前不再下载依赖项，那说明依赖项用的是本地的（上次测试下载的）。

这些依赖项是从哪下载的？读者可能也想到了环境变量 GOPROXY，我们一起看一下：

$ echo $GOPROXY
https://goproxy.cn,direct

注：goproxy.cn 是七牛云维护的一个非营利性项目，目标是为中国及世界上其他地方的 gophers 们提供一个免费的、可靠的、持续在线的且经过 CDN 加速的模块代理；“direct” 为特殊指示符，用于指示 go 回源到模块版本的源地址去抓取 (比如 github 等)，当值列表中上一个 go module proxy 返回 404 或 410 错误时，go 会自动尝试列表中的下一个，遇见 “direct” 时回源，遇见 EOF 时终止并抛出类似 “invalid version: unknown revision...” 的错误。

这些依赖项都下载到哪去了？依赖项是如何管理的？我们虽然对整个过程不是很清楚，但可以断定这些问题肯定与 go.mod 文件有关。

我们先查看 go.mod 文件，发现多了一行：

module github.com/agiledragon/hello-gomod

go 1.14

require github.com/smartystreets/goconvey v1.6.4

注：最后一行是新增的，require 是关键字，指明 hello-gomod 工程的依赖项，此处只有 goconvey 模块（代码工程）及其版本。

我们接着查看 hello-gomod 工程的目录，发现模块根目录下（与 go.mod 同级）增加了一个文件 go.sum：

$ cat go.sum 
github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
github.com/jtolds/gls v4.20.0+incompatible h1:xdiiI2gbIgH/gLH7ADydsJ1uDOEzR8yvV7C0MuV77Wo=
github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d h1:zE9ykElWQ6/NYmHa3jpm/yHnI4xSofP+UP6SpjHcSeM=
github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
github.com/smartystreets/goconvey v1.6.4 h1:fv0U8FUIMPNf1L9lnHLvLhgicrIVChEkdzIKYqbNC9s=
github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=

注：本 go.sum 文件是运行 go test 命令自动生成的，里面有直接依赖和间接依赖的所有模块的导入路径、版本号和哈希值，可以确保下次获取的第三方依赖及其版本与本次完全相同，即保证了可重复构建。

我们最后进入 $GOPATH/pkg 目录，发现多了一个 mod 子目录，同时 mod 下有两个子目录：

$ pwd
/Users/zhangxiaolong/Desktop/D/go-workspace/pkg/mod
zhangxiaolongdeMacBook-Pro:mod zhangxiaolong$ ls
cache       github.com

注：细节先不用深究，我们仅知道 $GOPATH/pkg/mod 目录下是 go mod 的缓存就可以了。当运行 go run，go build，go test 等命令时，如果 go mod 缓存中有依赖项，则直接获取，否则先拉取到缓存，然后再从缓存中获取。

当用户使用了 go mod 机制管理依赖包后，就弃用了 GOPATH mode，而这时 go mod 的缓存仍然放在 $GOPATH/pkg/mod 目录下。貌似 go mod 与环境变量 GOPATH 仍然有一点点关系，但这种关系非常弱，因为用户可以在任意目录放代码工程，而不再局限在 $GOPATH/src 目录下了。

更进一步，如果我们不配置环境变量 GOPATH ，go mod 缓存会存放在哪里？

我们先取消环境变量 GOPATH 的设置：

$ echo $GOPATH
/Users/zhangxiaolong/Desktop/D/go-workspace
$ unset GOPATH
$ echo $GOPATH

$

我们再运行一下测试，发现测试仍然通过，并且 go test 命令在正式测试前下载了所有的依赖项：与我们设置了 GOPATH 环境变量的情况完全相同

$ go test -v ./calculator/
go: downloading github.com/smartystreets/goconvey v1.6.4
go: downloading github.com/jtolds/gls v4.20.0+incompatible
go: downloading github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d
=== RUN   TestAdd

  TestAdd 
    normal case ✔


1 total assertion

--- PASS: TestAdd (0.00s)
PASS
ok      github.com/agiledragon/hello-gomod/calculator   0.008s

注：我们取消了 GOPATH 环境变量后，go mod 缓存就会自动下载到 $HOME/go/pkg/mod 目录下。本质上，$HOME/go 就是 GOPATH 变量的值（从 go1.8 版本开始，GOPATH 变量有了默认值 $HOME/go）。

go mod 工程的 CI

go mod 工程上线 CI 后，代码中没有了存放第三方依赖项的 vendor 目录，编译时需要实时拉取第三方依赖。

这里有两个问题：

CI 运行过程中不能访问大网（公网）
CI 运行过程中对性能和可靠性要求高，从大网下载所有依赖项有风险

针对这些问题，有两种解决方案：

使用 go mod vendor 命令生成一个 vendor 目录，并上传到代码库
搭建一个私有的 go proxy

关于如何搭建一个私有的 go proxy，本文不进行深入讨论，在后续的文章中可能会涉及。

我们在模块根目录下运行 go mod vendor 命令：

$ go mod vendor
go: downloading github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1

注：我们运行 go test 命令时，没有下载 gopherjs 模块，而运行 go mod vendor 命令时，自动下载了一个新的依赖项。

我们进入到 vendor 目录，并查看子目录：

$ cd vendor
$ ls
github.com  modules.txt

一个代码工程从 GOPATH mode 迁移到 module-aware(go mod) mode 时，可能的三种状态：

state1：GOPATH mode vendor
state2：go.mod + go.sum + module-aware mode vendor
state3：go.mod + go.sum + go proxy

对于一个大型项目，有很多个团队，而每个团队又有多个 go 工程，作者建议迁移 go mod 时增加临时状态 state2，即工程状态变化为：state1 ==> state2 ==> state3；对于一个小型项目，总共只有几个 go 工程，作者建议迁移 go mod 时直接到目标状态 state3，即工程状态变化为：state1 ==> state3。

小结

本文通过一个简单的案例，带领读者初步体验了 go mod 机制的强大。读者在轻松愉悦的旅途中理清了 go mod 的基本原理，掌握了 go mod 的简单用法，后续可以尝试在学习或工作中使用 go mod 来管理工程的依赖项，从而真实感受 go mod 的魅力。

下一篇文章《gomonkey 的 go mod 改造之旅》预告：
gomonkey 是作者自研的一款 go 语言的打桩框架，深受国内外 gophers 的喜爱，目前已有 336 个 star。gomonkey 在运行时不依赖第三方包，长期以来一直保持 GOPATH mode 并不会出现任何问题。gomonkey 提供了详尽的测试用例，虽然运行这些用例需要依赖第三方包（测试框架），但对于大多数用户来说他们并不实际运行这些用例，而是仅仅将这些用例当作 API 文档来学习。我们尝试用 go mod 机制来改造 gomonkey 工程，希望能给读者带来更佳的用户体验。