路径前缀式版本路由（/api/v1、/api/v2）是唯一兼顾缓存、监控、调试与灰度的方案；query参数或Accept头会导致CDN缓存击穿、Prometheus指标混杂、Swagger文档错乱及日志归因困难。
必须用 e.Group("/api/v1") 和 e.Group("/api/v2") 显式分组，路径前缀是唯一能兼顾缓存、监控、调试和灰度的方案；其他方式（如 query 参数或 Accept 头）会导致 CDN 缓存击穿、Prometheus 指标混杂、日志无法归因。
为什么不能用 version 查询参数或 Accept 头做主路由
看似灵活，实则破坏整个可观测链路：
- CDN 和 Nginx 的
proxy_cache_key默认不含 query 或 header，/users?version=v2和/users?version=v1会被缓存为同一 key，导致响应错乱 - Prometheus 中
http_request_duration_seconds{path="/users"}会把 v1/v2 流量全聚合，查慢请求时根本分不清是哪个版本的问题 - Swagger 文档生成器（如 swaggo）按路径注册 schema，
@Success 200 {object} UserV2写在 v1 handler 里，v1 文档里就直接出现 v2 字段 - 前端直访、Postman 调试、Nginx access log 都得额外解析 query/header，上线后查问题多一层人工判断
e.Group() 分组注册时的三个硬性要求
分组不是语法糖，是物理隔离边界，以下三点不满足就会出 404 或逻辑串包：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 每个版本必须一级声明完整路径：
v1 := e.Group("/api/v1/users")，禁止嵌套e.Group("/api").Group("/v1").Group("/users")——后者会让中间件挂载错层、日志路径与实际匹配路径不一致 - 路径必须严格对齐：如果
v2.GET("/users/:id", handler)，那v1.GET("/users/:id", legacyHandler)也必须显式注册，否则/api/v1/users/123直接 404 - 中间件必须按组独立注册：
v1.Use(jwtAuthV1())和v2.Use(oauth2Scope("users:read"))不能共用一个中间件实例，v2 新增双因素校验时不能影响 v1
DTO 结构体必须按版本拆开，哪怕字段一模一样
Go 的 JSON 序列化没有运行时 schema 校验，共用 struct 是最隐蔽的兼容性炸弹：
立即学习“go语言免费学习笔记（深入）”；
- 定义
UserV1和UserV2两个结构体，即使当前字段完全相同，也要分开声明 -
UserV2加了Nickname string `json:"nickname"`，但 v1 handler 若误用UserV2{}返回，v1 客户端解析 JSON 会 panic（字段不存在或类型不匹配） - 别用指针“模拟可选字段”来凑合老版本：
UserV1.Name是string（必填），UserV2.Name是*string（可选），这是契约差异，不能靠nil掩盖 - 数据库 model（如 GORM struct）保持稳定，API 层响应必须显式转换：
userV1 := toUserV1(dbUser)，绝不裸露底层模型
最容易被忽略的是：版本分组后，handler 里不要再用 strings.HasPrefix(c.Request().URL.Path, "/api/v1") 手动判断版本——分组已隔离，重复判断不仅冗余，还会在路径拼接出错时引入隐藏 bug。真正要关注的是 DTO 转换是否漏字段、中间件是否漏挂、文档注释是否绑定到对应 group。
