中间件通过白名单路径（如/api、/users）识别无版本API请求，匹配^/v\d+/则放行，否则重写为/v1/users并同步RawPath；须避免与Group前缀叠加，文档生成应基于注册路径而非中间件补全。
中间件里怎么判断并补全缺失的版本号
当客户端请求 /users 这类无版本路径时，中间件需主动识别并注入默认版本（如 v1），但不能盲目重写所有路径——只对明确属于 API 范围的路径生效。常见错误是把 /health、/metrics 或静态资源也套上版本前缀。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 用正则或前缀白名单限定作用范围，例如只处理以
/api、/v（不含数字）、/users等开头的路径 - 检查请求路径是否已含版本标识：若匹配
^/v\d+/或/api/v\d+/，直接放行 - 仅当路径为
/users、/orders等“根级资源路径”且无版本前缀时，才重写为/v1/users - 避免修改原始
c.Request.URL.Path后不调用c.Request.URL.RawPath同步更新，否则后续路由匹配可能失败
gin.Group + 中间件组合怎么避免重复加前缀
如果既用了 r.Group("/v1") 又在中间件里把 /users 改成 /v1/users，最终会变成 /v1/v1/users ——这是最常踩的坑。Gin 的 Group 本质是路径拼接，中间件重写路径后，Group 的前缀仍会叠加。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 二选一：要么纯靠中间件补全 + 全局注册路由（如
r.GET("/users", handler)），要么纯靠Group分离（如v1.GET("/users", handler)），不要混用 - 若坚持用 Group，中间件只做版本校验和上下文注入（如
c.Set("version", "v1")），不再重写 URL - 若必须重写路径，注册路由时用通配符（如
r.Any("/*path", versionMiddleware)），并在中间件末尾显式调用c.Request.URL.Path = newPath和c.Request.URL.RawPath = newPath
如何让补全逻辑不影响 OpenAPI 文档生成
swaggo/swag 依赖路由注册时的原始路径生成文档。中间件动态补全的路径不会被扫描到，导致 /v1/users 在文档里显示为 /users，误导前端开发者。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 文档生成阶段绕过中间件，直接读取
gin.Engine.Routes()获取真实注册路径 - 若使用
Group方式，每个版本 group 单独打@Tags v1和@Version 1.0注释，swag 才能正确分组 - 禁止在 handler 上写
@Param version query string false "API version"来模拟路径版本——这会让文档和实际行为不一致 - 补全中间件本身不参与文档生成，它只是运行时兜底逻辑，文档应反映设计态约定（即“所有 API 必须带 /v{N} 前缀”）
默认版本补全后怎么保证 handler 能正确分发
中间件把路径改成 /v1/users，但如果没有对应路由注册，Gin 仍会 404。补全只是第一步，关键是要有能匹配新路径的 handler。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 补全后必须确保存在
r.Group("/v1").GET("/users", ...)这类显式路由，不能指望中间件“自动转发”到某个函数 - 更安全的做法是：中间件只设置
c.Set("api_version", "v1")，然后所有 handler 开头统一读取该值，再 switch 分支调用handleUsersV1(c)或handleUsersV2(c) - 若用 switch 分发，务必在 default 分支返回
406 Not Acceptable，而不是 fallback 到 v1——这会掩盖客户端错误 - 注意
c.GetHeader("X-API-Version")和路径补全逻辑的优先级：建议 header > 路径 > 默认，三者冲突时以 header 为准（便于灰度）
