中间件必须挂载在Group上而非根引擎，否则/v1/和/v2/权限会互相干扰；因全局r.Use()使所有版本共用同一校验逻辑，无法按版本差异化授权，且叠加挂载易引发token重复解析、c.Abort()冲突等错误。
中间件必须挂载在 Group 之上，而不是单个路由或根引擎上；否则 /v1/ 和 /v2/ 的权限会互相干扰甚至完全失效。
为什么 router.Use(AuthMiddleware()) 会让 v1/v2 权限失控
这是最常踩的坑：把鉴权中间件直接注册到全局 router 上，比如 r.Use(AuthMiddleware())，会导致所有路由（包括 /v1/xxx 和 /v2/xxx）都强制走同一套校验逻辑。但实际需求往往是「v1 只允许 user 角色，v2 要求 admin 角色」——全局中间件无法区分版本上下文。
更糟的是，如果后续又在 v2 := r.Group("/v2") 里重复 v2.Use(AdminOnlyMiddleware())，两个中间件叠加可能引发重复解析 token、重复写 header、甚至 c.Abort() 冲突导致 401/403 混乱。
- 正确做法是：每个版本 Group 自己挂自己的中间件，互不污染
- 错误写法示例：
r.Use(AuthMiddleware())+v2.Use(AdminOnlyMiddleware()) - 中间件内部不要硬编码版本判断，而应从
c.FullPath()或路径前缀提取版本信息（如/v1/），再查策略表
AuthMiddleware 怎么根据路径前缀动态校验角色
与其为每个版本写一个中间件函数，不如写一个通用版，在运行时识别请求路径所属版本，再查对应权限策略。比如 /v1/users 查 v1_permissions 表，/v2/orders 查 v2_permissions 表。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
关键点在于：中间件不能假设版本已知，而要主动解析。Gin 提供 c.Request.URL.Path 或更稳妥的 c.FullPath()（已处理路由参数）。
- 用
strings.HasPrefix(c.FullPath(), "/v1/")判断是否属于 v1 - 从 context 中取用户角色（如
c.GetString("role")，由前置 auth 中间件注入） - 查表或 map 判断该角色是否被允许访问当前路径，例如：
v1Policy["/users"] == []string{"user", "admin"} - 不满足时调用
c.AbortWithStatusJSON(403, gin.H{"error": "forbidden"})，别用c.JSON+c.Abort()分两步，容易漏掉 abort
如何避免 v1.Group("/users") 下的子路由全部 404
现象是：定义了 v1 := r.Group("/v1")，但在它外面提前注册了类似 r.GET("/v1/:id", handler) 这种通配根路由，结果所有 v1.Group("/users") 下的 GET /v1/users 全部 404 —— 因为 Gin 路由匹配是顺序优先，且 /v1/:id 会贪婪匹配 /v1/users（:id 被当成字符串 "users"）。
- 所有版本路由必须严格通过
Group()组织，禁止在 Group 外写同前缀的独立路由 - 调试时用
r.Routes()打印全部注册路由，确认/v1/users是否真的注册成功，而非被/v1/:id吞掉 - 如果真需要泛匹配（如 /v1/health），把它放在对应 Group 内部，而不是 engine 根层
中间件里读取版本号别只信 URL 路径
单纯靠 c.Request.URL.Path 判断版本有风险：前端可能伪造路径，或反向代理重写了 path。更健壮的方式是结合请求头（如 X-API-Version）或 JWT payload 中的 version 字段。
但注意：一旦引入多来源版本标识，就必须定义优先级。推荐顺序是「JWT payload > 请求头 > URL 路径」，并在日志中记录实际采用的版本源，方便排查灰度问题。
- JWT 中带 version 是最可信的，因为服务端签发、客户端无法篡改
- 若用
X-API-Version: v2，需在中间件开头就校验格式（如正则^v\d+$），防止传入v2.1导致策略表查不到 - URL 路径只作为 fallback，且必须和 Group 前缀一致，否则说明路由注册本身就有问题
真正的难点不在写中间件，而在确保所有版本 Group 的挂载顺序、路径前缀、中间件作用域三者严格对齐；稍有错位，权限就会静默失效或过度拦截，而且很难通过单元测试覆盖这种组合逻辑。
