包与模块:一个项目怎么组织

难度 ★☆☆☆☆ · 前置:错误是返回值:if err != nil 在做什么 | 一句话结论:包是目录,import 写的是地址,调用写的是包名,而 Go 用大小写、import 环和 internal 三样东西逼着你把依赖的方向摆正。

写这一篇之前我回头翻了翻自己第一个算得上正式的项目,七个文件全躺在一个目录里,每个开头都是 package main,当时觉得挺省事,反正 go run 点一下就能出结果,还能少想一层目录结构。麻烦是三个月后来的,另一个小工具要复用里面算校验位的那十几行,我打开一看,那十几行跟一个全局变量、一个命令行解析函数黏在同一个文件里,搬走一半就编不过,剩下的那半又反过来依赖那个全局变量,绕了一圈才发现想复用的东西根本摘不出来。Go 里被别人引用的最小单位不是文件,是包,而包的边界就是目录,这句话听着像教科书上的定义,落到手上其实是个提醒,你把文件扔进哪个目录,就是在决定以后什么东西能被别的地方拿走。

拆包这件事,早拆比晚拆便宜。

先把一个文件拆成四个目录

从一个能跑的最小结构开始。建一个空目录,进去敲 go mod init demo,屏幕上回来一句 go: creating new go.mod: module demo,目录里多出一个 go.mod,打开就两行。

这个文件是模块的根,第一行那个 demo 是模块的路径,你自己写的每一个包都挂在它后面,全名是模块路径接一个斜杠再接子目录。然后照着这个形状建目录,根目录放 main.go,greet/ 放 greet.go,mathx/ 放 mathx.go,internal/secret/ 放 secret.go,四个 .go 文件的第一行分别写 package main、package greet、package mathx、package secret,这一行是包声明,也是这一篇所有规矩的起点。

根目录那个 main.go 我没有塞进 cmd/ 或者 app/ 里。只有一个入口的时候,多套一层目录换来的代价是每次 go run 都要多敲一段路径,收益要等到你有第二个入口才兑现,这笔账不划算。

四个目录建好,用 go list 数一遍,末尾那三个点意思是这个目录连同它下面所有的子目录,列出来的每一行都是一个能单独被 import 的包。

1
2
3
4
5
$ go list ./...
demo
demo/greet
demo/internal/secret
demo/mathx

这四行值得盯一会儿,因为它一次讲清了两件事,而且这两件事我当初是一起搞混的。根目录自己也是一个包,全名就是模块路径 demo,后面不带任何后缀,所以 main.go 里的 package main 跟目录名没有关系,那是另一套规矩。子目录的包全名是 demo 前缀加斜杠加目录名,跟你写在文件第一行的那个词并不是一回事,下一节专门拆开说。现在先记一个能照着数的办法,行数就是包的数量,凭空多出来的行要么是多建了一个空目录,要么是某个目录里的包名写岔了,两种毛病都会让后面的 import 莫名其妙地失败,而报错信息往往不提最容易看走眼的地方。

跑起来看看,go run 后面那个点代表当前目录这个包,四个包是被 main.go 这一个文件串起来的。

1
2
3
4
5
6
7
8
$ go run .
init: mathx
init: greet
init: main
你好,老康
3 + 4 = 7
名字的码位之和 = 57016
internal-ok

前三行 init 是怎么冒出来的,第五节讲。先看后四行,main 里调了 greet.Hello、mathx.Add、greet.Score,还有 internal/secret.Token,一段代码把四个方向上的东西拉到了一起。

这里顺带记一个常犯的错,go run 后面如果写的不是点而是某个子目录,比如 go run ./greet,得到的是一句 package demo/greet is not a main package。子目录是一个包,不是一段程序,只有包名叫 main 的目录才产得出能跑的东西,这个错误和下一节那个包名写错的错误长得很像,病根却完全不同,一个是没入口,一个是名字对不上。

四个目录,四个包,一个入口。

