go modules 不参与 http 接口版本控制，仅管理模块自身语义版本（如 v2.1.0），影响 import 路径与依赖解析；http api 版本（如 /v2）需独立设计与维护，二者必须分离对齐，否则引发兼容问题。

Go Modules 不直接参与 HTTP 接口版本控制，但它决定了微服务“自身代码版本”如何被其他服务消费——接口版本和模块版本是两层事，混用会出严重兼容问题。

go.mod 中的 version 字段 ≠ API 路径里的 /v1

你在 go.mod 里写的 module github.com/yourorg/users-service/v2，只是告诉 Go 编译器：“这个包是 v2 版本的模块”，它影响的是 import 路径和依赖解析。比如：

import "github.com/yourorg/users-service/v2/client"

这跟 HTTP 请求走 /v1/users 还是 /v2/users 完全无关。常见错误包括：

• 把 go.mod 升级到 v2 就以为对外 API 自动变成 v2 —— 实际路由、DTO、文档全没变，客户端调 /v2/xxx 直接 404
• 在同一个模块里同时提供 /v1 和 /v2 路由，却把模块名还叫 v1，导致下游服务升级后 import 冲突或误用旧 client
• 用 replace 在本地强制指向开发分支，但 CI 环境没同步，测试通过、上线炸了

真正需要对齐的两个版本维度

微服务演进中必须区分并分别管理：

• go.mod 的模块语义版本（如 v1.3.0）：控制依赖兼容性，遵守 SemVer，主版本升级需改 import 路径
• HTTP API 路径版本（如 /api/v2）：控制客户端契约，独立生命周期，可长期共存

举例：你的服务发布了 v2.0.0 模块，但只新增了 /api/v2/orders，/api/v1/users 仍完全保留——这时模块版本升了，API 版本没全升，也不能强制客户端切到 v2。

Golang Google Wire

在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface

下载

client 包必须按 API 版本分包，且与 go.mod 版本联动

如果你提供 SDK 给其他服务调用，client 包结构要反映真实 API 支持能力：

• github.com/yourorg/users-service/v1/client：只封装 /v1/xxx 请求，生成的 struct 严格对应 v1 DTO
• github.com/yourorg/users-service/v2/client：只封装 /v2/xxx，字段、错误码、重试策略都可不同

这样下游服务才能明确选择依赖哪个 client：

require github.com/yourorg/users-service/v1 v1.5.2<br>require github.com/yourorg/users-service/v2 v2.1.0

别写一个“通用 client”去 if-else 切版本——那会让调用方失去编译期类型安全，也绕过了 Go Modules 的版本隔离机制。

容易被忽略的陷阱：proto 文件 + go.mod 版本错位

如果用 gRPC，.proto 文件通常放在 api/v1/ 或 api/v2/ 目录下，生成的 Go 代码会带包路径。此时：

• proto 文件变更必须同步 bump go.mod 主版本（如从 v1 → v2），否则生成的代码 import 冲突
• buf lint 或 breaking change 检查必须绑定到 go mod 版本号，不能只看文件目录
• Kubernetes 中部署多个版本实例时，每个实例的镜像 tag 应包含 go.mod 版本（如 users-service:v2.1.0），而不是模糊的 latest 或 v2

接口版本是运行时契约，模块版本是构建时契约——两者都稳，服务才真的可演进。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！