Gin中JWT认证核心是三步:登录签发token、中间件解析验证、错误返回明确状态码;需注意claims嵌入RegisteredClaims、切Bearer前缀、密钥统一、时间校准及认证与授权分离。

直接用 github.com/golang-jwt/jwt/v5 做 Gin 的 JWT 认证,核心就三件事:登录时签发 token、中间件里解析验证、出错时明确返回对应状态码。别被“无状态”“签名算法”这些词绕晕,实际写起来就几十行代码,关键在怎么避开常见坑。
登录接口怎么生成合法 token
生成 token 不是拼字符串,得用 jwt.NewWithClaims 显式构造,且必须包含标准声明(比如 exp),否则后续解析会失败或被当成过期。
-
exp字段必须是int64类型的 Unix 时间戳(不是秒数字符串),推荐用time.Now().Add(...).Unix() - 密钥
jwtKey必须是全局唯一 byte slice,不能写成字符串字面量再转 —— Go 里[]byte("abc")和[]byte("abc")是两个不同底层数组 - 自定义 claims 结构体要嵌入
jwt.RegisteredClaims,否则ParseWithClaims无法识别过期、签发时间等字段 - 别把用户密码、敏感字段塞进 payload,JWT 是 Base64 编码,不是加密 —— 只放必要 ID、角色、过期时间即可
JWT 中间件怎么正确提取和校验 token
前端传来的 token 通常带 Bearer 前缀,中间件必须手动切掉,否则 jwt.Parse 会报 token contains an invalid number of segments。
- 用
c.GetHeader("Authorization")获取头,再用strings.TrimSpace(strings.TrimPrefix(authHeader, "Bearer "))提纯 - 校验失败时必须调用
c.Abort()阻断后续执行,否则即使 token 无效,handler 还会继续跑 - 解析成功后,把用户信息存到
c.Set("user_id", claims.UserId),让下游 handler 能安全取用,别每次再 parse 一遍 - 不要在中间件里做数据库查用户 —— JWT 本身已含身份信息,查库是授权环节的事,混在一起会导致性能瓶颈
为什么 token 总是报 “invalid or expired”
这个错误最常出现在三个地方:时间偏差、密钥不一致、token 被篡改但没被发现。
- 服务端系统时间不准(比如 Docker 容器没同步宿主机时间),
exp或iat校验直接失败 —— 用date命令确认时间是否误差超过 5 秒 - 签发用的密钥和验证用的密钥不一致,尤其是本地开发用
"dev_key",上线却忘了换环境变量里的JWT_SECRET - 前端 localStorage 存的 token 被手动修改过(哪怕只改一个字符),签名失效,
token.Valid就是 false - 用
HS256算法时,密钥长度太短(比如少于 32 字节)可能被某些 jwt 库拒绝,建议至少 32 字节随机字符串
如何让错误响应对前端友好
JWT 校验失败时,别统一返回 401 + {"error": "Unauthorized"},前端没法区分是过期、无效还是缺失。
- 缺失
Authorization头 → 401 +{"code": "MISSING_TOKEN"} - token 解析失败(格式错误)→ 400 +
{"code": "INVALID_TOKEN_FORMAT"} - 签名无效或密钥错 → 401 +
{"code": "INVALID_SIGNATURE"} - 过期 → 401 +
{"code": "TOKEN_EXPIRED"}(方便前端自动刷新) - 所有错误都加
c.Abort(),避免下游 handler 误读空用户数据
真正容易被忽略的是:JWT 中间件只管认证,它不决定“这个用户能不能访问 /admin/delete”,那是 RBAC 授权中间件该干的事 —— 把两者职责混在一起,后期加审计日志、动态权限、租户隔离时,你会回来重写三遍中间件。











