Gin 本身不提供「剥离路径前缀」的中间件，需通过 router.Group() 注册别名路由或手动重写 c.Request.URL.Path 与 RawQuery 并同步 c.Params，确保 handler 接收的路径和参数与注册路由一致。
直接说结论：Gin 本身不提供「剥离路径前缀」的中间件，但你可以用 router.Group() + c.Request.URL.Path 手动重写，或更稳妥地用中间件配合 c.Request.URL.Path 和 c.Request.URL.RawQuery 做路径重写后调用 c.Next() —— 关键不是“剥离”，而是让 handler 看到的路径和你注册的路由一致。
为什么不能靠中间件自动“剥离”前缀
Gin 的路由匹配发生在中间件执行之前，c.Request.URL.Path 是原始请求路径，中间件无法改变已匹配的路由目标。比如你注册了 r.GET("/api/v2/users", handler)，但用户访问的是 /legacy/v1/users，光靠中间件改 c.Request.URL.Path 不会让 Gin 自动跳转到那个 handler —— 它已经 404 了。
常见错误现象：
- 写了中间件修改
c.Request.URL.Path，但 handler 拿不到参数（c.Param("id")为空） - 用了
c.Redirect()，但前端收到 301/302，暴露了旧路径 - 试图在中间件里调用
c.Handler()或硬塞 handler，结果 panic：「handler is not a function」
真正能落地的两种方式
方式一：用 router.Group() 注册别名路由（推荐）
这是 Gin 官方鼓励、零 runtime 开销的做法。本质是把旧路径当 Group 前缀，复用新 handler：
// 新接口定义在 /api/v2/
v2 := r.Group("/api/v2")
v2.GET("/users", userHandler)
v2.POST("/users", userHandler)
// 旧路径 /legacy/v1/ → 映射到同一组 handler
legacy := r.Group("/legacy/v1")
legacy.GET("/users", userHandler) // 注意：这里路径是 "/users"，不是 "/legacy/v1/users"
legacy.POST("/users", userHandler)
注意点：
-
r.Group("/legacy/v1")的前缀必须以/开头，且结尾不能带/（/legacy/v1/会导致实际注册成/legacy/v1//users） - handler 内部仍用
c.Param("id")、c.Query("page")，完全无感知 - 如果旧路径含动态段（如
/legacy/v1/users/:id），必须显式写全：legacy.GET("/users/:id", userHandler)
需要透传 query 和 path 参数时怎么办
当旧路径结构和新路径不一致（比如 /v1/user?id=123 → /v2/users/123），Group 就不够用了。这时得写中间件做路径重写 + 参数提取：
func legacyToV2Middleware() gin.HandlerFunc {
return func(c *gin.Context) {
oldPath := c.Request.URL.Path
if strings.HasPrefix(oldPath, "/v1/user") {
// 提取 id（假设来自 query）
id := c.Query("id")
if id != "" {
// 重写为 /v2/users/{id}
c.Request.URL.Path = "/v2/users/" + id
c.Request.URL.RawQuery = "" // 清空原 query，避免重复
c.Next()
return
}
}
c.AbortWithStatus(http.StatusNotFound)
}
}
使用时挂到根 router：
r.Use(legacyToV2Middleware())
r.GET("/v2/users/:id", userHandler) // 这个 handler 必须存在且能处理 :id
风险提示：
- 必须确保重写后的路径与已注册路由完全匹配，包括 trailing slash、大小写、参数占位符名称
- 不要在中间件里调用
c.JSON或c.String后还执行c.Next()，否则 panic -
c.Request.URL是指针，改它会影响后续中间件，但 Gin 路由已匹配完毕，所以 handler 能读到新路径，但c.Param()不会自动更新 —— 你需要手动c.Params = gin.Params{{Key: "id", Value: id}}
最易被忽略的一点：Gin 的路由匹配基于前缀树（Radix Tree），所有路径注册都是静态构建的。所谓「剥离前缀」其实是人工对齐路径结构，而不是运行时魔法。Group 方式安全、清晰；手动重写方式灵活但要自己兜底参数映射和错误处理。
