module path决定服务边界与自治性：必须按服务粒度独立设置（如github.com/org/auth-service），禁止共用根模块或含/internal等非法路径段，否则破坏依赖隔离与CI/CD稳定性。
go.mod 中的 module path 怎么影响服务边界
模块路径不是随便起的，它直接决定服务能否被独立引用和升级。比如 github.com/org/project/auth 和 github.com/org/project/payment 必须是两个独立的 go.mod 文件，不能共用一个根模块——否则 go mod tidy 会把所有依赖拉进同一个版本锁文件，失去服务自治性。
常见错误是把所有微服务放在一个大仓库里，却只在根目录放一个 go.mod。结果改 auth 的依赖，payment 的构建也会受影响，CI/CD 拉取的 go.sum 变了，但没人意识到。
- 每个服务必须有自己独立的
go.mod，路径对应服务名，如github.com/org/auth-service - module path 不能带
/internal或/cmd这类路径段，Go Modules 不支持子模块嵌套式声明 - 如果使用 monorepo，用
replace或require显式指向本地路径（如./auth），但上线前必须替换为真实远程路径，否则部署失败
语义化版本怎么和 API 路径版本对齐
Go Modules 的 v1.2.0 和 HTTP 接口的 /v1/users 是两套版本体系，但必须保持语义一致：主版本升级（v2.0.0）意味着接口不兼容变更，此时 /v1 路由应继续存在，/v2 新增，且两个版本的服务实例可能同时运行。
如果只改了 go.mod 里的版本号却不更新 API 路径，客户端调用不会出错，但实际行为可能已变——比如 User 结构体字段被删了，而 proto 或 JSON 序列化没做兼容处理。
立即学习“go语言免费学习笔记（深入）”；
-
go.mod中的版本号要和 Git Tag 严格对应，CI 流程需校验git describe --tags输出是否匹配go list -m - HTTP 路由版本（如
/v1）不能靠 Go Modules 自动推导，必须手动在 Gin/Echo 的 Group 路由中显式定义 - gRPC 场景下，proto 文件目录结构（如
api/v1/user.proto）要和go.mod版本号同步，buf 工具能检查 breaking change，但得配好buf.yaml
跨服务调用时的依赖版本冲突怎么破
订单服务依赖用户服务的 v1.3.0，通知服务却用了 v1.5.0，当它们都引入同一个公共工具库（比如 github.com/org/common），MVS（最小版本选择）可能选一个中间版本，导致某一方的接口行为异常——这不是 bug，是 Modules 的确定性策略本身带来的副作用。
根本问题在于：你没法要求所有服务“统一升级”公共库。尤其当 common 里混着 DTO、error 定义、工具函数时，耦合太紧。
- 禁止在
pkg/或common/下放任何业务相关类型；DTO 必须由调用方按需定义，或通过 proto 生成 - 工具函数尽量下沉到
internal/，不对外暴露，避免被跨服务 import - 真要共享逻辑，用
replace锁死版本，或拆成更小粒度的模块（如github.com/org/uuidgen），让每个服务只拿自己需要的部分
服务发现与 go.mod 版本之间没有自动关联
Consul 注册时打上 version:v1.2.0 标签，API 网关根据请求路径转发到对应实例——这个过程完全不读 go.mod。也就是说，即使你把 go.mod 升级到 v2.0.0，但忘了更新服务注册的元数据，流量还是全打到旧版实例上。
更隐蔽的问题是：不同服务的 go.mod 里写的依赖版本不一致，但它们都连同一个 Redis 或 MySQL 实例，而驱动版本差异可能导致连接池行为不一致，出现超时抖动。
- 服务注册的 version 标签必须从
go.mod解析，不能手写；建议在cmd/auth/main.go启动时读取runtime/debug.ReadBuildInfo()提取 module version - 基础设施客户端（如
redis.Client）版本必须在所有服务间对齐，哪怕只是 minor 版本，否则底层协议细节可能有差异 - CI 构建产物里应包含
go list -m all输出，作为部署清单的一部分，而不是只看 Git Tag
go.mod 的 require 行里，也在 proto 的 message 字段里，还在 Consul 的 service tag 里。漏掉任意一环，版本控制就变成幻觉。 
