Golang微服务接口版本管理技巧

URL路径前缀是首选，应将版本号放在URL路径中（如/api/v1/users），因其便于调试、网关路由、CDN日志记录和OpenAPI文档生成；Header或Query参数易导致缓存失效、代理丢弃或复现困难。

URL路径前缀是首选，别迷信Header或Query参数

绝大多数Go微服务应该把版本号放在URL路径里，比如/api/v1/users和/api/v2/users。这不是因为“标准”，而是调试时一眼看清版本、网关路由规则好写、CDN和日志能天然记录、OpenAPI文档能自动分版本生成——而X-API-Version头容易被反向代理丢弃，?version=v2则会让缓存失效、浏览器直接访问无法复现问题。

• 用Gin时，务必用r.Group("/v1")和r.Group("/v2")，别混用r.GET("/v1/users")和r.Group("/v1")，否则路径重复导致404
• 避免用数字开头的路径如/api/2/users，会被误判为资源ID；坚持用v1、v2这种带字母的格式
• 如果真要支持Header fallback（比如内部灰度），中间件里只做识别和注入c.Set("version", ver)，绝不替代路径作为主路由依据

每个版本必须定义独立DTO，禁止共用struct加json:",omitempty"

Go里没有字段级版本控制，靠一个User struct加tag模拟兼容性，只会让v2新增字段在v1请求中静默丢失，或者v1客户端收到v2才有的字段引发解析错误。正确做法是为每个版本声明专属DTO，比如UserV1和UserV2，字段名、类型、JSON tag全可不同。

• UserV1里用Name string，UserV2里改用FullName string，不靠重命名tag硬撑
• 新增字段在UserV2里直接加，旧版UserV1保持不动；删除字段？先保留UserV1里的字段，几轮发布后再删
• 转换逻辑写成显式函数，比如func ToV2(u *model.User) *UserV2，而不是用mapstructure自动映射——后者字段名一变就崩，且没法测边界case

Service层尽量无版本感知，但DTO隔离必须严格

业务逻辑（查DB、校验权限、发消息）不该随接口版本翻倍。真正该拆的是HTTP层：handler负责解析请求、调service、包装响应。这样v2加个软删除状态，只需在handler/v2/user.go里补字段映射，service/user.go完全不用动。

• v1 handler调userSvc.GetByID(ctx, id)，v2 handler也调同一个方法，返回的*model.User再转成各自DTO
• 禁止v2 handler里直接调v1的createUserV1()函数——这等于把版本边界焊死在业务层，后续想下线v1就得全局grep
• 如果v2需要新校验规则（比如邮箱必须验证），加在v2 handler里，或抽成validator.V2()，别污染通用service

gRPC和模块依赖的版本管理不能只靠路径

HTTP API用路径就够了，但gRPC和SDK依赖得更狠——Protobuf字段删改会直接破坏二进制兼容，go get不带/v2后缀会导致所有服务被迫升级。

• Protobuf升级只允许追加字段、不能改类型、枚举值编号不能重用；旧字段加deprecated = true，生成代码会有警告
• 发布client SDK时，go.mod必须改成module github.com/your-org/user-client/v2，调用方import路径也得写全github.com/your-org/user-client/v2
• 服务注册到Consul/Nacos时，用tags: ["v2"]或metadata: {"version": "v2.1"}，让网关或客户端SDK按tag选实例，而不是靠URL硬编码

版本管理最常被忽略的不是技术怎么写，而是生命周期管控：每个v1接口要有明确的废弃倒计时，文档里标清“v1将于2026-Q3下线”，监控里盯住v1调用量是否归零。否则v1代码永远不敢删，越积越多，就成了技术债黑洞。