Fiber框架需手动实现API版本控制，不支持Spring Boot 4式的@Get(version="1")声明；核心是在中间件中从路径、请求头或查询参数提取版本号并存入c.Locals，供后续逻辑分支处理。
Fiber 框架本身不内置 API 版本控制中间件，必须手动实现或组合已有机制。它不像 Spring Boot 4 那样在 @Get 上直接支持 version 属性，也没有 ApiVersionConfigurer 这类配置钩子。你要检测版本号，核心是「在请求进入业务逻辑前，从某处提取版本标识，并决定是否放行、重定向或返回错误」。
怎么在 Fiber 中间件里读取版本号
版本号来源决定了中间件写法，常见三种方式对应不同提取逻辑：
- 路径中带
v1、v2：比如/api/v1/users→ 用c.Params("version")或正则匹配c.Path() - 请求头如
API-Version: 2→ 用c.Get("API-Version")（注意大小写敏感，Fiber 默认转为小写，实际取c.Get("api-version")） - 查询参数
?version=2→ 用c.Query("version")
示例中间件（路径提取）：
func VersionCheck() fiber.Handler {
return func(c *fiber.Ctx) error {
path := c.Path()
re := regexp.MustCompile(`/v(\d+)/`)
matches := re.FindStringSubmatchIndex([]byte(path))
if matches == nil {
return c.Status(fiber.StatusBadRequest).SendString("missing version in path")
}
versionStr := string(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()
}
}
为什么不能只靠路由分组做版本隔离
单纯用 app.Group("/v1") 只是组织路由前缀，不解决「同一路径下多版本共存+运行时决策」的问题。比如你希望：
-
GET /users根据API-Version头自动走 v1 或 v2 的 handler - v2 接口允许调用 v1 的部分逻辑（复用 service 层），但要拦截非法版本访问
- 文档生成工具（如 Swagger/FiberSwagger）能识别并标注版本
这些都需要中间件把版本信息注入 c.Locals，再由后续 handler 读取判断，而不是靠路由树硬拆。
容易踩的坑：版本解析和路由匹配顺序
Fiber 中间件执行顺序严格依赖注册位置，常见错误有：
- 把
VersionCheck放在app.Use("/api", ...)之后 → 导致/api/v1/users的/api前缀已被截掉，c.Path()变成/v1/users，正则需同步调整 - 没处理
c.Next()后的 panic 或 error 返回 → 版本校验失败后仍继续执行下游 handler - 用
c.Get("API-Version")但客户端发的是X-API-Version或Accept头 → 必须明确约定并文档化版本传递方式 - 未对
c.Locals("api_version")做类型断言，下游直接强转int→ 运行时 panic
真正复杂的点不在「怎么取版本号」，而在于「取到之后怎么让整个 handler 链一致响应」——比如 v2 接口返回新字段，但 v1 要保持字段精简，这需要业务逻辑层主动分支，中间件只负责提供可靠、可信任的版本上下文。
