jwt.ParseWithClaims 后必须手动检查 token.Valid，因它仅做语法和签名验证，不自动校验 exp/nbf/iat；需同时满足 err == nil && token.Valid 才视为通过，且须显式启用时间校验选项、白名单放行 OPTIONS/健康路径、透传用户信息、确保系统时间同步。
jwt.ParseWithClaims 后必须手动检查 token.Valid
Go 的 jwt.ParseWithClaims 只做语法解析和签名验证，不自动校验 exp、nbf、iat 等时间字段。哪怕 token 已过期，只要签名正确，它仍会返回一个 *jwt.Token 对象，且 token.Valid 为 false——但这个字段你得自己读、自己判断。
常见错误是写完 token, err := jwt.ParseWithClaims(...) 就直接用 token.Claims，完全忽略 err == nil && token.Valid 这个双重条件。
- 正确写法：只有
err == nil && token.Valid才认为校验通过 - v4/v5 版本默认关闭时间校验；若要用
jwt.WithExpirationRequired()或jwt.WithLeeway(5 * time.Second)，必须显式传入选项 - 自定义 claims 结构体时，确保字段类型匹配（如
exp int64），否则解析失败会导致token.Valid == false，但错误被静默吞掉
OPTIONS 请求和健康检查路径必须白名单放行
网关中间件若对所有路径一视同仁地校验 JWT，会直接阻断预检请求（OPTIONS）和运维必需路径（如 /health、/metrics、/swagger/*），导致 CORS 失败或监控失联。
放行逻辑不能靠“跳过中间件”，而应在校验前明确判断路径是否在白名单中：
- 白名单建议硬编码为 slice：
[]string{"/login", "/register", "/health", "/metrics", "/actuator/health"} - 对
OPTIONS请求，校验中间件应直接c.Next()，但不能省略设置响应头（如Access-Control-Allow-Origin） - 别用模糊匹配（如
strings.HasPrefix(path, "/static/")）替代配置化白名单，后期难维护
校验后必须透传用户信息给下游服务
网关做完 JWT 解析，只是拦住了非法请求；下游服务仍需知道“谁来了”。如果只丢弃 token、不传递解析结果，每个微服务还得重复 parse 和校验——既违背网关集中鉴权的初衷，又引入安全不一致风险。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
推荐做法是在转发前把关键字段注入 HTTP Header：
- 用
c.Request().Header.Set("X-User-ID", userID)、X-User-Roles、X-Auth-Scopes等透传（避免覆盖原始Authorization） - 下游服务应只信任这些
X-前缀头，且网关需确保它们无法被客户端伪造（例如：不在 public API 中回显） - 若使用 gRPC 或内部通信，建议改用 metadata 透传，而非复用 HTTP header
系统时间偏差会让 exp 校验不可靠
JWT 的 exp 字段依赖本地系统时间。微服务节点若未同步 NTP，哪怕偏差 3 秒，就可能让刚签发的 token 被判为已过期，或让已过期的 token 意外通过。
这不是代码 bug，而是基础设施问题：
- 所有网关和下游服务节点必须配置 NTP 客户端（如
chrony或systemd-timesyncd），指向同一可信时间源 - 上线前运行
timedatectl status检查偏移量，超过 ±1s 必须告警 -
jwt.WithLeeway是兜底手段，不能替代 NTP；生产环境禁止用time.Now().Unix()直接算 exp，改用time.Now().Add(duration).Unix()
时间同步和 token.Valid 判断这两件事，最容易在压测或上线后突然暴露——前者藏在 infra 层，后者藏在 if 条件里，都不起眼，但一出问题就是大面积 401。
