应使用 gin.Group() 创建 /v1 和 /v2 分组实现版本路由，避免手写路径；各分组可独立挂载中间件，路径自动前置防错；不支持自动 fallback，需手动处理未知版本；推荐路径前缀而非 query 或 header 版本化。
用 gin.Group() 按前缀分版本，别手写路由拼接
直接在根路由下用 gin.Group() 创建 /v1 和 /v2 分组，是最干净、最符合 Gin 设计意图的做法。手写 r.GET("/v1/users", ...) 看似简单，但后续中间件、参数绑定、错误统一处理都会变麻烦。
- 每个分组可独立挂载中间件（比如
v2需要新鉴权逻辑，v1保持旧逻辑） - 分组路径自动前置，避免漏写或写错前缀（比如误写成
/V1或/api/v1） - 路由树结构清晰，
gin.DumpRoutes()能一眼看出版本隔离是否完整
示例：
r := gin.Default()
v1 := r.Group("/v1")
{
v1.GET("/users", getUsersV1)
v1.POST("/users", createUserV1)
}
v2 := r.Group("/v2")
{
v2.GET("/users", getUsersV2)
v2.POST("/users", createUserV2)
}
版本路由必须显式声明，Gin 不会自动 fallback 到 v1
如果用户请求 /v3/users，而你只定义了 v1 和 v2 分组，Gin 默认返回 404 —— 它不会“降级”到最近的已存在版本。这点常被误认为是“版本兼容”，其实是缺失设计。
- 需要 fallback 必须手动实现：加一个兜底
r.NoRoute()检查路径前缀，再重定向或返回特定错误 - 更稳妥的做法是拒绝未知版本，返回
400 Bad Request并带明确提示（如"unsupported api version: v3"） - 别依赖 Nginx 或网关做版本路由转发后再进 Gin，那会让 Gin 层的路由调试和日志混乱
中间件作用域要对齐版本生命周期
版本升级往往伴随数据格式、权限模型、限流策略变化。把中间件挂错位置，会导致 v1 接口意外执行 v2 的校验逻辑，或者 v2 漏掉关键审计。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 通用中间件（如日志、CORS）可以注册在根路由
r.Use(...) - 版本专属中间件（如 v2 新增的 JWT scope 校验）必须挂到对应
Group()内部 - 避免在分组内重复注册根路由已有的中间件，除非明确需要覆盖行为（例如 v2 要禁用某项旧限流）
URL 前缀不是唯一方案，但 query 参数或 header 版本化更难维护
用 ?version=v2 或 Accept: application/vnd.myapp.v2+json 看似灵活，实际在 Gin 里要靠手动解析、条件分支、甚至重写路由匹配逻辑，很快就会失控。
- Gin 的
router.Handle()不支持基于 query 或 header 的原生路由分发 - 所有 handler 都得先做版本判断，再调用对应业务函数，代码分散、测试难覆盖
- API 文档（如 Swagger）无法自动生成不同版本的 endpoint，需额外标注或拆分 spec 文件
- CDN、网关、监控系统对路径前缀识别最稳定；query/header 方式容易被缓存穿透或日志丢失
路径前缀不是银弹，但它把版本边界落在 URL 这个最外层契约上，让协作、排障、演进都有明确锚点。
真正容易被忽略的是：版本分组之后，各版本的 handler 函数名、单元测试文件、DTO 结构体最好也带上 V1/V2 后缀。否则几个月后连自己都分不清哪个 UserResponse 是哪个版本的。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
