Go语言API版本控制核心是路由分组隔离版本，如Gin的Group("/v1")和Group("/v2")，配合兼容策略（保留旧字段、可选新字段、410提示废弃）、版本解析中间件及文档生命周期管理。
Go语言中实现API版本控制，核心是通过路由分组隔离不同版本的接口，并结合兼容策略平滑过渡。关键不在于写多少版本，而在于让旧版能继续运行、新版可独立演进、客户端无感升级。
用Gin或Echo做路由分组，按版本前缀隔离
主流Web框架（如Gin、Echo）都支持基于路径前缀的路由分组，这是最直观、最易维护的版本控制方式。
- Gin示例：用
Group("/v1")和Group("/v2")分别注册对应逻辑，彼此完全解耦 - 路径统一规范为
/api/v1/users、/api/v2/users，避免混用v1和version=1等多套机制 - 分组内可复用中间件（如鉴权、日志），但不要跨版本共享handler函数——逻辑耦合会破坏版本独立性
兼容处理：保留旧字段 + 可选新字段 + 渐进式废弃
版本升级时，服务端要兼顾老客户端，不能简单删字段或改类型。
- 响应结构体用
json:",omitempty"控制空值不输出，新增字段设为指针或带默认值的可选字段 - 接收请求时，用两个结构体分别绑定v1/v2入参，或用一个结构体+自定义UnmarshalJSON适配多版本格式
- 对已废弃接口，返回
410 Gone并附带迁移提示（如X-API-Deprecated: true头 + JSON提示文案），而非直接404
用中间件识别客户端意图，动态路由或降级
某些场景下需更灵活控制，比如按Header中的Accept-Version: v2自动路由，或对未带版本号的请求默认走v1。
立即学习“go语言免费学习笔记（深入）”；
- 写一个版本解析中间件，从URL路径、Query参数或Header中提取版本号，存入
c.Set("api_version", "v2") - 在handler里根据
c.GetString("api_version")决定调用哪套业务逻辑，适合小范围兼容逻辑 - 不建议全量用此方式替代路径分组——它增加调试难度，且违反RESTful对资源路径语义的约定
文档与生命周期管理不能少
没有文档的版本控制等于埋雷。每个版本上线后，必须同步更新OpenAPI（Swagger）定义，并标注废弃状态。
- 用
swag init -g ./main.go --parseDependency --parseInternal生成多版本文档，配合// @Version 1.2注释 - 在API网关或内部监控中记录各版本调用量趋势，设定下线时间表（如v1在v3上线后6个月停服）
- 提供版本变更日志（Changelog）和迁移指南，重点说明字段变更、错误码调整、性能影响等实际影响点
