不能用 ctx.Redirect() 处理 API 版本兼容，因其触发 HTTP 3xx 重定向，而多数 API 客户端不自动跟随，导致请求失败、数据丢失、监控失真；应改用内部路由转发+响应转换。
直接用 ctx.Redirect() 做旧版 API 兼容会出问题——它发的是 HTTP 3xx 响应，客户端必须跳转，而多数 API 客户端（尤其是移动端 SDK 或老系统）根本不会处理重定向，直接报错或丢弃响应。
为什么不能用 Redirect 处理 API 版本兼容
ctx.Redirect() 是面向浏览器的页面跳转机制，底层发的是 301 或 302 状态码 + Location 头。但 API 场景下：
- 绝大多数 HTTP 客户端（如 OkHttp、AFNetworking、axios 默认配置）不会自动跟随重定向，尤其对 POST/PUT 请求更保守
- 重定向后原始请求方法、body、header 全部丢失，
POST /v1/users重定向到/v2/users后变成无 body 的 GET - 监控和链路追踪里出现额外跳转，掩盖真实调用路径，日志里看到的是两个独立请求，不是一次逻辑调用
- 无法控制响应体内容——你没法在重定向响应里塞 JSON 错误提示或迁移指引
正确做法：用内部路由转发代替外部重定向
让 /v1/users 请求实际执行 GetUsersV2() 逻辑，但返回 v1 兼容结构。关键不是“跳”，而是“代理+转换”：
- 注册
v1 := r.Group("/v1")，然后v1.GET("/users", func(c *gin.Context) { ... })，里面调用 v2 业务逻辑，再用toUserRespV1()封装响应 - 不要写
c.Redirect(http.StatusMovedPermanently, "/v2/users")—— 这是陷阱 - 如果真要通知客户端升级，可在响应头加
X-API-Deprecated: true和X-API-Redirect-To: /v2/users，由客户端自行决策 - 转发时保留原始
c.Request.Body和c.Request.Header，避免鉴权信息丢失
路由注册顺序导致转发失效的典型坑
Gin 路由匹配是顺序优先，不是最长前缀优先。下面这段代码会让所有 /v1/* 请求被第一个 GET 拦截，v1 Group 内的子路由全失效：
r.GET("/v1/:id", handler) // ❌ 错误：通配在前
v1 := r.Group("/v1")
v1.GET("/users", getUsersV1) // ✅ 实际永远不会走到这里
必须严格按“先 Group，再注册子路由”顺序：
- 先
v1 := r.Group("/v1") - 再
v1.GET("/users", ...)、v1.POST("/users", ...) - 根路由
r上只挂跨版本中间件（如authMiddleware），别挂具体 handler
共用业务逻辑但隔离响应结构的实操要点
同一个用户查询服务，v1 返回 {"name":"Alice"}，v2 返回 {"name":"Alice","role":"admin","created_at":"..."}。硬拷贝 handler 会导致维护灾难：
- 定义分离的响应结构体：
UserRespV1和UserRespV2，字段显式声明，不依赖json:",omitempty"动态控制 - handler 函数只做领域层调用：
user, err := svc.GetUser(c.Param("id"))，不构造响应体 - 响应构造抽成独立函数：
c.JSON(200, toUserRespV1(user))或c.JSON(200, toUserRespV2(user)) - 新增字段时，v1 版本函数里直接忽略，v2 版本才赋值——语义清晰，无歧义
最易被忽略的是中间件作用域：v1 Group 里没挂鉴权中间件？那所有 v1 接口就裸奔了。跨版本通用中间件必须注册在根 r 上，或者显式传入每个 Group。
