Go 1.11 的 go mod 是多模块项目事实标准，需按可独立版本化、可复用、有明确 API 边界拆分模块；replace 仅用于开发期本地覆盖，须发布前移除；应通过接口抽象、中间 contracts 模块等避免隐式循环依赖；CI 中需单独构建各模块并校验 go list -m all。
Go 1.11 引入的 go mod 已成为多模块项目的事实标准，但“多模块”不等于“多个 go.mod 文件随便放”——关键在于明确边界、控制依赖流向、避免循环引用。
什么时候该拆出独立模块（go.mod）？
不是按功能目录切分，而是按「可独立版本化、可被外部复用、有明确 API 边界」来判断。比如：
- 一个通用的加密工具包（
github.com/yourorg/crypto-utils），被多个内部服务引用 → 应有自己go.mod - 某个微服务的
internal/子包，只在本项目内使用 → 不需要单独go.mod，应保留在主模块中 - CLI 工具和其核心库逻辑高度耦合、无对外暴露意图 → 保持单模块更清晰
replace 和 require 在多模块中的实际作用
主模块通过 require 声明对其他模块的依赖版本；而 replace 是开发期绕过远程拉取、直连本地路径的临时手段，仅在 go.mod 中
常见误用：在发布前忘记删掉 replace，导致 CI 构建失败或依赖不一致。
module github.com/yourorg/app
go 1.21
require (
github.com/yourorg/auth v0.3.1
github.com/yourorg/storage v0.5.0
)
replace github.com/yourorg/auth => ./auth
replace github.com/yourorg/storage => ../storage-lib
注意：replace 路径必须是相对路径，且目标目录下必须存在有效的 go.mod；若目标模块未发布到远端，其他协作者 go build 会失败，除非他们也配置了相同 replace。
如何防止模块间隐式循环依赖？
Go 编译器不会报错，但运行时或测试阶段可能因初始化顺序异常崩溃。典型信号：
-
import cycle not allowed（少见，多见于init()中跨模块调用） - 单元测试通过，集成测试 panic：某结构体字段类型来自另一个模块，而该模块又
require当前模块 -
go list -f '{{.Deps}}' ./...显示 A → B → A 类路径
解决方法：
- 用接口抽象依赖：把 B 模块需要的 A 的能力，定义在 B 自己的
interface{}中，A 实现它并传入 B - 引入中间模块（如
github.com/yourorg/contracts），只放共享类型与接口，不包含实现 - 禁用跨模块直接引用内部结构体：所有导出类型应在模块顶层
.go文件中声明，避免藏在internal/下又被其他模块 import
CI/CD 中多模块构建的坑点
默认 go build ./... 会遍历所有子模块，但若某个模块的 go.mod 里 require 了尚未发布的版本（如 v0.4.0-rc1），CI 可能因 GOPROXY 无法命中而失败。
推荐做法：
- 每个模块单独构建：
cd auth && go build -o ../bin/auth，避免依赖污染 - 在根目录
go.work中显式列出参与开发的模块（适用于本地联调），但 CI 应禁用go.work，强制走go.mod声明 - 用
go list -m all校验所有模块版本是否可解析，作为 CI 前置检查步骤
真正麻烦的从来不是怎么写 go.mod，而是当三个模块都改了同一个底层错误码常量、却没人同步更新文档和 HTTP 错误映射表的时候。
