Fiber 本身不提供自动版本路由切换，必须靠 Group 显式分组 + 统一前缀管理，否则易导致路径重复、中间件错配、参数解析失败等问题。
直接结论：Fiber 本身不提供自动版本路由切换，必须靠 Group 显式分组 + 统一前缀管理，否则容易出现路径重复、中间件错配、参数解析失败等问题。
为什么不能只靠中间件或路由参数做版本控制
有人试图用 ctx.Params("version") 或中间件里解析 URL 片段来分流，这在 Fiber 中不可靠：
- Fiber 的基数树（radix tree）匹配是精确前缀驱动的，
/v1/users和/v2/users是完全独立的节点，无法靠运行时判断“动态跳转” - 如果写成
app.Get("/:version/users", handler)，会和/v1/users/:id冲突——因为:version是通配节点，会提前捕获所有一级路径，导致子路由失效 - 没有内置的版本协商（如 Accept header 解析），
application/vnd.myapi.v1+json这类格式需手动解析，且无法和路由树联动
正确创建 v1/v2 分组并避免路径拼接错误
最稳妥的方式是每个版本用独立 Group，且子路由路径**必须带全量前缀**（Fiber 不会自动补）：
app := fiber.New()
v1 := app.Group("/v1")
v1.Get("/users", getUsersV1)
v1.Post("/users", createUserV1)
<p>v2 := app.Group("/v2")
v2.Get("/users", getUsersV2)
v2.Post("/users", createUserV2)
常见错误写法：
-
v1 := app.Group("/v1"); v1.Get("/v1/users", ...)→ 实际匹配/v1/v1/users -
app.Group("/v1").Get("/users", ...)没赋值给变量 → 后续无法复用该组注册其他方法（如Post） - 把版本号硬编码进 handler 名（如
getUsersV1），但路由注册漏掉 v1 分组 → 请求直接 404
如何共享中间件又隔离版本逻辑
版本分组天然支持中间件隔离。比如鉴权规则不同：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
v1 := app.Group("/v1")
v1.Use(authV1Middleware) // 只对 /v1/* 生效
v1.Get("/users", getUsersV1)
<p>v2 := app.Group("/v2")
v2.Use(authV2Middleware) // 独立配置，不影响 v1
v2.Get("/users", getUsersV2)
注意点：
- 全局中间件（
app.Use()）仍会先执行，比如日志、CORS；版本级中间件在其后 - 不要在 v1 分组里注册
/health这类无版本语义的路径——应放到根路由或单独app.Group("/health") - 若需 v1 和 v2 共享某个 handler（如公共错误页），别塞进某个分组，而是在根路由注册：
app.Get("/error", commonErrorPage)
StrictRouting 对多版本的影响很隐蔽
默认开启 StrictRouting: true 会导致 /v1/users/ 和 /v1/users 被视为两个路由。如果你只注册了后者，前端发带尾斜杠的请求就 404。
解决方式不是关 StrictRouting（会破坏 /v1/users/:id 和 /v1/users 的区分），而是统一重定向：
app.Use(func(c fiber.Ctx) error {
path := c.Path()
if strings.HasSuffix(path, "/") && path != "/" {
return c.Redirect(strings.TrimSuffix(path, "/"), 301)
}
return c.Next()
})
这个中间件要放在所有 Group 之前，否则 v1/v2 分组里的路由可能还没走到它就被基数树判为不匹配。
真正麻烦的是文档和客户端一致性：OpenAPI 规范里写的路径、SDK 生成的 URL、前端 axios 调用的 baseURL，必须全部对齐版本前缀。少一个 /v2，线上就出 404，而且 Fiber 不会报“路由模糊匹配”，只会静默失败。