四个包之间的依赖方向:main 引 greet,greet 引 mathx,internal/secret 只对模块内可见

目录名是地址,包名是称呼

这个区分我刚学的时候混了很久。import 后面那一串是路径,用来找到代码在哪,你在代码里敲的点号前面那个词是包名,用来称呼它。两件事可以不一样,Go 也允许它们不一样,而且允许得很自然,因为编译器找包只看路径,提你名字写错是另一条报错。现实里这种不一致到处都是,我从 GitHub 上拉下来的包有一半仓库的目录名末尾叫 go-something,文件里的包名却只留 something,go.sum 里还挂着完整路径,三样东西各写各的。一开始我以为是自己漏读了什么约定,翻了几遍文档也没找到那条线,后来才明白路径是给包管理器用的坐标,包名是给人打字用的简称,两者的读者根本不同,硬要统一反而会让路径变长、让调用变难看。

我拿一个叫 nametest 的模块试了一遍,目录叫 mathx,里面的文件第一行故意写成 package m,函数还是那个 Add。main 里照样 import 那个路径,调用的时候必须写 m.Add,写成 mathx.Add 编译器不认。给 go list 加个模板能把这个关系打出来,左边路径,右边包名。

1
2
3
$ go list -f '{{.ImportPath}} -> {{.Name}}' ./...
nametest -> main
nametest/mathx -> m

写成 mathx.Add 会得到什么也一并记下,这两条报错连在一起看才有意思,头一条说的是你引进来一个叫 m 的东西却没用,第二条说的是 mathx 这个名字压根不存在,编译器宁可相信你引了一个闲置的包,也没打算拿路径末尾那段当名字用。

1
2
.\main.go:6:2: "nametest/mathx" imported as m and not used
.\main.go:10:14: undefined: mathx

路径负责找到谁,包名负责怎么叫它。

大写能出门,小写出不去

greet 包里我写了两个函数,Hello 大写开头,hello 小写开头,从 main.go 里调一次小写那个。

1
2
# demo
.\main.go:10:20: undefined: greet.hello (but have Hello)

编译器没有骂我越权,它只是说这个名字不存在,然后顺手告诉我有一个叫 Hello 的。Go 的导出规则就一条,首字母大写,包外可见,首字母小写,只有本包自己能看见,这条规则对函数、变量、常量、类型、结构体字段一视同仁,没有 public、private 这类关键字,也没有写在别处的访问修饰符。字段这一层最容易漏,我写了个带 port 字段的结构体,从别的包读了一次,编译器给的句子跟函数那次不一样,多补了半句解释。

1
.\main.go:12:16: c.port undefined (cannot refer to unexported field port)

这两条报错合起来看就明白了,Go 不是在你访问的时候检查权限再拒绝,它压根不承认那个名字在包外存在,所以你看到的永远是 undefined,而不是 forbidden。理解这一点以后,我改别人的包时先看首字母再看实现,省掉很多弯路。

还有个副作用值得提前知道,go doc 只列大写的东西,别人拿到你的包,看到的就是这个界面。

1
2
3
4
5
$ go doc demo/greet
package greet // import "demo/greet"

func Hello(name string) string
func Score(name string) int

import 绕成一个圈,编译器就不走了

环是一定会踩到的,我这次是故意踩的。让 greet import mathx,同时让 mathx import greet,两边写的都是路径全名,go build ./… 停在编译期,一句话都没多给。

1
2
3
4
package demo
imports demo/greet from main.go
imports demo/mathx from greet.go
imports demo/greet from mathx.go: import cycle not allowed

