在学完 Go 的语法之后,就可以开始写代码了,但一个项目中不可能只有几个代码文件,而是由很多代码组成,下面这篇文章将告诉你如何组织这些 Go 代码。
原文地址:https://golang.org/doc/code
写在前面
这篇文档演示了基于 Go Modules(模块) 的包的开发流程,并介绍了获取、构建和安装 Go 模块、包、命令时使用的 Go 工具。
注意:这篇文章会假设你在使用 Go1.13或更高版本,并且没有设置 GO111MODULE 环境变量。如果需要是使用 Go Modules 的版本,看这里。
组织代码
Go 代码是通过 package(包) 来组织。包是同一目录下所有源文件的集合,它们会被编译在一起。一个源文件中定义的函数、类型、变量和常量对同一个包下的其他源文件都是可见的。
一个 repository(仓库)中包含一个或多个 module(模块)。模块由多个相关的包组成,并且会一起发布。一个仓库中通常只会包含一个模块,这个模块位于仓库的根目录。go.mod 中会声明模块路径,该模块中的所有包再被导入的时候,到会把这个路径当做前缀加上。一个模块的范围是从包含 go.mod 的文件夹及文件夹中所有的文件夹(包括所有的子文件夹),到那些包含了 go.mod 的子文件夹(如果有的话)为止。
在代码可以编译之前,你不需要把代码推送到远程的仓库。模块可以不属于任何残酷,仅仅在本地定义。把要发布的代码组织好是一个好习惯。
每个模块的路径不仅仅用于作为导入包的前缀,在使用 go 命令下载包的时候也需要用到。比如,为了下载 golang.org/x/tools 模块,go 命令就会找到 https://golang.org/x/tools(详情看这里)。
导入路径是用来导入包的字符串。一个包的导入路径就是模块的路径加上这个包在模块中的子目录路径。比如模块 github.com/google/go-cmp 包含一个包,在 cmp 目录下。那么这个包的导入路径就是 github.com/google/go-cmp/cmp。标准库中的包没有模块路径前缀。
你的第一个程序
在编译和运行一个简单程序之前,要选择一个模块路径(在这里用 example.com/user/hello)并且创建一个 go.mod 文件来描述这个模块:
$ mkdir hello # 可选,如果已经存在,直接把项目拉取到本地
$ cd hello
$ go mod init example.com/user/hello
go: creating new go.mod: module example.com/user/hello
$ cat go.mod
module example.com/user/hello
go 1.14
Go 源文件的第一个语句必须是包名。可执行的文件必须使用 main 作为包名。
接下来,在当前目录下创建一个 hello.go 文件,写入以下代码:
package main
import "fmt"
func main() {
fmt.Println("Hello, world.")
}
现在你可以使用 go 命令来编译并安装这个程序:
$ go install example.com/user/hello
这个命令将会编译 hello 程序,产生一个可执行文件。这个命令会被安装为 $HOME/go/bin/hello
(在 Windows 系统中,路径是 %USERPROFILE%\go\bin\hello.exe
)。
安装的目录通过 GOPATH 和 GOBIN 环境变量来控制。如果 GOBIN 设置了,就会安装到 GOBIN 指定的目录。如果 GOPATH 设置了,这个就会安装到 GOPATH 目录下的子目录 bin 中。否则就会被安装到默认的 GOPATH 子目录下 bin 下($HOME/go 或者 %USERPROFILE%\go)。
你可以使用 go env
命令来设置环境变量的默认值:
$ go env -w GOBIN=/somewhere/else/bin
使用 go env -u
删除 go env -w 设置的变量值:
$ go env -u GOBIN
像 go install
这样的命令可以在模块的根目录及其子目录中使用。如果当前的工作目录不在 example.com/user/hello 模块中,go install 会失败。
为了方便起见,go 命令接受工作目录的相对路径,如果没有给出其他路径,则默认为当前工作目录下的包。因此,在我们的工作目录中,以下命令都是等价的:
$ go install example.com/user/hello
$ go install .
$ go install
接下来,我们来运行一下这个程序,确保功能正常。为了使用方便,我们把安装目录增加到系统 PATH 路径下,这样就可以直接在命令行使用程序:
# windows 用户看这里: https://github.com/golang/go/wiki/SettingGOPATH
# 设置 %PATH%.
$ export PATH=$PATH:$(dirname $(go list -f '{{.Target}}' .))
$ hello
Hello, world.
如果你在用版本管理系统,现在就可以初始化仓库,添加文件,并提交第一次修改。这个步骤是可选的,在写代码的时候,不一定要使用版本管理系统:
$ git init
Initialized empty Git repository in /home/user/hello/.git/
$ git add go.mod hello.go
$ git commit -m "initial commit"
[master (root-commit) 0b4507d] initial commit
1 file changed, 7 insertion(+)
create mode 100644 go.mod hello.go
go 命令通过请求相应的 HTTPS URL 并读取 HTML 响应中的元数据来定位给定模块的存储库(参见 go help importpath)。许多代码托管服务已经为包含 Go 代码的存储库提供了元数据,因此,为了让你的模块可以顺利的被人找到,直接使用存储库的 URL 作为你的模块路径。
导入当前模块内的包
让我们写一个 morestrings
包并在 hello 程序中使用它。首先,为这个包创建一个目录:$HOME/hello/morestrings,并创建一个 reverse.go 文件,填充下面的内容:
// Package morestrings implements additional functions to manipulate UTF-8
// encoded strings, beyond what is provided in the standard "strings" package.
package morestrings
// ReverseRunes returns its argument string reversed rune-wise left to right.
func ReverseRunes(s string) string {
r := []rune(s)
for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
r[i], r[j] = r[j], r[i]
}
return string(r)
}
因为我们的 ReverseRunes 方法以大写字母开头,所以它是导出的,可以在其他的包中导入 morestrings 包来使用.
使用 go build 命令编译测试一下这个包:
$ cd $HOME/hello/morestrings
$ go build
这不会产生输出文件,相反,它将已编译的包保存在本地构建缓存中。
在确认 morestrings 是可编译的,就可以在 hello 程序中使用它。然后修改 /hello/hello.go 来使用 morestrings 包:
package main
import (
"fmt"
"example.com/user/hello/morestrings"
)
func main() {
fmt.Println(morestrings.ReverseRunes("!oG ,olleH"))
}
安装 hello 程序:
$ go install example.com/user/hello
运行这个新版的程序,你应该可以看见一个反转的字符串:
$ hello
导入远程模块的包
导入路径可以使用版本管理系统(如 Git 或 Mercurial)获取源码,go 工具会自动从远程仓库获取包。例如,在程序中使用 github.com/google/go-cmp/cmp:
package main
import (
"fmt"
"example.com/user/hello/morestrings"
"github.com/google/go-cmp/cmp"
)
func main() {
fmt.Println(morestrings.ReverseRunes("!oG ,olleH"))
fmt.Println(cmp.Diff("Hello World", "Hello Go"))
}
当你运行 go install,go build,或者 go run 等命令时,就会自动下载这些远程的模块并记录到 go.mod 文件中:
$ go install example.com/user/hello
go: finding module for package github.com/google/go-cmp/cmp
go: downloading github.com/google/go-cmp v0.4.0
go: found github.com/google/go-cmp/cmp in github.com/google/go-cmp v0.4.0
$ hello
Hello, Go!
string(
- "Hello World",
+ "Hello Go",
)
$ cat go.mod
module example.com/user/hello
go 1.14
require github.com/google/go-cmp v0.4.0
模块依赖关系会自动下载到 GOPATH 下的 pkg/mod 子目录。某个模块的给定版本的下载内容在所有需要该版本的其他模块之间共享,因此 go 命令将这些文件和目录定义为只读。如果要删除这些下载的模块,可以使用:
$ go clean -modcache
测试
Go 有一个轻量级的测试框架,包含 go test
命令和 testing
包。
测试文件的结尾必须以 _test.go
结尾,并且测试函数的名称都是 TestXXX,方法签名是 func(t *testing.T)。测试框架会运行每一个函数,如果函数调用了t.Error 或者 t.Fail 函数,那么这个测试就可以被认为失败。
为 morestrings 添加一个测试 $HOME/hello/morestrings/reverse_test.go,写入以下代码:
package morestrings
import "testing"
func TestReverseRunes(t *testing.T) {
cases := []struct {
in, want string
}{
{"Hello, world", "dlrow ,olleH"},
{"Hello, 世界", "界世 ,olleH"},
{"", ""},
}
for _, c := range cases {
got := ReverseRunes(c.in)
if got != c.want {
t.Errorf("ReverseRunes(%q) == %q, want %q", c.in, got, c.want)
}
}
}
使用 go test 来运行测试:
$ go test
PASS
ok example.com/user/morestrings 0.165s
运行 go help test
或者查看文档来看更多细节。