go mod 在微服务中至关重要，决定依赖升级安全、避免 import cycle 及 DTO 复用不污染；Go 的 MVS 算法强制单版本共存，多版本 require 会升版导致兼容问题；共享契约需纯数据定义、禁止业务依赖；replace 仅限开发调试，上线前须清理并统一打 tag；vendor 适用于私有环境，go.sum 不可随意删除。
微服务项目里，go mod 不是“能用就行”的工具——它直接决定你能否安全升级依赖、是否频繁遇到 import cycle not allowed、能不能让不同服务复用同一套 DTO 而不互相污染。
为什么 go.mod 里 require 同一个模块的多个版本会失败
Go 的 MVS（最小版本选择）算法强制整个模块图只保留一个满足所有依赖要求的版本。比如 service-a require github.com/your/api v1.2.0，service-b require github.com/your/api v1.5.0，当它们被同一个主模块（如 gateway）同时引入时，go mod tidy 会升到 v1.5.0，但 service-a 可能因 v1.5.0 的接口变更而编译失败。
- 这不是 bug，是设计：Go 不支持“多版本共存”，不像 Java 的 classloader 隔离
- 真实痛点常出现在共享
internal/contract模块时——某个服务偷偷升级了 DTO 字段类型，其他服务没同步就炸了 - 临时解法是用
replace锁死版本，但必须同步更新所有引用方的go.mod，否则 CI 构建环境会拉取最新版并失败
如何让多个微服务安全复用一套 API 契约
关键不是“怎么共享代码”，而是“怎么避免共享带来的 import cycle”。把契约抽成独立模块只是第一步，结构不对照样崩。
-
internal/contract必须是纯数据定义：只有struct、interface、error类型，禁止 import 任何业务逻辑包（包括internal/service或pkg/util） - 每个微服务只
import github.com/your-org/contract/v1，绝不import github.com/your-org/order/internal/contract—— 后者等于把服务 A 的内部路径暴露给服务 B - 如果 DTO 需要 JSON 序列化行为，用
json.Marshaler接口在各自服务内实现，不要在 contract 包里写方法
replace 指令在开发期有用，上线前必须清理
replace 是调试利器，但它是构建时的“硬编码补丁”，会绕过版本校验和 GOPROXY 缓存，CI/CD 流水线里极易出问题。
立即学习“go语言免费学习笔记（深入）”；
- 本地开发时可用：
replace github.com/your/api => ../api，快速验证改动 - 但合并前必须删掉
replace行，并运行go mod tidy && go build ./...确认无误——否则别人 checkout 代码后go build直接失败 - 更稳妥的做法是：用
git tag v1.3.0打正式版，然后所有服务统一go get github.com/your/api@v1.3.0
vendor 目录在微服务交付中仍有存在价值
公有云构建环境（如 GitHub Actions）默认走 GOPROXY，但私有环境或 air-gapped 部署时，vendor 是唯一可靠方案。
- 执行
go mod vendor后，所有依赖源码进vendor/，go build -mod=vendor强制只读该目录 - 注意：
vendor不解决版本冲突——它只是把当前go.mod解析出的最终版本快照打包，冲突必须先在go.mod里修好 - CI 流水线里建议加检查：
git status --porcelain vendor/ | grep -q '^M' && echo "vendor out of sync" && exit 1
最常被忽略的其实是 go.sum 文件的语义：它不是“锁文件”，而是每个依赖模块的 checksum 记录。删掉它再 go mod tidy，可能拉到已被撤回的恶意版本——尤其当你依赖的第三方模块没做签名发布时。
