token校验必须在gin中间件中本地完成：解析authorization头中的jwt，验证签名、过期及claims，失败即返回401；校验通过后将user_claims注入context供下游使用，禁用远程校验、头透传和硬编码密钥。
Token校验必须在中间件中完成，且不能依赖下游服务
网关层做Token校验的核心逻辑是：收到请求后立即验证 Authorization 头里的 JWT 是否合法、未过期、签名校验通过。一旦失败，直接返回 401 Unauthorized，绝不转发到下游服务。Gin 的中间件机制天然适合这个场景——用 gin.HandlerFunc 拦截所有路由，提前处理鉴权。
常见错误是把校验逻辑写在控制器里，或者调用下游的 /auth/validate 接口做远程校验，这会放大延迟、引入单点故障、破坏网关的“前置防护”定位。
- 校验必须本地完成：用
github.com/golang-jwt/jwt/v5解析并验证签名和 claims，密钥或公钥应从配置加载，不硬编码 - 跳过校验路径需显式声明：如
/health、/login等，用 map 或正则预定义白名单，避免漏放行或误拦截 - 注意时钟漂移：
jwt.WithValidator中要设置jwt.WithLeeway(5 * time.Second)，否则 NTP 不同步时容易报token is expired
解析后的用户信息必须注入上下文，而非全局变量或 HTTP 头透传
校验通过后，需要把 user_id、role、scopes 等字段安全地传递给下游服务。最稳妥的方式是将解析出的 jwt.MapClaims 或自定义结构体塞进 Gin 的 c.Request.Context()，再通过 c.Set() 或 c.Copy() 保证协程安全。
绝对不要用 c.Request.Header.Set("X-User-ID", ...) 向下游透传——这既不安全（头可被伪造），也违背网关职责（下游应信任网关已鉴权，而非自己再解析一遍 Token）。
- 推荐做法：
c.Set("user_claims", claims)，后续 handler 中用c.MustGet("user_claims").(jwt.MapClaims)取值 - 若需透传给下游，应由网关重写为可信头，例如
X-Auth-User-ID，且值来自已校验的 claims，不取原始请求头 - 避免在中间件里修改
c.Request.URL或c.Request.Header后忘记 deep copy，导致并发 panic
公钥轮换时必须支持多 key 并行校验，且不重启服务
生产环境 JWT 密钥必然轮换。如果只维护一个 jwt.SigningKey，新旧 Token 切换期间会出现部分请求失败。正确做法是维护一个 key set（比如 map[string]*rsa.PublicKey），按 kid 字段动态选择校验密钥。
Gin 中间件本身无状态，但 key set 需全局共享且线程安全。别用全局变量加锁读写，改用 sync.RWMutex 包裹 map，或直接用 atomic.Value 存储不可变 key set 结构。
- JWT 解析时启用
jwt.WithValidMethods([]string{jwt.SigningMethodRS256.Alg()})，防止算法混淆攻击 - key set 加载失败不能 panic，应 fallback 到旧 key 并打 warning 日志；新 key 加载成功后，旧 key 至少保留 24 小时
- 测试时用
curl -H "Authorization: Bearer xxx" http://localhost:8080/api/v1/user验证不同 kid 的 Token 是否都能过
错误响应格式要统一，且不泄露敏感信息
Token 校验失败时，Gin 中间件应统一返回 JSON 错误体，字段固定为 code、message，HTTP 状态码严格对应错误类型：400 Bad Request（格式错误）、401 Unauthorized（签名无效/过期）、403 Forbidden（scope 不足）。绝不能返回 500 Internal Server Error 或堆栈信息。
尤其注意：不要把 jwt.ValidationError 的 Error() string 直接返回给客户端——里面可能含密钥长度、算法名等调试信息。
- 用 switch 判断
err.(jwt.ValidationError).Errors位掩码，映射成业务友好的 message，例如token expired→"登录已过期，请重新登录" - 日志中记录完整 error 和原始 token（前 10 字符 + ...），但响应体里 token 必须脱敏
- 对高频失败 IP 做简单限流（如
golang.org/x/time/rate），防爆破攻击
跨服务 Token 校验真正难的不是解析 JWT，而是密钥生命周期管理、上下文安全传递、错误语义收敛这三个点。多数线上问题都出在 key 轮换没灰度、claims 注入被 goroutine 覆盖、或 401 响应体格式不一致导致下游解析失败。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
