一个仓库放多个模块:workspace、internal 和 vendor

一个仓库放多个模块:workspace、internal 和 vendor
隔壁老康难度 ★★★☆☆ · 前置:go.mod 记你要什么,go.sum 记你拿到了什么 | 一句话结论:
go.work只让几个本地目录互相看见,它不改变任何模块的依赖解析规则,所以在 workspace 根目录敲go build ./...一定会失败,internal的边界也一分不让。
go.work 这个名字我第一次见到的时候,扫了一眼文档前两段就关掉了,因为它出现在那些讲 monorepo 的文章里,配的图是一个大仓库套着十几个小模块,看起来跟我没关系。我当时的项目结构很简单,一个服务一个仓库,顶多再有一个公共库,两边用 replace 指过去就行。这个判断在半年内一直没出错,直到我手上同时要改三个仓库的那种日子多起来,每天早上第一件事变成检查 replace 里那几条相对路径还在不在,换台机器就得重新指一遍。那种日子持续了大概两周,我把它当成正常的麻烦,因为身边没人抱怨这件事,所以我以为它就该这样。
具体场景是这样的一个东西。example.com/a 是工具库,example.com/b 是服务,b 依赖 a。以前改 a 的流程是先在 a 里改完,go build 加 go test 确认没问题,然后推一个临时 tag,回到 b 里 go get 那一串伪版本号,再跑 b 的测试。中间任何一步发现 a 改错了,这个循环要整段重来,因为那个伪版本号已经写进 b 的 go.mod 和 go.sum 了。
我试过的第一个土办法是在 b 的 go.mod 里加一句 replace example.com/a => ../a。这个办法能用,但只在那台机器上能用,因为 ../a 是相对路径,它假设了 a 和 b 是兄弟目录。换一个同事,或者换一个检出位置,这行就指空了。
后来我改成一个绝对路径,本机能跑,一提交就炸。
我把 replace 指向 D:/work/a 之后本地一切正常,CI 上却报哈希校验失败,因为 replace 到本地目录的模块不参与校验,别人的机器上根本没有这个目录。这件事一直拖到我发现它有个专门的名字,也就是 go.work。
use 那一行写的不是依赖,是目录
go.work 的语法短得有点不像话,整个文件一般就五六行,初始化也就一条命令。
1 | go work init ./a ./b |
use 后面跟的是目录,不是模块路径,也不是版本号。这一点值得单独说,因为它是 go.work 和 go.mod 最根本的区别。go.mod 里的 require example.com/a v0.9.1 说的是我要这个东西的某个版本,go.work 里的 use ./a 说的是这个东西就在我隔壁,别去网络上下载,直接用这个目录里的源码。一个描述的是版本,一个描述的是位置,位置这件事天生没法参与版本选择,所以 workspace 里的模块永远只有目录本身那一个身份,你想在里面写个 v0.9.1 都写不出来。这个约束初看像是功能缺失,用久了会发现它是把职责分清楚了,版本归 go.mod,位置归 go.work,两边各管一件事,谁也别越界。
这个区别解释了后面所有的行为。既然 use 认的是目录,它就不可能改变任何一个模块自己 go.mod 里的 require 行,b 里那句 require example.com/a 还老老实实在那儿,只是模块解析走到那里的时候被 workspace 拦下来,指到了本地磁盘。
版本选择这一层,workspace 一刀都没动。
位置和版本,本来就是两件事。
没有 go.work 的时候,报错看着像缺文件
把 go.work 删掉,在 b 里编译,看到的是这个。
1 | main.go:6:2: missing go.sum entry for module providing package example.com/a (imported by example.com/b); to add: |
这条报错很有迷惑性,它说缺 go.sum 条目,还热心地建议你 go get example.com/b。照着敲会发现这句话是错的,example.com/b 就是你当前这个模块自己,go get 它只会换来另一条错误。
真正缺的东西是 a 这个模块的源码,而 go.sum 之所以没有它的条目,是因为 a 从来没有被真正解析出来过。你可能会想,go.mod 里不是写着 require example.com/a v0.0.0 吗,怎么叫没解析。写着,但 v0.0.0 这个版本在网络上不存在,example.com/a 这个路径本身也解析不出仓库,所以模块解析在第一步就断了,断在拿不到源码,表现出来却是缺哈希。这中间隔了一整层逻辑,所以这条报错的指向性特别差,我第一次遇到的时候在这上面耗了半个下午,中间还试过删 go.sum 重新生成,当然没有用。
说它病得重,不如说病灶长在了别的地方。
真正的病根就是那句 require example.com/a v0.0.0。这行只有在别处有真东西的时候才有意义,而在 workspace 模式下它完全是多余的,甚至可以删掉。
删掉那行,再看。
1 | example.com/a |
两行,干净,一行一个模块,没有任何版本号。
我盯着这个输出看了几秒。
这就是 go.work 的定位,它替掉的是那些本来要写成 require 加 replace 的本地引用,而不是替掉 require 本身。用 go.work 之后,那两个模块的 go.mod 都不用再提对方一句,谁在 workspace 里谁就自动可见。这个设计的代价是可见性变成了运行环境的一部分,同一份代码在有 go.work 的目录树里能编过,换个目录就编不过,所以它只适合那种几个模块必须一起改的阶段。这个代价听起来不大,真踩进去的时候挺疼,因为它把一道本来写在文件里的约束挪到了一个不在版本控制里的东西上,而人对不在版本控制里的东西是没有警惕心的。
在 workspace 根目录敲 ./... 会失败
go.work 建好之后,人很自然地会站在仓库根目录敲一句 go build ./...。
1 | pattern ./...: directory prefix . does not contain modules listed in go.work or their selected dependencies |
这条报错我看了好几遍才读懂。./... 的意思是当前目录及其所有子目录里的包,但 workspace 根目录本身不是一个模块,它没有自己的包,它下面那些目录分别属于 ./a 和 ./b 两个模块。go 解析 ./... 的时候得先给这个模式找一个归属模块,找不到就干脆停了。
完整的说法是,./... 这个模式在任何一个模块目录里都会展开成那个模块下所有子目录中的包,它是相对某个模块定义的,而 workspace 根目录什么都没有,它只是一个装着几个模块的文件夹。所以这里不是 go 偷懒,也不是什么 bug,是这个模式本身没有落脚点。我在论坛上看到过有人把这条报错当成 workspace 功能不完善的证据,实际上它恰恰说明 ./... 从来没有过全局含义,我们以前觉得它有,只是因为我们一直站在模块里面敲它,误以为那个点指的就是当前目录。
保护的是你,代价是你得多敲几个字。
换个角度想,如果没有这层检查,go build ./... 会一次性把仓库里能编的东西全编一遍,包括那些你根本没打算参与构建的目录,比如 testdata 里故意写坏的示例代码,或者某个老版本服务的归档备份。我见过一个仓库在根目录跑 go vet ./... 直接跑挂了,就是因为翻到了 testdata 里的坏代码。
正确的写法是把模块路径显式列出来。
1 | go build ./a/... ./b/... |
或者干脆进到某个模块目录里跑,那个目录下有 go.mod,./... 立刻有了意义。这两种写法我都用,改单个模块的时候用后者,跑全量检查的时候用前者。
顺带说一句,go test ./... 在根目录的失败方式更难看一点。
1 | # ./... |
那个 FAIL 很容易被当成测试没过,其实是压根没跑起来。
差一个字母,含义差很远。
internal 的边界不因为 workspace 而改变
internal 这个目录名的规则很硬,路径里只要出现过一段 internal,这个包就只能被它父目录树里的包导入。example.com/a/internal/secret 的父目录树是 example.com/a,所以只有 a 下面的包能引它。
workspace 一点都不改这条规则。我在 b 里直接引它,报的是这句。
1 | package example.com/b |
而 a 自己的子目录 example.com/a/sub 引它是可以的,因为它在父目录树里面。这两件事放在一起看,internal 的边界按的是模块路径的目录树,不是文件系统的目录树,也不是 workspace 里谁跟谁挨着。b 和 a 在 go.work 里并列,在文件系统里也可以是兄弟目录,但在模块路径上 b 在 a 外面,所以 b 进不去。这条规则是我见过的 Go 工具链里最好的一条,它只用了一个名字就表达了一件复杂的事,而且不需要任何配置,不需要任何注解,看路径就知道能不能引。
这个设计有个好处我很喜欢,它让内部这个概念可以在编译期被强制,而不依赖文档里写一句请勿使用。代价是你不能把 a 的内部实现拆成一个单独模块还想让它对 a 可见,模块边界和 internal 边界一旦冲突,internal 边界赢。
我在一个项目里真的撞过这个。当时为了复用,把 a 的内部实现挪到了 example.com/a-core 这个新模块,然后在 a 里引它,一切正常,因为 a 取的是新模块的公开导出。等到把 a 的一些工具函数也搬过去,搬完之后 a 里那些原本能直接调内部函数的地方全红了,因为这次反过来了,a 变成了外部消费者。那次改动的净收益是负的,我最后把工具函数又搬回来,只留下那批确实不需要访问内部状态的代码在外面,教训是模块拆分应该先画 internal 的边界,再决定切在哪,而不是先切完再看哪里编译不过。
搬回去是唯一的路。
vendor 在 workspace 里是另一套命令
进到任意一个模块里敲 go mod vendor,会被直接拦住。
1 | go: 'go mod vendor' cannot be run in workspace mode. Run 'go work vendor' to vendor the workspace or set 'GOWORK=off' to exit workspace mode. |
这条报错给的两个方案都不是绕路,是真的两条路。GOWORK=off 是临时退出 workspace 回到单模块模式,这时候 go mod vendor 就正常了,vendor 目录落在那个模块里。go work vendor 是给整个 workspace 生成一份共享的 vendor,放在 workspace 根目录。
共享这两个字有实际后果,go work vendor 生成的 vendor/modules.txt 第一行是 ## workspace,后面每一行都是 workspace 里某个模块要的东西。有意思的是版本冲突那部分,我让 a 要 github.com/pkg/errors v0.8.1、b 要 v0.9.1,modules.txt 里两条 explicit 都写上了,但 vendor 目录里只放了一份代码,就是高的那个 v0.9.1。
1 | ## workspace |
这个行为和 workspace 内的版本统一是一回事。在 workspace 里跑 go list -m github.com/pkg/errors,拿到的是 v0.9.1,退出 workspace 回到 a 自己看,拿到的是 v0.8.1。所以 workspace 有一个很多人没意识到的副作用,它会把所有参与模块的依赖抬到同一个高度,你在 workspace 里开发的那个组合,跟最终发布出去的单模块组合,依赖版本可能不一样。这个差异在开发期看不出来,因为两边都能编过,两边的测试也都能过,只有在线上出问题的时候才会有人想起来去比对一下版本号,而那个时候已经没有 go.work 可查了。
依赖版本不一样这件事,平时不出事,出事就是线上。
整个 vendor 目录 48 KB、三个 .go 文件,因为这个依赖本身很小,换成 Kubernetes 那种体量,go work vendor 出来的东西会非常可观。这也是我一直倾向于不把 vendor 目录进仓库的原因,除非项目有明确的离线构建要求,否则它只是把依赖的解析结果冻结在一个没人会看的目录里,而这个冻结是有代价的,每次升级依赖都得重新跑一遍命令,忘了跑就会出现 vendor 和 go.mod 对不上的情况,报错信息还特别长。
一句话收尾
| 你要做的事 | 命令 | 边界在哪 |
|---|---|---|
| 让几个本地模块互相看见 | go work init 加 use |
只在 go.work 所在目录树生效 |
| 临时退回单模块 | GOWORK=off |
影响当前这条命令,不改文件 |
| 查当前生效的是哪个 | go env GOWORK |
会打出绝对路径,off 表示没启用 |
| 在根目录构建全部模块 | go build ./a/... ./b/... |
./... 在根目录不认 |
| 整个 workspace 打 vendor | go work vendor |
产物在根目录,单模块的 go mod vendor 会报错 |
go.work 这个文件名里那个 work 是 work in progress 的意思,不是 workspace。我第一次看到这个说法时觉得挺准的,它确实是一个都在改的状态下才有用的东西,一旦几个模块的版本定下来、各自推了 tag,那就该把它收起来,因为留着它等于让构建结果依赖于某台机器上的目录结构,而构建结果是不该依赖这种东西的。
我现在的做法是把 go.work 提交进仓库,但在 CI 里固定带上 GOWORK=off。开发的时候它是省事的东西,构建的时候它是不该出现的东西,这两种状态必须分开。这件事我吃过一次亏,那时候我把 go.work 直接提交了,CI 从远端拉代码,use ./a 这个目录因为在同一份代码里所以没事,但 use ./web 指向的前端目录恰好在 .gitignore 里没被提交,构建就一直报目录不存在,而本地怎么跑都是好的。









