Golang go 命令

1.简介

go 是管理 Go 代码的工具，但不仅仅用于编译 Go 代码。

2.格式

go COMMAND [ARGS]

子命令 COMMAND ：

help：显示指定命令的详细帮助信息
build：编译包与依赖
clean：移除当前源码包和关联源码包里面编译生成的文件
doc：展示包与符号的文档说明
env：打印Go的环境信息
bug：打开默认的浏览器让你汇报一个bug
fix：针对你提供的代码，自动将旧的API替换成新的API
fmt：格式化Go代码
generate：用于在编译前自动化生成某类代码
get：下载并安装指定的包及其依赖
install：编译包与依赖，可执行文件放到$GOPATH/bin，依赖包放到$GOPATH/pkg
list：查看当前安装的全部 package
mod：模块维护。管理工程依赖的第三方库
run：编译并运行。运行结束会删除编译生成的可执行文件
test：后缀为_test.go的文件在build的时候会被忽略，go test用于编译它们并生成测试程序并运行
tool：运行指定的Go工具
version：打印Go版本信息
vet： 代码静态检查，报告代码中的语法错误

3.命令详解

go help

go help 用于查看某个命令或主题的帮助信息。

命令格式：

go help CMD
go help TOPIC

示例：

# 查看 go mod 命令用法
go help mod
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
...

# 查看测试函数说明
go help testfunc
The 'go test' command expects to find test, benchmark, and example functions
in the "*_test.go" files corresponding to the package under test.
...

go version

简介：

查看 Go 版本信息。

格式：

go version [-m] [-v] [file ...]

示例：

# 查看 Go 版本
go version
go version go1.10.2 linux/amd64

go env

简介：

用于查看和设置 Go 环境变量。

格式：

go env [-json] [-u] [-w] [var ...]

示例：

# 查看 Go 所有环境变量
go env
'GOARCH="amd64"
GOBIN="/data/home/go_proj/going_proj/bin"
GOCACHE="/home/dablelv/.cache/go-build"
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/dablelv:/data/home/go_proj/going_proj"
GORACE=""
GOROOT="/usr/local/go"
...

# 以 JSON 格式显示 Go 环境变量
go env -json

# 查看指定环境变量
go env NAME

# 删除环境变量
go env -u NAME

# 设置环境变量
go env -w NAME=VALUE

go get

简介

将依赖项添加到当前模块并安装它们。

go get 干了三件事：

• 一是更新 go.mod 文件将指定包及其版本加入其中；

• 二是下载包源码至模块缓存（GOPATH/pkg/mod）；

• 三是安装包，生成二进制程序至GOPATH/bin（从 Go 1.17 版本开始，为了更加符合其语义，该功能被废弃，改用go install）。

注意： 如果包中不包含可执行文件，则不会执行第三步，即 go get 操作成功后 GOPATH/bin 目录下不会有任何编译好的二进制文件。

格式

go get [-d] [-t] [-u] [-v] [-insecure] [build flags] [packages]

选项：

-d 只更新 go.mod 和下载，不安装。
-t 同时下载需要为运行测试所需要的包。
-u 更新包至最新的次版本号（minor）或修订号（patch），如果有更新的话。
-u=patch 更新包至最新的修订号（patch），如果有更新的话。注意不是 -u patch。
-v 显示操作流程的日志及信息，方便检查错误。
-insecure 允许使用不安全的 HTTP 方式进行下载操作。

示例

（1）不加选项与参数执行 go get。

为当前模块添加依赖，即更新 go.mod 和 go.sum 文件（不存在则创建）。

go get

（2）添加对包的依赖或将其升级到最新版本。

go get example.com/pkg

（3）将包升级或降级到指定版本

go get example.com/pkg@v1.2.3

有关模块的详细信息，请参阅 https://golang.org/ref/mod。

有关包的详细信息，请参阅 go help packages。

go mod

简介

go mod 提供对模块的访问和操作。

请注意，所有 go 命令都内置了对模块的支持，不仅仅是go mod。例如，日常添加、删除、升级、降级，应该使用go get。

有关模块功能的概述，请参阅go help mod <command>。

格式

go mod <command> [arguments]

子命令

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

示例

（1）在当前目录中初始化新模块，模块名为你项目名。一般是在首次创建项目时使用，将生成go.mod文件。

go mod init [module-path]

（2）下载 modules 到本地 cache。

# 下载所有依赖的 modules
go mod download [all]

# 下载指定名称的 modules
go mod download PATH@VERSION

（3）添加缺少的模块并删除未使用的模块，一般用来更新 go.mod 文件。

go mod tidy

