Gin中平滑迁移URL路径应使用router.Any拦截+手动调用目标handler，而非Redirect或Handle：前者不改变状态码、保留请求体、复用中间件；后者会导致请求体丢失、中间件失效、无法灰度下线。
直接用中间件拦截旧路径并跳转到新 handler，是 Gin 里最可控、副作用最小的平滑过渡方式——它不改 HTTP 状态码、不丢请求体、不破坏客户端缓存，还能复用原有中间件链。
为什么不能用 ctx.Redirect 或 router.Handle
这两个看似快捷的方式实际会引入三类硬伤：
-
ctx.Redirect触发真实 HTTP 重定向（301/302），POST/PUT 请求体彻底丢失，前端需手动重发，埋点和监控链路断裂 -
router.Handle("GET", "/old", handler)绕过 Gin 的中间件机制，鉴权、日志、panic 恢复等全局逻辑全部失效 - 两者都会让旧路径在服务端“消失”，无法统计调用量、无法加灰度开关、无法渐进下线
router.Any 拦截 + 手动调用目标 handler 的实操要点
这是真正实现「路径不变、逻辑迁移」的核心手段。关键不是改 URL，而是接管请求上下文后精准投递给新 handler：
- 必须显式修改
c.Request.URL.Path和c.Request.Method，否则新 handler 内部的路径解析（如c.Param("id")）会出错 - 不能依赖
c.Next()或嵌套c.Redirect，Gin 不会因修改URL.Path自动重新匹配路由 - 目标 handler 必须提前定义为变量（如
userV2GetHandler），不能现场写闭包，否则无法被多个拦截点复用 - 若新 handler 依赖中间件注入的数据（如
c.MustGet("user_id")），旧路径拦截前必须确保相同中间件已执行
router.Any("/users/list", func(c *gin.Context) {
c.Request.URL.Path = "/api/users"
c.Request.Method = "GET"
userV2GetHandler(c) // 显式调用，非重定向
})
如何让拦截逻辑可灰度、可观测、可下线
平滑过渡不是一劳永逸，而是需要数据驱动的渐进过程：
- 在拦截 handler 中加埋点：记录来源 IP、User-Agent、调用频次，用 Prometheus 指标暴露
api_migration_old_path_called_total{path="/users/list"} - 通过配置开关控制是否启用拦截：
if !config.MigrationEnabled { c.Next(); return }，避免上线即全量 - 返回
Deprecation响应头：c.Header("Deprecation", "true")，提醒客户端限期迁移 - 拦截 handler 最终要移除，而非长期保留——它只是临时桥梁，不是永久路由
最容易被忽略的一点：拦截 handler 和目标 handler 共享同一份上下文，但中间件执行顺序不会自动对齐。如果新路径绑定了 authMiddleware，而拦截点没显式调用它，就会绕过鉴权——这不是 bug，是设计使然，必须人工补全。
