正确用法是app.Group("/v1")后子路由必须写全路径如v1.Get("/users", h)；错误写法如v1.Get("users", h)注册为/users导致404，或v1.Get("/v1/users", h)注册为/v1/v1/users。
怎么用 app.Group() 正确创建带前缀的路由分组
Fiber 的 Group 不是自动补前缀的“魔法盒子”，它返回一个新 *fiber.Router，但子路由路径必须写全量（含前缀），否则 404。注册时 Fiber 会把 group 前缀和你传入的路径字符串拼起来——这个拼接只发生在注册阶段，不参与运行时匹配。
正确写法：
v1 := app.Group("/v1")
v1.Get("/users", getUsersV1)
v1.Post("/users", createUserV1)
常见错误：
-
v1.Get("users", h)→ 实际注册的是/users，匹配不到/v1/users -
v1.Get("/v1/users", h)→ 实际注册的是/v1/v1/users，请求/v1/users直接 404 - 链式调用
app.Group("/v1").Group("/users").Get("/list", h)→ 路径变成/v1/users/list，但中间多了一层对象跳转，重构难、调试懵
为什么不能只靠 Group 实现运行时版本判断
单纯用 app.Group("/v1") 只能隔离前缀和中间件，无法支持「同一路径下按请求头或参数动态分流」这类需求。比如你希望：
- GET
/users根据API-Version: 2自动走 v2 handler - v2 接口复用 v1 的 service 层逻辑，但要拦截非法版本访问
- Swagger 文档能识别并标注当前版本
这些都需要在请求进入 handler 前，把版本号提取出来存进 c.Locals，而不是靠路由树硬拆。Fiber 的基数树匹配是精确前缀驱动的，/v1/users 和 /v2/users 是两个完全独立的节点，没法运行时“跳转”。
错误尝试：app.Get("/:version/users", handler) 会导致通配节点提前捕获所有一级路径，让 /v1/users/:id 这类子路由失效。
怎么写中间件从路径/请求头提取版本号并注入 c.Locals
版本号来源决定中间件写法。三种主流方式对应不同提取逻辑，关键点是：提取后必须存进 c.Locals，供后续 handler 读取分支；且中间件要放在 Group 内注册，避免污染其他路由。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
路径提取示例（推荐）：
func VersionFromPath() fiber.Handler {
return func(c *fiber.Ctx) error {
re := regexp.MustCompile(`/v(\d+)/`)
matches := re.FindStringSubmatchIndex([]byte(c.Path()))
if matches == nil {
return c.Status(fiber.StatusBadRequest).SendString("missing version in path")
}
versionStr := string(c.Path()[matches[0][2]:matches[0][3]])
version, _ := strconv.Atoi(versionStr)
if version < 1 || version > 3 {
return c.Status(fiber.StatusNotFound).SendString("unsupported version")
}
c.Locals("api_version", version)
return c.Next()
}
}
使用方式：
v1 := app.Group("/v1")
v1.Use(VersionFromPath()) // 注意：这里注册的是中间件，不是 handler
v1.Get("/users", func(c *fiber.Ctx) error {
v := c.Locals("api_version").(int)
if v == 1 {
// 处理 v1 逻辑
}
return c.JSON(200, "ok")
})
注意事项：
- 请求头如
API-Version: 2，实际要用c.Get("api-version")（Fiber 默认转小写） - 查询参数用
c.Query("version") - 中间件必须在 Group 上注册，否则
c.Locals不会被后续 handler 看到
如何共享业务逻辑又保持版本隔离
版本差异应集中在 API 层（路由 + handler），通用能力必须下沉。硬塞 if version == 2 到 handler 或 service 里，v3 上线时就会指数级膨胀。
推荐结构：
- 控制器层：每个版本对应独立 handler，只做参数解析、版本路由、响应组装
- Service 层：完全复用，比如
userSvc.GetUserByID(id)对 v1/v2 都可用 - Response 构建：用独立 builder，如
UserResponseV1.Build(u)和UserResponseV2.Build(u) - 验证逻辑：各版本定义自己的
ValidateUserV1/ValidateUserV2，不共用 struct tag
中间件也按需隔离：v1.Use(authV1Middleware) 和 v2.Use(authV2Middleware) 互不影响，但全局中间件（如日志、CORS）仍会在它们之前执行。
最易被忽略的一点：错误响应格式必须和当前版本对齐。v2 请求如果落到 v1 的全局异常处理器，返回的 JSON 结构很可能不兼容——这意味着你要为每个 Group 单独注册错误处理中间件，或在统一错误中间件里先查 c.Locals("api_version") 再格式化输出。
