必须用 router.group() 实现版本控制，因其支持中间件自动注入、路径统一管理、子组嵌套及生命周期绑定；手动拼接路径会丧失这些能力，难以维护和扩展。
直接用 router.Group() 做路径前缀分组是最稳妥、最符合 Gin 设计意图的版本控制方式。其他方案（如 query 参数或 header）在 Gin 中缺乏原生支持，容易绕过中间件、难以统一日志和监控，不推荐用于生产环境。
为什么必须用 Group() 而不是手动拼接路径
手动写 r.GET("/api/v1/users", handler) 看似简单，但会丢失路由组的核心能力：中间件自动注入、基础路径统一管理、子组嵌套、以及与 gin.Engine 生命周期绑定。一旦你需要给 v1 接口加鉴权中间件，而 v2 不加，或者想把 v1 全部挂到 /legacy 下做迁移，硬编码路径就只能全局搜索替换。
正确做法是始终通过 Group() 创建隔离上下文：
v1 := r.Group("/api/v1")
v1.Use(authMiddleware) // 仅作用于 v1
v1.GET("/users", listUsersV1)
v1.POST("/users", createUserV1)
v2 := r.Group("/api/v2")
v2.Use(jwtAuthMiddleware, auditLog) // v2 用不同中间件组合
v2.GET("/users", listUsersV2)
-
Group()返回的是新RouterGroup实例，自带独立的HandlersChain，天然支持差异化中间件 - 所有子路由自动继承前缀，避免手误漏写
/v1或多写斜杠 - 后续要整体禁用 v1？只需注释掉
v1 := r.Group(...)块，不影响其他路由
Group() 嵌套与多级版本共存
当业务需要同时支持 /api/v1、/api/v2 和 /internal/v1 这类非对称路径时，不能只靠一层分组。Gin 支持无限嵌套，且每个 Group() 的 relativePath 是相对于其父组的：
api := r.Group("/api")
v1 := api.Group("/v1") // 实际路径 /api/v1
v1.GET("/users", listV1)
internal := r.Group("/internal")
intV1 := internal.Group("/v1") // 实际路径 /internal/v1
intV1.GET("/health", internalHealthCheck)
- 嵌套后各组中间件互不干扰，
api.Use()不会影响internal组 - 注意
relativePath开头不能带斜杠（如api.Group("//v1")会出错），Gin 会自动处理路径拼接 - 如果某版 API 需要完全隔离（比如运行在不同端口），那就该用多服务并行方案，而不是强行塞进一个
Group
版本路由与中间件执行顺序的隐含陷阱
很多人以为 v1.Use(mw) 只影响 v1 下注册的 handler，其实它还决定了中间件在请求链中的位置——特别是当多个 Group 共享同一中间件实例时：
commonLogger := loggerMiddleware() // 同一实例
v1 := r.Group("/v1").Use(commonLogger)
v2 := r.Group("/v2").Use(commonLogger)
v1.GET("/a", handlerA) // 日志中显示 /v1/a
v2.GET("/b", handlerB) // 日志中显示 /v2/b
- 同一个中间件实例被复用，但
c.Request.URL.Path在执行时已是完整路径，所以日志/监控能正确归因 - 但如果中间件里做了路径重写（如
c.Request.URL.Path = "/new"），会影响后续路由匹配，这种操作在版本控制场景中极危险，应避免 - 真正要隔离行为，应该用函数工厂模式：
func() gin.HandlerFunc { return func(c *gin.Context) { ... } }，确保每次Use()都拿到全新闭包
版本控制真正的难点不在路由写法，而在于 handler 内部是否真的做到了逻辑隔离：v2 的校验规则、数据库字段映射、错误码定义，都必须和 v1 解耦。否则 Group() 只是画了一条线，底下代码还是混在一起——这比路由没分组更危险。
