应优先从请求头（如X-API-Version）提取版本号，fallback至query参数，校验是否为预设值（如v1/v2），非法则返回406；验证通过后将版本注入c.Locals("api_version")供handler分支处理，且仅对/api/*路径启用该中间件。
中间件里怎么提取并校验 API 版本号
版本控制不是靠 URL 路径硬编码（比如 /v1/users），而是通过请求头（如 X-API-Version）或 query 参数（如 ?version=v2）提取后统一拦截。中间件需优先读取、解析、验证，再决定是否放行或返回 400/406。常见错误是直接用 c.Params("version")——那只能匹配 /api/:version/users 这种路径占位符，而真实场景中版本标识往往不在路径里。
推荐顺序：先查 c.Get("X-API-Version")， fallback 到 c.QueryParam("version")，最后检查是否为空或格式非法（如非 v1、v2 等预设值）。注意别用 c.FormValue 或 c.Body() 去解析版本，它们不适用。
- 语义化版本（如
v2.1.0）建议只取主版本号做路由分发，避免规则爆炸 - 若允许
Accept: application/vnd.myapp.v2+json，需用c.Get("Accept")解析 media type，提取v2 - 校验失败时直接
return c.Status(406).JSON(fiber.Map{"error": "unsupported version"})，不要调c.Next()
如何让不同版本走不同 handler 而不重复注册路由
不能为每个版本都写一套 app.Get("/users", v1Handler) 和 app.Get("/users", v2Handler)——这会导致路由冲突，Fiber 不支持同路径多 handler。正确做法是：所有版本共用同一组路由定义，由中间件把版本信息注入 c.Locals，后续 handler 从 c.Locals("api_version") 读取并分支处理。
- 在中间件末尾加
c.Locals("api_version", version)，确保后续 handler 可安全读取 - handler 内部用
switch ver := c.Locals("api_version").(string) { case "v1": ... }分支 - 避免在中间件里直接
return c.Redirect(...)跳转到新路径——这破坏了 REST 语义，也绕过后续中间件（如鉴权） - 若必须隔离逻辑，可提前在中间件里根据版本号挂载不同子 router（如
v1Group := app.Group("")），但需确保路径前缀一致
为什么全局 Use() 会破坏灰度或环境隔离
用 app.Use(versionMiddleware) 是错的——它会对 /health、/metrics、/favicon.ico 全部执行版本校验，既没必要，又可能干扰监控链路。版本控制只应作用于业务 API 路径，比如 /api/*。
- 正确挂载方式：
api := app.Group("/api", versionMiddleware)，然后api.Get("/users", handler) - 若需区分环境（如
staging允许v3，prod最高只到v2），中间件内应读取os.Getenv("ENV")或c.Get("X-Env")，而非写死规则 - 注意
app.Use("/api", versionMiddleware)和app.Group("/api", versionMiddleware)行为一致，但后者更语义清晰、便于嵌套其他中间件（如 JWT） - 别在中间件里修改
c.Path()或重写 URL——Fiber 的路由匹配发生在中间件之前，改了也没用
兼容性与降级策略最容易被忽略的点
版本中间件不能只做“拦截”，还要提供平滑降级能力。比如客户端传了 v3，但服务端尚未上线，是返回 404、406，还是自动 fallback 到 v2？这取决于业务契约。很多团队卡在这里：没定义默认版本，也没声明废弃策略。
- 必须明确一个
defaultVersion（如v1），当请求未带版本头时，自动设为该值并记录 warn 日志 - 对已废弃版本（如
v0），建议返回410 Gone+Retry-After头，而非静默 fallback - 若用
StrictRouting: true（默认），注意/api/v1/users/和/api/v1/users是两个路径，中间件需统一 normalize 尾斜杠，否则版本判断可能错位 - 前端 SDK 应内置版本协商逻辑（如自动带
X-API-Version），而不是靠后端猜——中间件只是守门人，不是版本发现服务