go test

简介

go test 是 Go 用来执行测试函数（test function）、基准函数（benchmark function）和示例函数（example function）的命令。

执行 go test 命令，它会在*_test.go文件中寻找 test、benchmark 和 example 函数来执行。测试函数名必须以 TestXXX 开头，基准函数名必须以 BenchmarkXXX 开头，示例函数必须以 ExampleXXX 开头。

// test 测试函数
func TestXXX(t *testing.T) { ... }

// benchmark 基准函数
func BenchmarkXXX(b *testing.B) { ... }

// examples 示例函数，其相关命名方式可以查看第一篇文章
func ExamplePrintln() {
    Println("The output of\nthis example.")
    // Output: The output of
    // this example.
}

关于更多测试函数的信息请查看go help testfunc。

命令格式如下：

go test [build/test flags] [packages] [build/test flags & test binary flags]

go test 自动测试指定的包。它以以下格式打印测试结果摘要：

ok   archive/tar   0.011s
FAIL archive/zip   0.022s
ok   compress/gzip 0.033s
...

然后是每个失败包的详细输出。

go test 重新编译每个包中后缀为_test.go的文件。这些文件可以包含测试函数、基准函数和示例函数。有关更多信息，请参阅“go help testfunc”。每个列出的包都会导致执行一个单独的测试二进制文件。注意名称以_或.开头的文件即使后缀是_test.go将被忽略。

测试文件中如果声明的包后缀为_test将被作为单独的包来编译，然后与主测试二进制文件链接并运行。

go test 命令还会忽略 testdata 目录，该目录用来保存测试需要用到的辅助数据。

go test 有两种运行模式：

（1）本地目录模式，在没有包参数（如 go test 或 go test -v）调用时发生。在此模式下，go test 编译当前目录中找到的包和测试，然后运行测试二进制文件。在这种模式下，caching 是禁用的。在包测试完成后，go test 打印一个概要行，显示测试状态、包名和运行时间。

（2）包列表模式，在使用显示包参数调用 go test 时发生（例如 go test math，go test ./… 甚至是 go test .）。在此模式下，go 测试编译并测试在命令上列出的每个包。如果一个包测试通过，go test 只打印最终的 ok 总结行。如果一个包测试失败，go test 将输出完整的测试输出。如果使用 -bench 或 -v 选项，则 go test 会输出完整的输出，甚至是通过包测试，以显示所请求的基准测试结果或详细日志记录。

注意： 描述软件包列表时，命令使用三个点作为通配符。如测试当前目录及其子目录中的所有软件包。

go test ./...

仅在包列表模式下，go test 会缓存成功的包测试结果，以避免不必要的重复运行测试。当测试结果可以从缓存中恢复时，go tes t将重新显示以前的输出，而不是再次运行测试二进制文件。发生这种情况时，go test 打印 “(cached)” 以代替摘要行中的已用时间。

缓存中匹配的规则是，运行涉及相同的测试二进制文件，命令行上的选项完全来自一组受限的“可缓存”测试选项，定义为 -benchtime、-cpu、-list、-parallel、-run、-short 和 -v。如果运行 go test 时任何测试选项或非测试选项在此集合之外，则不会缓存结果。要禁用缓存，请使用除可缓存选项之外的任何测试选项或参数。明确禁用测试缓存的惯用方法是使用 -count=1。测试在包的根目录（通常为 $GOPATH）打开的文件和依赖的环境变量，只有不发生变化时才能匹配缓存。

被缓存的测试结果将被视为立即执行，因此无论 -timeout 设置如何，成功的包测试结果都将被缓存和重用。

test flag

除 build 选项外，go test 本身处理的选项包括：

-args
    Pass the remainder of the command line (everything after -args)
    to the test binary, uninterpreted and unchanged.
    Because this flag consumes the remainder of the command line,
    the package list (if present) must appear before this flag.

