go work 是多模块开发的起点，不是可选配置；它通过 go.work 文件统一管理本地模块可见性，使 go build、go test 等命令能自动识别未发布模块，路径必须为相对路径且目标含有效 go.mod，replace 仅用于临时调试，不应提交或嵌套使用。
go work 是多模块开发的起点，不是可选配置
Go 1.18 引入 go.work 文件后，本地多模块协同开发才真正变得可控。它不替代各子模块的 go.mod，而是让 Go 命令知道“当前工作区包含哪些模块”，从而统一解析 import 路径、运行测试、执行 go build 或 go test 时自动识别本地修改。
常见错误现象：在根目录下直接 go run ./cmd/api 报错 cannot find module providing package example.com/project/service，本质是 Go 没有上下文去定位本地未发布模块。
- 必须在项目根目录执行
go work init初始化工作区 - 逐个添加模块：
go work use ./api ./service ./shared（路径必须存在有效的go.mod） -
go.work文件应提交到 Git，但其中的replace不应出现——go.work管理的是“本地模块可见性”，不是版本替换 - CI 环境通常禁用
go.work，改用cd ./cmd/api && go build进入子模块构建，避免依赖工作区状态
每个 go.mod 必须有真实、唯一的模块路径
模块路径不是别名，而是 Go 导入语句中实际使用的字符串。如果 ./service/go.mod 写成 module service，那么其他模块 import 它时就得写 import "service" ——这会导致跨项目复用失败、IDE 无法跳转、go list 解析异常。
正确做法是让模块路径反映未来可能的公开地址，例如：module github.com/yourorg/project/service。即使你还没 push 到 GitHub，这个路径也决定了：
立即学习“go语言免费学习笔记（深入）”；
- 其他模块 import 时的完整路径：
import "github.com/yourorg/project/service" -
go get安装时的解析目标（若将来发布） - VS Code 或 GoLand 的符号跳转是否生效
- 生成的
go.sum中校验和绑定的 key
replace 只应在 go.mod 中用于本地开发，且不能跨模块链式嵌套
replace 是临时绕过远程版本拉取的手段，不是模块解耦方案。它只在当前模块的 go.mod 中生效，上级或下游模块不会继承。
典型陷阱：你在 ./cmd/api/go.mod 里 replace github.com/yourorg/project/service => ./service，但 ./service/go.mod 又 replace github.com/yourorg/project/shared => ../shared ——此时 ./cmd/api 编译时根本看不到 shared 的本地路径，会尝试下载远端版本，导致构建失败或行为不一致。
- 所有
replace应集中在根go.mod（若存在），或各子模块自己声明，不可依赖“传递” - 路径必须是相对路径，且目标目录下必须已有
go.mod；../shared合法，../../shared在某些 CI 路径下可能越界 - 发布前必须删除全部
replace行，否则go mod tidy无法升级为真实语义化版本 - 若多个模块都依赖同一内部库，优先考虑提升为独立
pkg/模块并统一require，而非每个地方都replace
循环依赖检测要靠 go list 和显式接口，编译器不会帮你拦住所有情况
Go 编译器只检查 import cycle（如 A → B → A），但不会报错“B 的某个函数接收了 A 定义的 struct，而 A 又调用了 B 的函数”。这种隐式循环常在集成测试或运行时暴露，表现为 panic、nil pointer 或初始化顺序错乱。
最轻量的验证方式是用 go list 扫描依赖图：
go list -f '{{.Deps}}' ./service | grep 'api'
若输出中同时出现 service 和 api，说明存在双向引用风险。
- 接口必须定义在被依赖方（例如
shared/interface），实现放在依赖方（service实现该接口，api仅 import 接口） - 禁止跨模块使用
internal/目录下的类型；对外暴露必须通过public/或模块根包导出 - 数据结构定义尽量收拢到
shared/model，避免各模块各自定义相似 struct 导致字段不一致 - CI 流程中建议加一步：
go list -f '{{.ImportPath}}: {{.Deps}}' ./... | grep -E 'api.*service|service.*api'，提前拦截高危组合
go.work 与 go.mod 的职责分离——前者管“我在哪开发”，后者管“我依赖谁、用哪个版本”。混淆这两层，项目越大越难维护。 
