路径前缀分组是Fiber实现API版本控制的唯一可行方式，因其能统一解决日志聚合、CDN缓存、OpenAPI文档生成和Prometheus指标切片等问题。
路径前缀分组是 Fiber 实现 API 版本控制的唯一可行方式，其他方案（如 query、header）会在日志聚合、CDN 缓存、OpenAPI 文档生成和 Prometheus 指标切片上持续出问题。
为什么必须用 app.Group("/v1") 而不是手动拼路径
Fiber 的 app.Group() 返回一个独立的 *fiber.Router 实例，它不自动补前缀，也不修改你传入的路径字符串——但注册时会把 group 前缀和你写的子路径拼起来。这个拼接只发生在注册阶段，运行时不参与匹配。
- ✅ 正确：
v1 := app.Group("/v1"); v1.Get("/users", handler)→ 匹配GET /v1/users - ❌ 错误：
v1.Get("users", handler)→ 实际注册为/users，请求/v1/users404 - ❌ 错误：
v1.Get("/v1/users", handler)→ 注册为/v1/v1/users，请求/v1/users仍 404 - ⚠️ 链式嵌套如
app.Group("/v1").Group("/admin").Get("/dashboard", h)路径虽正确（/v1/admin/dashboard），但前缀分散，重构时极易漏改中间件或路径
每个版本必须定义独立 DTO 结构体，哪怕字段一模一样
共用 User struct 是最隐蔽的崩溃点：v2 新增字段后，v1 客户端 JSON 解析可能 panic；v1 的 json:",omitempty" 在 v2 字段为零值时，还可能让 v1 响应意外丢失旧字段。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 声明
V1User和V2User两个结构体，即使当前字段完全一致 - handler 中显式转换：
c.JSON(200, V1User{ID: u.ID, Name: u.Name})，禁止直接传 domain model - 禁用指针字段“模拟兼容”，比如把
Name string改成Name *string——这掩盖了语义变更，后续维护成本更高 - 数据库 model（如 GORM struct）保持稳定，只做存储；API 层靠手动赋值或
mapstructure.Decode做 domain → DTO 转换
别指望运行时从路径或 header 动态分流同一路径
Fiber 的基数树路由是静态注册、精确匹配的。/v1/users 和 /v2/users 是两个完全独立的节点，无法在 handler 里“跳转”到另一个版本逻辑。所谓“按 header 切版本”必须靠中间件提前提取并注入上下文。
立即学习“go语言免费学习笔记（深入）”；
- 若真需兜底支持
X-API-Version头，只应在 Group 内注册中间件：v1.Use(versionHeaderMiddleware)，解析后写入c.Locals["version"] = "v1" - 绝不混用路径前缀 + header：比如同时允许
/v1/users和X-API-Version: v2，冲突时行为不可控 -
app.Get("/:version/users", handler)是危险写法——通配符会提前捕获所有一级路径，导致/v1/users/:id等子路由失效 - Swagger 文档生成依赖路径结构，OpenAPI 的
components/schemas必须按版本拆开，否则@Success 200 {object} V1User会混进 v2 文档
最容易被忽略的是监控指标切片：Prometheus 的 http_request_duration_seconds{path="/users"} 会把所有版本流量揉在一起，查慢请求时根本分不清是哪个版本拖慢的——路径前缀是唯一能让指标、日志、网关策略对齐的锚点。