-c
    Compile the test binary to pkg.test but do not run it
    (where pkg is the last element of the package's import path).
    The file name can be changed with the -o flag.

-exec xprog
    Run the test binary using xprog. The behavior is the same as
    in 'go run'. See 'go help run' for details.

-i
    Install packages that are dependencies of the test.
    Do not run the test.
    The -i flag is deprecated. Compiled packages are cached automatically.

-json
    Convert test output to JSON suitable for automated processing.
    See 'go doc test2json' for the encoding details.

-o file
    Compile the test binary to the named file.
    The test still runs (unless -c or -i is specified).

有关构建选项的更多信息，请参阅“go help build”。有关指定软件包的更多信息，请参阅“go help packages”。

test/binary flags

以下选项同时支持测试二进制文件和 go test 命令。

主要分为两类，一类是控制测试行为，一类是用于状态分析。

控制测试行为选项：

-bench regexp
    Run only those benchmarks matching a regular expression.
    By default, no benchmarks are run.
    To run all benchmarks, use '-bench .' or '-bench=.'.
    The regular expression is split by unbracketed slash (/)
    characters into a sequence of regular expressions, and each
    part of a benchmark's identifier must match the corresponding
    element in the sequence, if any. Possible parents of matches
    are run with b.N=1 to identify sub-benchmarks. For example,
    given -bench=X/Y, top-level benchmarks matching X are run
    with b.N=1 to find any sub-benchmarks matching Y, which are
    then run in full.

-benchtime t
    Run enough iterations of each benchmark to take t, specified
    as a time.Duration (for example, -benchtime 1h30s).
    The default is 1 second (1s).
    The special syntax Nx means to run the benchmark N times
    (for example, -benchtime 100x).

-count n
    Run each test and benchmark n times (default 1).
    If -cpu is set, run n times for each GOMAXPROCS value.
    Examples are always run once.

-cover
    Enable coverage analysis.
    Note that because coverage works by annotating the source
    code before compilation, compilation and test failures with
    coverage enabled may report line numbers that don't correspond
    to the original sources.

-covermode set,count,atomic
    Set the mode for coverage analysis for the package[s]
    being tested. The default is "set" unless -race is enabled,
    in which case it is "atomic".
    The values:
	set: bool: does this statement run?
	count: int: how many times does this statement run?
	atomic: int: count, but correct in multithreaded tests;
		significantly more expensive.
    Sets -cover.

-coverpkg pattern1,pattern2,pattern3
    Apply coverage analysis in each test to packages matching the patterns.
    The default is for each test to analyze only the package being tested.
    See 'go help packages' for a description of package patterns.
    Sets -cover.

-cpu 1,2,4
    Specify a list of GOMAXPROCS values for which the tests or
    benchmarks should be executed. The default is the current value
    of GOMAXPROCS.

-failfast
    Do not start new tests after the first test failure.

-list regexp
    List tests, benchmarks, or examples matching the regular expression.
    No tests, benchmarks or examples will be run. This will only
    list top-level tests. No subtest or subbenchmarks will be shown.

-parallel n
    Allow parallel execution of test functions that call t.Parallel.
    The value of this flag is the maximum number of tests to run
    simultaneously; by default, it is set to the value of GOMAXPROCS.
    Note that -parallel only applies within a single test binary.
    The 'go test' command may run tests for different packages
    in parallel as well, according to the setting of the -p flag
    (see 'go help build').

-run regexp
    Run only those tests and examples matching the regular expression.
    For tests, the regular expression is split by unbracketed slash (/)
    characters into a sequence of regular expressions, and each part
    of a test's identifier must match the corresponding element in
    the sequence, if any. Note that possible parents of matches are
    run too, so that -run=X/Y matches and runs and reports the result
    of all tests matching X, even those without sub-tests matching Y,
    because it must run them to look for those sub-tests.

-short
    Tell long-running tests to shorten their run time.
    It is off by default but set during all.bash so that installing
    the Go tree can run a sanity check but not spend time running
    exhaustive tests.

-shuffle off,on,N
	Randomize the execution order of tests and benchmarks.
	It is off by default. If -shuffle is set to on, then it will seed
	the randomizer using the system clock. If -shuffle is set to an
	integer N, then N will be used as the seed value. In both cases,
	the seed will be reported for reproducibility.

-timeout d
    If a test binary runs longer than duration d, panic.
    If d is 0, the timeout is disabled.
    The default is 10 minutes (10m).

-v
    Verbose output: log all tests as they are run. Also print all
    text from Log and Logf calls even if the test succeeds.

-vet list
    Configure the invocation of "go vet" during "go test"
    to use the comma-separated list of vet checks.
    If list is empty, "go test" runs "go vet" with a curated list of
    checks believed to be always worth addressing.
    If list is "off", "go test" does not run "go vet" at all.

状态分析选项：

-benchmem
    Print memory allocation statistics for benchmarks.

-blockprofile block.out
    Write a goroutine blocking profile to the specified file
    when all tests are complete.
    Writes test binary as -c would.

-blockprofilerate n
    Control the detail provided in goroutine blocking profiles by
    calling runtime.SetBlockProfileRate with n.
    See 'go doc runtime.SetBlockProfileRate'.
    The profiler aims to sample, on average, one blocking event every
    n nanoseconds the program spends blocked. By default,
    if -test.blockprofile is set without this flag, all blocking events
    are recorded, equivalent to -test.blockprofilerate=1.

-coverprofile cover.out
    Write a coverage profile to the file after all tests have passed.
    Sets -cover.

-cpuprofile cpu.out
    Write a CPU profile to the specified file before exiting.
    Writes test binary as -c would.

-memprofile mem.out
    Write an allocation profile to the file after all tests have passed.
    Writes test binary as -c would.

-memprofilerate n
    Enable more precise (and expensive) memory allocation profiles by
    setting runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'.
    To profile all memory allocations, use -test.memprofilerate=1.

-mutexprofile mutex.out
    Write a mutex contention profile to the specified file
    when all tests are complete.
    Writes test binary as -c would.

-mutexprofilefraction n
    Sample 1 in n stack traces of goroutines holding a
    contended mutex.

-outputdir directory
    Place output files from profiling in the specified directory,
    by default the directory in which "go test" is running.

-trace trace.out
    Write an execution trace to the specified file before exiting.

常用选项

-bench regexp
	只执行匹配对应正则表达式的 benchmark 函数，如执行所有性能测试 "-bench ." 或 "-bench=."
-benchtime t
	对每个 benchmark 函数运行指定时间。如 -benchtime 1h30，默认值为 1s。特殊语法 Nx 表示运行基准测试 N 次（如 -benchtime 100x）
-run regexp
	只运行匹配对应正则表达式的 test 和 example 函数，例如 "-run Array" 那么就执行函数名包含 Array 的单测函数
-cover
	开启测试覆盖率
-v
	显示测试的详细命令

示例

假设在文件 add.go 有一个被测试函数

package hello

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

• 测试函数（test function）

在测试文件 add_test.go 添加一个单元测试函数 TestAdd：

package hello

func TestAdd(t *testing.T) {
	sum := Add(5, 5)
	if sum == 10 {
		t.Log("the result is ok")
	} else {
		t.Fatal("the result is wrong")
	}
}

比如使用 -run 来运行指定单元测试函数，发现只运行了 TestAdd 测试函数。

go test -v -run TestAdd main/hello
=== RUN   TestAdd
    add_test.go:16: the result is ok
--- PASS: TestAdd (0.00s)
PASS
ok      main/hello      0.170s

• 基准函数（benchmark function）

添加一个性能测试函数 BenchmarkAdd：

package hello

func BenchmarkAdd(b *testing.B) {
	for n := 0; n < b.N; n++ {
		Add(1, 2)
	}
}

运行指定基准函数：

go test -bench BenchmarkAdd main/hello
goos: windows
goarch: amd64
pkg: main/contain
cpu: Intel(R) Core(TM) i7-9700 CPU @ 3.00GHz
BenchmarkAdd-8          1000000000               0.2333 ns/op
PASS
ok      main/contain    0.586s

• 示例函数（example function）

package hello

func ExampleAdd() {
	fmt.Println(Add(1, 2))
	// Output: 3
}

运行指定示例函数：

go test -v -run ExampleAdd main/contain
=== RUN   ExampleAdd
--- PASS: ExampleAdd (0.00s)
PASS
ok      main/contain    (cached)

注意： 示例函数类似于测试函数，但不是使用 *testing.T 来报告成功或失败，而是将输出打印到 os.Stdout。如果示例函数中的最后一条注释以“Output:”开头，则将输出与注释进行精确比较（参见上面的示例）。如果最后一条注释以“Unordered output:”开头，则将输出与注释进行比较，但忽略行的顺序。编译了一个没有此类注释的示例函数，会被编译但不会被执行。如果在“Output:”之后没有文本，示例函数仍会被编译并执行，并且预期不会产生任何输出。

• 获取每个函数的单测覆盖率。

如果您想查找没有被测试覆盖的函数，可以使用 -coverprofile 选项将覆盖率报告输出到文件中。

go test -coverprofile cover.out ./...

然后使用内置的 go tool cover 命令来查看覆盖率报告。

go tool cover -func cover.out

上面使用 -func 选项可以输出每个函数的单测覆盖率概要信息。类似如下：

github.com/dablelv/go-huge-util/cmp/cmp.go:21:                  Cmp                             100.0%
github.com/dablelv/go-huge-util/cmp/cmp.go:35:                  Compare                         95.5%
github.com/dablelv/go-huge-util/cmp/cmp.go:85:                  CompareLT                       0.0%
...

---

参考文献

The Go Programming Language.Command go
语义化版本 2.0.0
Deprecation of ‘go get’ for installing executables
Go 测试，go test 工具的具体指令 flag