go mod vendor 不能解决多级依赖混乱，因为它只冻结版本而非约束调用关系；硬编码 import 路径、跨模块直调内部包、缺失接口抽象与依赖倒置，导致重构时连锁报错；需通过 contract 接口契约、目录边界、linter 规则和构建标签实现安全替换与分层治理。
大型微服务中直接硬编码 import 路径、跨模块调用未抽象接口、依赖倒置缺失，会导致重构时牵一发而动全身——这不是设计问题，是依赖治理没到位。
为什么 go mod vendor 不能解决多级依赖混乱
go mod vendor 只冻结依赖版本，不约束模块间调用关系。实际项目里常见：user-service 直接 import "github.com/ourorg/order/internal/payment"，把内部实现细节暴露给下游，一旦 payment 模块重构路径或拆分，所有引用它的服务全量报错。
- vendor 不阻止 import 跨层穿透（比如从 api 层 import internal 包）
- go list -f '{{.Deps}}' 无法识别“逻辑层级”，只输出字面依赖树
- gomodgraph 等工具画出的图里，service → domain → infra 的箭头全是双向的，说明存在循环引用或越权调用
用 interface + pkg boundary 强制分层契约
Go 没有 module visibility 关键字，但可以用目录结构 + 接口声明 + linter 规则模拟“包级访问控制”。关键不是删代码，是定义谁可以依赖谁。
- 每个业务模块根目录下必须有
contract/子目录，只放interface{}和 DTO（如UserRepo,OrderEvent） - 禁止任何
internal/或pkg/下的非 contract 包被外部模块 import —— 用golangci-lint配置exportloopref+ 自定义go-critic规则拦截 - infra 模块实现 contract 接口时，用
newXXXRepo()工厂函数返回，而非暴露 struct；调用方只依赖contract.UserRepo，不感知 MySQL 或 Redis 实现
示例：user-service 调用订单服务，不 import 其内部逻辑：
立即学习“go语言免费学习笔记（深入）”；
// user-service/usecase/create_user.go
func (u *UserUsecase) CreateUser(ctx context.Context, req CreateUserReq) error {
// 依赖的是 contract.OrderService，不是 order-service 的具体实现
_, err := u.orderSvc.CreateOrder(ctx, req.OrderData)
return err
}
如何安全替换一个已上线的 infra 实现（比如从 MySQL 切到 TiDB）
不是改 import 路径，而是通过构建标签 + 接口实现切换。编译期决定用哪个驱动，运行时零改动。
- 在 infra/order/mysql/ 下实现
contract.OrderRepo，同时在 infra/order/tidb/ 下另写一份 - 主模块的
main.go用//go:build tidb标签控制引入哪套实现 - CI 流水线打镜像时传参：
CGO_ENABLED=1 GOOS=linux go build -tags tidb -o order-svc ./cmd/order - 关键点：两套实现必须共用同一组 migration SQL（用 golang-migrate），且
contract接口方法签名不能因数据库差异而变
gomod replace 不是长期方案，要配合最小化发布单元
用 replace 临时指向本地修改的模块，容易在 PR 合并后忘记删，导致线上环境拉错 commit。真正解法是把模块切得足够小、发布节奏足够快。
- 每个
go.mod对应一个可独立部署的二进制（如auth-api、auth-worker），而不是整个 auth-domain - contract 模块单独发版（语义化版本号），其他模块通过
require github.com/ourorg/auth-contract v1.2.0显式声明兼容范围 - 当 contract 接口加字段，旧版服务仍能启动（DTO 字段加
json:",omitempty"），但新版 client 必须处理新增字段，避免静默丢数据
最常被忽略的点：contract 接口变更必须同步更新 OpenAPI spec 和 protobuf 定义——否则前端和 gRPC 客户端会卡在“看似能跑，实则字段丢失”的状态。