这段输出值得看一眼它的格式,它不是一句话,是把你走过来的一整条路画了出来,main 从 main.go 引了 greet,greet 从 greet.go 引了 mathx,mathx 又从 mathx.go 回过头引 greet,走到这里断了。末尾那个 import cycle not allowed 翻论坛是没什么用的,因为它不是配置问题,是结构问题,两个包都想站在对方肩膀上,谁也不肯先降下来,而 Go 连先编译哪个都排不出来。解法只有三种,把共用的那部分挪进第三个包,把其中一个方向改成传函数或者传接口,或者干脆把两个包并成一个。我选的是第一种,把那几行纯计算的挪进 mathx,让 greet 只往下引,箭头变成单向,挪完编译就过了,从那以后谁想把箭头掉个头,编译器当天就会拦住。环这个东西急不得,它只能靠拆,拆的时候别心疼那几个看着顺手的函数调用,它们挪完位置往往还会更清楚一点。

init 跑在最前面,顺序不看你写在第几行

一个包里能写几个 init,一个文件里也能写几个,它们都在 main 之前跑完,顺序我拿三个包试了一遍。建了个模块,main 同时 import 了 aaa 和 zzz,而 aaa 自己又 import 了 zzz。

1
2
3
4
5
$ go run .
init: zzz
init: aaa, 看见 zzz
init: main
main, 引用了 aaa zzz

zzz 排在第一,虽然它在 main.go 的 import 列表里排在 aaa 后面,顺序是按依赖走的,被依赖的包先跑完,依赖它的才轮得上,main 永远排在最末尾。

那两个互不依赖的包呢。我又建了个模块,main.go 里把 bbb 写在 aaa 前面,跑出来 aaa 反而在前。

1
2
3
4
$ go run .
init: aaa
init: bbb
main 1 2

这一条别当成承诺,互不依赖的包之间,Go 规范没有规定谁先谁后,工具链现在按路径的字典序排,换个编译器版本、换个构建方式都可能变,能指望的只有拓扑序那一半,剩下那一半不要赌。

还有一个更细的层次,包里的变量赋值排在 init 前面,我写了个包,两个文件各有一个包级变量,其中一个文件里还塞了两个 init,输出是赋值、赋值、init、init、init,末了才轮到 main。

1
2
3
4
5
6
7
$ go run .
赋值: 变量 A
赋值: 变量 B
init 第 1 个
init 第 2 个
init in b.go
main 变量 A 变量 B

初始化只跑一次,别在里面放慢活。

internal 那道门只冲模块外面关

根目录下 internal/secret 这个名字是有作用的,不是给人看着舒服的。模块里的任何包都能 import demo/internal/secret,main.go 里我引了,编得过。模块外面就不行,我在旁边建了个 outside 模块,go.mod 里用 replace 指到 ../demo,再 import 同一个路径。

1
2
package outside
main.go:6:2: use of internal package demo/internal/secret not allowed

关键在门是按模块边界关的,不是按目录远近,同一个模块里 internal 随便引,出了这个模块,哪怕 replace 指的就是隔壁那个目录,一样进不去。我顺手把 outside 的 import 换成 demo/greet 又跑了一次,这次编得过,输出里少了 internal 那一行。

1
2
3
4
$ go run .
init: mathx
init: greet
你好,老康

这条规矩在入门阶段就用得上,因为它给了你一个不靠自觉的约定,还没想好要不要公开的东西扔进 internal,以后谁想 import,编译器会替你拒绝。

门是对外关的,对内一直开着。

三个命令当尺子

拆完包之后有三个命令可以当尺子用,一个都不改代码,只看。go vet ./… 和 gofmt -l . 跑完什么都不打印就是过了,一旦有输出,输出本身就是问题清单。go mod tidy 更有意思,我这个项目拆完包之后跑它,go.mod 一个字没变,md5 前后一样,也没多出 go.sum,因为它只管外面来的依赖,自己家的包一个都不算,没输出就是好消息。

你现在手上有什么

到这里你已经能把一个单文件程序拆成四个包,知道 import 写路径、调用写包名,知道大写才是门,知道 import 不能成环,知道 init 按拓扑序走,知道 internal 只拦模块外面的人。

这几条合起来就是 Go 组织一个项目的骨架,剩下的都是往这个骨架上挂东西。下一篇换一批天天要用的标准库,看看光靠官方那几十个包能写出多少东西来。

骨架搭好了,往里填就是。