Go modules 怎样拆分多模块工作区

我在一个仓库里同时维护“业务服务”和“共享模块”时，最容易遇到的不是代码写不出来，而是依赖到底应该指向本地目录还是模块版本。Go 的多模块工作区适合解决这个联调问题：每个模块继续保留自己的 go.mod，再用根目录的 go.work 把它们放进同一个开发上下文。

官方资料：https://go.dev/doc/tutorial/workspaces

开发期用 go.work 管理多个本地模块，发布期仍以各模块自己的 go.mod、版本标签和模块代理为准。不要把工作区文件当成新的发布依赖清单。

先区分 go.work、replace 和版本依赖

这三个方案都能让代码“找到另一个模块”，但解决的问题不同。go.work 面向一个开发者同时编辑多个模块的场景；replace 是写进某个模块依赖图的定向替换；正式发布则应该让 go.mod 的 require 指向可复现的模块版本。

我的判断是：如果你要同时修改两个模块，先考虑 go.work；如果只是临时验证一个本地分支，才使用范围明确的 replace；准备交付时，回到版本化依赖。

分别初始化两个独立模块

假设目录名为 workspace，里面有业务模块 hello，以及本地依赖模块 example/hello。它们必须各自拥有 go.mod，否则就不是两个可独立发布的模块。

# 先创建业务模块；模块路径要与未来发布或引用的身份一致
mkdir -p workspace/hello workspace/example/hello
cd workspace/hello
go mod init example.com/hello

# 再初始化被依赖模块；这里不把两个模块合并成一个 go.mod
cd ../example/hello
go mod init golang.org/x/example/hello

业务模块的代码可以正常导入依赖模块中的包，例如 golang.org/x/example/hello/reverse。如果此时只在单个模块目录内工作，Go 会按该模块自己的依赖图解析；跨目录联调还需要下一步的工作区声明。

用 go work init 和 go work use 组成工作区

回到 workspace 根目录，先把业务模块加入工作区，再把本地依赖模块加入。官方教程中，go work init ./hello 会创建 go.work，go work use 会追加新的模块路径。

# 在两个 go.mod 的共同父目录创建工作区文件
cd workspace
go work init ./hello

# 把另一个本地模块纳入同一个工作区
go work use ./example/hello

# 需要递归发现多个模块时，可以从指定目录向下扫描
go work use -r .

工作区文件的关键部分类似下面这样。JSON 不允许注释，所以这里用有效的 go.work 片段，并在代码块外解释每个字段。

go 1.18

use (
    ./hello
    ./example/hello
)

go 指令声明文件解释所需的 Go 版本，use 列出作为 main module 参与构建的模块。这样从工作区根目录运行 go run ./hello 时，业务模块引用的本地依赖可以由工作区解析，而不必先把依赖模块发布到代理。

本地联调完成后，怎样回到发布边界

工作区最方便的地方，也是最容易让人误判的地方：本地源码优先并不等于这个源码已经是可发布依赖。模块准备交付时，应先在依赖模块中提交变更并打版本，再回到业务模块更新 require，让脱离工作区的环境也能解析。

# 工作区内先整理各模块的依赖关系
go work sync

# 发布依赖模块后，在业务模块中改用明确版本
cd hello
go get golang.org/x/example/hello@v0.1.0
go mod tidy

go work sync 的职责是把工作区构建列表同步到各模块；它不是发布命令。CI 或生产构建应明确决定是否启用工作区，避免某个开发者目录里的 go.work 意外改变依赖来源。

几个容易混淆的问题

go.work 能替代多个模块的 go.mod 吗？

不能。go.work 只描述工作区里的模块集合，每个模块仍需要自己的 go.mod 来声明模块路径和依赖。

什么时候不该提交 go.work？

如果团队希望每个模块严格按已发布版本构建，或者 CI 已经显式生成工作区，个人本地的 go.work 不应悄悄改变项目的默认依赖来源。提交前要把开发便利和交付可复现性分开考虑。

多模块是不是一定比单模块更好？

不是。共享模块需要独立版本、兼容策略和发布流程时，多模块更合适；代码总是一起发布、边界也不稳定时，先保持单模块通常更简单。

最后可以用一句话记住这套选择：go.work 解决“我现在要同时改几个模块”，replace 解决“我暂时换一个来源试试”，go.mod 版本依赖解决“别人和 CI 怎样稳定地构建”。