go-modules

Sep 1 2019

Go Modules

A module is a collection of related Go packages that are versioned together as a single unit.

Modules record precise dependency requirements and create reproducible builds.

Go从1.11开始引入了原生的包管理器Go Modules，他的前身是vgo。

Example

go mod init github.com/my/repo
go: creating new go.mod: module github.com/my/repo
$ cat go.mod

module github.com/my/repo

require rsc.io/quote v1.5.2

go.mod

go.mod类似于node里的package.json，里面记录了当前module所需要的直接依赖以及间接依赖。

module github.com/pingcap/tidb # 模块的名字

require (
	github.com/BurntSushi/toml v0.3.1
	github.com/StackExchange/wmi v0.0.0-20180725035823-b12b22c5341f // indirect
	github.com/blacktear23/go-proxyprotocol v0.0.0-20180807104634-af7a81e8dd0d
	github.com/codahale/hdrhistogram v0.0.0-20161010025455-3a0bb77429bd // indirect
	github.com/coreos/bbolt v1.3.3 // indirect
	github.com/coreos/etcd v3.3.13+incompatible
	github.com/coreos/go-systemd v0.0.0-20181031085051-9002847aa142 // indirect
	github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f // indirect
	github.com/cznic/mathutil v0.0.0-20181122101859-297441e03548
	github.com/cznic/sortutil v0.0.0-20150617083342-4c7342852e65
	github.com/dgryski/go-farm v0.0.0-20190104051053-3adb47b1fb0f
	github.com/dustin/go-humanize v1.0.0 // indirect
	github.com/go-ole/go-ole v1.2.1 // indirect
	github.com/go-sql-driver/mysql v0.0.0-20170715192408-3955978caca4
	github.com/gogo/protobuf v1.2.0
	github.com/golang/protobuf v1.2.0
	github.com/google/btree v0.0.0-20180813153112-4030bb1f1f0c
	github.com/google/uuid v1.1.1
)

除了require， go.mod还支持一些其他的指令

1
2

replace example.com/some/dependency => example.com/some/dependency-fork v1.2.3 # 使用某个依赖的fork来替换这个依赖
replace example.com/original/import/path => /your/forked/import/path # 替换的路径可以是绝对路径

版本选择

所有的原生命令都会(go get go build)都会自动更新go.mod文件(注意在$GOPATH下需要设置GO111MODULE为on)，默认会添加依赖的最新版本到go.mod。

依赖使用Pseudo-versions

commit time commit hash

github.com/google/btree v0.0.0-20180813153112-4030bb1f1f0c

tag-version

go.sum

go.sum中记录了构件项目时所用的各个依赖的哈希值，用来对module进行验证

1	cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=

执行go mod verify可以检查你下载的依赖是否与go.sum记录的相匹配从而提高了安全性，go module下载的module可以在$GOPATH/pkg/mod里查看。

常用命令

Go {get，build，test}

Go mod provides access to operations on modules.

Note that support for modules is built into all the go commands，
not just 'go mod'. For example， day-to-day adding， removing， upgrading，
and downgrading of dependencies should be done using 'go get'.
See 'go help modules' for an overview of module functionality.

Usage:

	go mod <command> [arguments]

The commands are:

	download    download modules to local cache
	edit        edit go.mod from tools or scripts
	graph       print module requirement graph
	init        initialize new module in current directory
	tidy        add missing and remove unused modules
	vendor      make vendored copy of dependencies
	verify      verify dependencies have expected content
	why         explain why packages or modules are needed

Use "go help mod <command>" for more information about a command.

Migrate from govendor to go modules

go mod init会自动从vendor/vendor.json中拷贝依赖，也会自动生成一个包名，你也可以自己取一个名字，这将作为pkg的引用名字。
build your project
1. 成功 done
2. 失败
  1. 对于major version>=2的modules 需要手动在import path里加上major version如quoteV3 "rsc.io/quote/v3"，但是使用起来包名还是一样的。
  2. 错误信息是:”unknown revision”，这个错误的意思是远程分支没有这个commit，这时候需要确认自己需要的依赖的正确版本，用go get更新对应的依赖，然后回到步骤2。
go mod tidy，这个命令会整理去掉不需要的依赖。
(optional) 如果因为某些原因还是需要vendor目录，可以执行go mod vendor 会生成vendor目录(虽然官方不推荐)，目录底下有一个modules.txt文件记录了vendor的内容，编译时要使用vendor还需要加上编译参数-mod=vendor。

注意

go modules在$GOPATH下不是默认启用的(是的，在非$GOPATH下是默认启用的，go project可以放在任意的目录下了，看起来官方准备摒弃$GOPATH)，要在$GOPATH下启用需要export GO111MODULE="on"。
vendor模式下vendor目录当前不会拷贝非go语言的依赖 https://github.com/golang/go/issues/26366。

Eric