Fiber 不支持自动版本路由切换，必须用 Group 显式分组并统一前缀管理；动态参数 :version 会破坏基数树匹配、阻断子路由注册、无法对齐中间件生命周期，Accept 头协商需手动处理；正确做法是为每个版本创建独立 Group（如 v1 := app.Group("/v1")），子路由路径须以 / 开头且不含重复前缀；中间件按作用域隔离，全局中间件优先执行，版本级中间件仅影响对应前缀；需注意 OpenAPI 文档同步、结构体字段兼容性及 Fiber 版本差异。
Fiber 本身不提供自动版本路由切换，必须靠 Group 显式分组 + 统一前缀管理，否则容易出现路径重复、中间件错配、参数解析失败等问题。
为什么不能用 :version 动态参数做路由分流
Fiber 的路由树是基数树（radix tree），匹配基于精确前缀。写成 app.Get("/:version/users", handler) 看似灵活，实际会破坏子路由结构：
-
/:version是通配节点，会提前捕获所有一级路径，导致/v1/users/:id这类带二级参数的路由永远无法注册成功 - 无法与中间件生命周期对齐：比如
v1需要 JWT 解析scope:read_v1，v2要校验scope:read_v2，动态参数没法触发不同中间件链 - Accept header 版本协商（如
application/vnd.myapi.v2+json）需手动解析，且 Fiber 不支持将其映射到路由分支，纯属业务层补丁
正确创建 /v1 和 /v2 分组的写法
每个版本必须用独立 Group，且子路由路径**必须以 / 开头、不含重复前缀**——Fiber 不会自动拼接父级前缀：
app := fiber.New()
v1 := app.Group("/v1")
v1.Get("/users", getUsersV1) // ✅ 匹配 /v1/users
v1.Post("/users", createUserV1)
v2 := app.Group("/v2")
v2.Get("/users", getUsersV2) // ✅ 匹配 /v2/users
v2.Post("/users", createUserV2)
常见错误写法：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
-
v1 := app.Group("/v1"); v1.Get("/v1/users", ...)→ 实际匹配/v1/v1/users -
app.Group("/v1").Get("/users", ...)没赋值给变量 → 后续无法复用该组注册Post或Use - handler 名含
V1但漏掉v1.Group()→ 请求直接 404，连中间件都不会执行
如何在隔离版本的同时共享/差异化中间件
版本分组天然支持中间件作用域隔离，但要注意执行顺序：
- 全局中间件（
app.Use()）始终最先执行，比如日志、CORS、请求 ID 注入 - 版本级中间件（
v1.Use()）在其后，只影响对应前缀路径 - 示例中
authV1Middleware和authV2Middleware可分别处理不同 token 格式或 scope 规则，互不干扰
如果某中间件需跨版本共用（如统一限流），建议放在全局层；若逻辑差异大，务必拆到各 Group 内注册，避免隐式耦合。
容易被忽略的兼容性细节
路径拼接错误和中间件作用域只是表象，真正难调试的是版本升级时的「静默失效」：
- 新增
/v3时，别忘了同步更新 OpenAPI 文档中的basePath和servers字段 - 如果用 GORM 查询，
v1返回UserV1结构体（含字段full_name），v2改为firstName/lastName，千万别在 handler 里直接复用同一张表的SELECT *—— 字段映射错位不会报错，只会返回空值 - Fiber v2.x 不支持
Route方法嵌套声明（如app.Route("/api", func(r fiber.Router) { r.Group("/v1")... })），这种写法在 v3 才可用，生产环境请严格锁定 v2 版本
