Go work 怎样管理多个模块联调

当一个仓库同时维护订单服务和账户库时，反复修改 go.mod 里的 replace 很快就会把“本地联调”和“正式依赖”混在一起。更合适的做法是：保留每个项目自己的 go.mod，在共同父目录创建 go.work，再用 use 把需要一起改动的模块纳入 workspace。

官方文档：https://go.dev/ref/mod#workspaces

这样，Go 命令会把列出的模块视为当前 workspace 的 main modules。联调完成后，再用单模块模式和各自的 go.mod 做一次回归，避免把本地路径关系误带进发布流程。

升级范围：先把联调目录和模块边界分开

这次调整解决的是“多个本地 module 同时开发”的问题，不是把多个目录合并成一个 module。假设目录如下：

workspace/
├── account/
│   └── go.mod
├── order/
│   └── go.mod
└── go.work

account 和 order 仍然各自拥有模块路径、依赖和发布边界；go.work 只是位于上层的本地协作声明。这个区分很重要：它可以让服务代码直接引用本地库的改动，却不会要求你把两个项目的源码、版本号和发布节奏合并。

变更表：用 go work init/use 纳入模块

进入 workspace 根目录，先初始化工作区，再加入两个模块：

# 在共同父目录创建 workspace 声明
go work init ./account

# 把第二个本地 module 加入同一个联调边界
go work use ./order

# 查看当前 go 命令实际使用的 go.work
go env GOWORK

生成的文件可以整理成下面这样：

go 1.23

use (
    ./account
    ./order
)

go 行应与团队准备使用的 Go 版本策略一致；示例中的版本只是文件形态示意，不代表必须固定在这一版本。官方定义中，use 指向的目录必须包含 module，Go 命令才会把它们作为 workspace 的主模块。

旧代码风险：不要把临时 replace 当成工作区配置

如果以前在 order/go.mod 里写过：

// 仅用于说明旧的本地替换写法
replace example.com/account => ../account

迁移到 workspace 后，要先判断它是不是只服务于本地联调。工作区模式能够为多个模块提供统一的主模块集合，临时路径替换继续留在模块文件里，容易让同一个依赖同时存在两套来源。更稳妥的做法是把“本地一起改”的关系交给 go.work，把真正需要所有开发者和 CI 都遵守的替换关系留在 go.mod。

联调时，order 中的导入可以保持正常的模块路径：

package main

import (
    "fmt"

    "example.com/account/profile"
)

func main() {
    // 通过模块路径调用本地 account 代码，便于跨模块同步修改
    fmt.Println(profile.DisplayName("u-1001"))
}

这里的关键不是改导入路径，而是让 Go 命令在 workspace 解析到本地的 account。如果导入仍然拿到缓存版本，先检查命令执行目录和 go env GOWORK，不要立即复制更多 replace。

新写法：为联调和单模块构建保留两条路径

本地联调时可以从 workspace 根目录执行：

# 检查 workspace 看到的模块集合
go list -m

# 同时编译工作区中的模块
go build ./...

# 运行订单模块的测试，覆盖它对本地账户模块的调用
go test ./order/...

发布或 CI 检查时，建议明确关闭 workspace 影响，再回到目标模块自己的依赖图：

# 只按 order/go.mod 解析，避免依赖本机 go.work
GOWORK=off go test ./order/...

# 确认当前命令已经退出 workspace 模式
GOWORK=off go env GOWORK

GOWORK=off 不是删除文件，而是对当前命令临时关闭 workspace。它适合用来发现“本地联调能过、单模块交付却缺依赖”的问题。

回归检查：用一张清单确认迁移没有扩大影响

可以按下面顺序做回归，不需要把 workspace 当成新的发布单元：

1. 在根目录运行 go env GOWORK，确认它指向预期的 go.work。
2. 检查 go.work 的 use 列表只包含本次需要联调的模块，避免把无关项目带入解析范围。
3. 执行 workspace 下的构建和测试，确认跨模块修改能够被当前代码直接看到。
4. 进入每个要交付的模块，使用 GOWORK=off 再跑一次该模块自己的测试。
5. 团队协作时约定 go.work 是否提交；如果只用于个人目录，应在 README 或脚本中说明生成方式，避免让其他人误以为它是模块发布元数据。

如果工作区命令行为异常，优先排查三个点：当前目录是否位于 go.work 的父子路径范围内、use 指向的目录是否真的有 go.mod、以及是否被 GOWORK=off 或其他环境设置覆盖。

迁移清单与常见问题

• go.work 能替代所有 replace 吗？不能简单这样理解。它适合声明本地 workspace 的模块集合；跨环境都必须成立的依赖替换仍要按项目约定放在模块配置中。
• 为什么改了 account 代码，order 仍像在用旧版本？先确认当前命令是否处于 workspace 模式，再确认 account 是否被列在 use 中；不要只看导入路径。
• go.work 要不要提交？取决于它是团队共享的联调边界，还是个人本地组合。无论哪种选择，都应让构建和测试命令明确知道是否启用 workspace。

总结一下：把独立模块留在各自的 go.mod，把本地联调关系集中放进根目录的 go.work，再用 GOWORK=off 做交付回归。这样既能获得多模块协作的即时反馈，也能保留每个模块单独构建、测试和发布的边界。