用URL路径做版本控制最稳妥，如/v1/users和/v2/users隔离handler；应避免query或header传版本号，推荐按版本分组路由、分包管理handler、禁止跨版本复用struct。
用 URL 路径做版本控制最稳妥
绝大多数 Go Web 框架（gin、echo、chi）都默认支持路径前缀路由，这是实现版本控制最直观、兼容性最好、也最容易调试的方式。客户端请求 /v1/users 和 /v2/users 时，后端可完全隔离两套 handler 逻辑，互不干扰。
常见错误是把版本号塞进 query 参数（如 /users?version=v2）或 header（如 Accept: application/vnd.myapi.v2+json），这会导致缓存失效、CDN 难以识别、日志聚合困难，且 OpenAPI 文档生成和测试都更麻烦。
实操建议：
- 在路由注册阶段就按版本分组，例如
router.Group("/v1")和router.Group("/v2") - 每个版本的 handler 应放在独立包下（如
handlers/v1和handlers/v2），避免交叉引用 - 不要复用同一 struct 做多个版本的 request/response，哪怕字段一致——改一个版本的字段可能意外影响另一个版本
- 如果用
gin，注意Use()中间件作用域：全局中间件对所有版本生效；而group.Use()只影响该版本
用 Accept Header 实现灰度发布但需谨慎
当需要对少量用户渐进式上线 v2 接口（比如只对 user_id % 100 的用户启用新逻
辑），又不想改 URL，可以用 Accept 或自定义 header（如 X-API-Version: v2）做运行时路由分发。但这不是标准 RESTful 版本控制推荐做法，属于灰度/AB 测试范畴。
容易踩的坑：
-
Accept值应遵循application/vnd.{vendor}.{api}+json格式，例如application/vnd.example.users+json; version=2，但很多前端库（如 axios、fetch）默认不设此 header，调试时容易漏掉 - 不能依赖
Content-Type判断版本，它描述的是请求体格式，不是 API 语义版本 - 若同时存在路径版本（
/v1/users）和 header 版本，必须明确定义优先级，否则逻辑混乱
func versionRouter(c *gin.Context) {
accept := c.GetHeader("Accept")
if strings.Contains(accept, "version=2") {
handleV2User(c)
return
}
handleV1User(c)
}
用中间件统一拦截并校验版本有效性
无论用路径还是 header 控制版本，都应在入口处强制校验：非法版本号（如 /v999/users 或 X-API-Version: v3）必须返回 400 Bad Request 或 406 Not Acceptable，而不是静默降级到 v1 —— 这会让客户端误以为调用成功，埋下兼容隐患。
关键点：
- 版本号应集中定义为常量（如
const V1 = "v1"），避免硬编码字符串散落在各处 - 中间件中解析出版本后，建议写入
c.Set("api_version", "v2")，后续 handler 可安全读取，无需重复解析 - 不要在中间件里做业务逻辑分支（如 “if v2 { do X } else { do Y }”），保持职责单一；版本差异应由不同 handler 承担
数据库迁移与版本共存的实际约束
API 版本升级常伴随数据结构变更（如 v2 新增 status_reason 字段），但线上不可能立刻停掉 v1。此时必须保证：
- v1 handler 读写的数据结构，对 v2 来说仍是合法子集（即 v2 允许字段为空或有默认值）
- 数据库字段不能直接删，只能标记为 deprecated；新增字段需设默认值或允许 NULL，否则 v1 插入会失败
- 如果 v2 引入了破坏性变更（如合并两个表），必须通过视图、DTO 转换层或双写逻辑隔离，不能让 v1 直接操作新 schema
最易被忽略的一点：日志和监控指标必须带上 api_version 标签。否则当 v2 出现 5xx 错误率飙升时，你无法快速判断是新逻辑问题，还是旧版本流量误打到了新 handler 上。
