go mod 的核心作用是隔离、复用和精确控制依赖边界，而非扁平化目录；每个逻辑明确的子模块（如 /pkg/auth）都应独立初始化 go.mod，使用唯一稳定模块路径，并通过 require 显式引入；replace 用于协同开发阶段本地联调，发布前须替换为正式版本；exclude 仅在上游严重 bug 且无法快速修复时谨慎使用；跨模块结构体共享需通过接口契约或显式字段声明约束，避免静默失败；模块边界错误将导致后续重构成本指数级上升。
多层嵌套项目里，go mod 不是用来“扁平化”目录结构的，而是用来隔离、复用和精确控制依赖边界的——关键不是让目录变浅，而是让依赖关系变清晰、可验证、不污染。
go.mod 必须放在每个独立可复用模块的根目录
常见错误是只在项目最外层放一个 go.mod，然后把所有子目录当成内部包硬塞进去。这会导致：internal 包被意外导出、版本无法单独升级、跨团队复用困难。
- 如果你有
/pkg/auth、/pkg/rpc、/cmd/gateway这类逻辑边界明确的模块，每个都该有自己的go.mod -
go mod init github.com/yourorg/auth—— 模块路径必须唯一且稳定，不能用本地路径或相对路径 - 主项目通过
require github.com/yourorg/auth v0.3.1显式引入，而不是import "./pkg/auth" - 子模块的
go.sum独立生成，不会和主项目混在一起，校验更可靠
replace 和 exclude 不是临时补丁，而是模块演进的必要工具
当多个嵌套模块还在协同开发、尚未发版时，replace 是唯一安全的本地联调方式；滥用 replace 会掩盖版本兼容问题，但不用它又没法真实验证跨模块调用。
- 开发阶段：在主项目的
go.mod中写replace github.com/yourorg/auth => ../auth，确保本地修改实时生效 - 发布前必须删掉
replace，改用正式 tag（如v0.3.1），否则 CI 构建会失败 -
exclude github.com/evil/dependency v1.2.0只应在上游依赖存在严重 bug 且无法快速修复时使用，且需同步提交 issue 并跟踪 upstream 修复进度 -
exclude不影响go list -m all输出，但会跳过该版本的 MVS 计算，务必谨慎
嵌套结构体 + 多模块 = 接口契约必须提前定义
当 User 结构体定义在 github.com/yourorg/model，而业务逻辑在 github.com/yourorg/service 时，字段访问、JSON 序列化、数据库映射等行为必须收敛到接口或类型别名，否则极易因字段小写/标签变更引发静默失败。
立即学习“go语言免费学习笔记（深入）”；
- 避免直接
import "github.com/yourorg/model"后裸用model.User；改为定义type User interface { GetID() string }在 service 层 - 如果必须共享结构体，确保
model.User的字段全部首字母大写，且jsontag 显式声明（如json:"user_id"） - 切片嵌套层级（如
User.Instances[i].Configs[j].Replicas[k]）应封装为方法，例如u.FindReplicaByID(id string)，把索引逻辑收进 model 模块 - 不同模块间传递结构体时，优先用值拷贝而非指针，防止跨模块内存生命周期失控
真正容易被忽略的不是怎么写 go mod init，而是模块边界一旦划错，后续所有重构成本会指数级上升——比如把配置解析逻辑和 HTTP handler 塞进同一个模块，之后想抽离成独立 SDK 就得重写整个依赖图。
