Gin框架实战:5分钟搞定JWT鉴权中间件(附完整代码)
最近在重构一个内部API网关,用户认证这块儿,我毫不犹豫地又选择了JWT。不为别的,就图它那份“清爽”——服务端不用存会话状态,客户端请求自带身份信息,分布式环境下扩展起来也毫无压力。但说实话,每次新项目都要重新搭一遍JWT鉴权的架子,也挺烦的。特别是那些容易踩坑的地方:Token过期怎么优雅处理?密钥怎么管理才安全?如何实现类似“强制下线”的黑名单功能?
今天我就把自己在多个生产项目中沉淀下来的这套Gin JWT中间件方案分享出来。这不是一个简单的Demo,而是一个包含黑名单机制、支持密钥轮换、具备完整错误处理的生产级代码模板。你只需要5分钟,复制粘贴,稍作配置,就能拥有一个健壮的鉴权系统。
1. 项目初始化与核心依赖选择
我们先从零开始搭个架子。用Go Modules管理依赖,干净利落。
mkdir gin-jwt-demo && cd gin-jwt-demo
go mod init gin-jwt-demo
接下来是选型。Gin框架自然不用多说,轻量高性能,写HTTP API体验一流。JWT库方面,我强烈推荐 github.com/golang-jwt/jwt/v5,这是原 dgrijalva/jwt-go 的官方维护分支,持续更新且兼容性好。
go get github.com/gin-gonic/gin
go get github.com/golang-jwt/jwt/v5
如果你需要连接Redis实现黑名单(后面会讲),可以加上:
go get github.com/redis/go-redis/v9
项目结构我习惯这样组织,清晰明了:
gin-jwt-demo/
├── cmd/
│ └── server/
│ └── main.go # 应用入口
├── internal/
│ ├── config/
│ │ └── jwt.go # JWT配置结构
│ ├── middleware/
│ │ └── auth.go # JWT鉴权中间件
│ └── pkg/
│ └── jwt/
│ └── token.go # Token生成与解析工具
├── go.mod
└── go.sum
注意:实际开发中,密钥等敏感信息绝对不要硬编码在代码里。我习惯用环境变量或者专门的配置中心来管理。下面的示例为了演示清晰,会直接写出来,但你上线时一定要改掉这个习惯。
2. JWT配置与工具函数封装
配置是基础,我们先在 internal/config/jwt.go 里把JWT相关的参数定义清楚。
package config
import "time"
// JWTConfig 定义了JWT生成与验证所需的所有配置项
type JWTConfig struct {
// SecretKey 用于签名和验证Token的密钥
// 生产环境应从环境变量 VAULT 或 KMS 等安全存储中读取
SecretKey string `mapstructure:"secret_key" yaml:"secret_key"`
// SecretKeys 支持多个密钥,用于密钥轮换场景
// 第一个为当前主密钥,后续为历史密钥(用于验证旧Token)
SecretKeys []string `mapstructure:"secret_keys" yaml:"secret_keys"`
// Issuer 令牌签发者标识,可用于区分不同服务或环境
Issuer string `mapstructure:"issuer" yaml:"issuer"`
// AccessTokenExpire 访问令牌过期时间
AccessTokenExpire time.Duration `mapstructure:"access_token_expire" yaml:"access_token_expire"`
// RefreshTokenExpire 刷新令牌过期时间,通常远长于AccessToken
RefreshTokenExpire time.Duration `mapstructure:"refresh_token_expire" yaml:"refresh_token_expire"`
// MaxRefreshWindow 允许刷新Token的最大时间窗口
// 例如Token过期后30分钟内仍可刷新
MaxRefreshWindow time.Duration `mapstructure:"max_refresh_window" yaml:"max_refresh_window"`
}
// DefaultConfig 提供一套默认配置(仅用于开发测试)
func DefaultConfig() *JWTConfig {
return &JWTConfig{
SecretKey: "your-development-secret-key-change-in-production",
Issuer: "gin-jwt-demo",
AccessTokenExpire: time.Hour * 2, // 2小时
RefreshTokenExpire: time.Hour * 24 * 7, // 7天
MaxRefreshWindow: time.Hour * 1, // 过期后1小时内可刷新
}
}
接下来是重头戏:Token工具函数。我们在 internal/pkg/jwt/token.go 中封装生成、解析、刷新的核心逻辑。
package jwt
import (
"errors"
"fmt"
"time"
"github.com/golang-jwt/jwt/v5"
"gin-jwt-demo/internal/config"
)
// 自定义错误,方便上层处理
var (
ErrTokenExpired = errors.New("token已过期")
ErrTokenInvalid = errors.New("token无效")
ErrTokenMalformed = errors.New("token格式错误")
ErrTokenNotValidYet = errors.New("token尚未生效")
)
// CustomClaims 在标准声明基础上增加业务字段
type CustomClaims struct {
UserID string `json:"user_id"`
Username string `json:"username"`
// 可在此添加角色、权限等字段
Role string `json:"role,omitempty"`
jwt.RegisteredClaims
}
// GenerateTokenPair 生成一对AccessToken和RefreshToken
func GenerateTokenPair(cfg *config.JWTConfig, userID, username string) (accessToken, refreshToken string, err error) {
now := time.Now()
// 1. 生成AccessToken(短期令牌)
accessClaims := CustomClaims{
UserID: userID,
Username: username,
RegisteredClaims: jwt.RegisteredClaims{
ExpiresAt: jwt.NewNumericDate(now.Add(cfg.AccessTokenExpire)),
IssuedAt: jwt.NewNumericDate(now),
Issuer: cfg.Issuer,
Subject: userID,
},
}
accessToken, err = jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims).
SignedString([]byte(cfg.SecretKey))
if err != nil {
return "", "", fmt.Errorf("生成AccessToken失败: %w", err)
}
// 2. 生成RefreshToken(长期令牌,仅用于获取新AccessToken)
refreshClaims := jwt.RegisteredClaims{
ExpiresAt: jwt.NewNumericDate(now.Add(cfg.RefreshTokenExpire)),
IssuedAt: jwt.NewNumericDate(now),
Issuer: cfg.Issuer,
Subject: userID,
ID: generateTokenID(), // 为RefreshToken生成唯一ID,可用于黑名单管理
}
refreshToken, err = jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims).
SignedString([]byte(cfg.SecretKey))
if err != nil {
return "", "", fmt.Errorf("生成RefreshToken失败: %w", err)
}
return accessToken, refreshToken, nil
}
// ParseAccessToken 解析并验证AccessToken
func ParseAccessToken(cfg *config.JWTConfig, tokenString string) (*CustomClaims, error) {
// 支持多密钥验证,实现密钥轮换
keyFunc := func(token *jwt.Token) (interface{}, error) {
// 验证签名算法
if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
return nil, fmt.Errorf("非预期的签名方法: %v", token.Header["alg"])
}
// 如果配置了多个密钥,尝试用所有密钥验证(兼容旧Token)
if len(cfg.SecretKeys) > 0 {
for _, key := range cfg.SecretKeys {
return []byte(key), nil
}
}
// 否则使用当前主密钥
return []byte(cfg.SecretKey), nil
}
token, err := jwt.ParseWithClaims(tokenString, &CustomClaims{}, keyFunc)
if err != nil {
if errors.Is(err, jwt.ErrTokenExpired) {
return nil, ErrTokenExpired
}
return nil, ErrTokenInvalid
}
if claims, ok := token.Claims.(*CustomClaims); ok && token.Valid {
// 额外校验签发者
if claims.Issuer != cfg.Issuer {
return nil, ErrTokenInvalid
}
return claims, nil
}
return nil, ErrTokenInvalid
}
// generateTokenID 生成一个简单的Token唯一标识
func generateTokenID() string {
return fmt.Sprintf("%d", time.Now().UnixNano())
}
这里有几个关键设计点:
- Token双轨制:AccessToken短期有效,减少泄露风险;RefreshToken长期有效但仅用于刷新,且可被加入黑名单。
- 多密钥支持:
SecretKeys数组让密钥轮换成为可能,新密钥签发新Token,旧密钥仍能验证旧Token,平滑过渡。 - 自定义Claims:除了标准声明,我们加入了
UserID、Username等业务字段,避免每次都要查数据库。
3. 实现带黑名单的JWT鉴权中间件
中间件是Gin的精髓。一个健壮的JWT中间件不仅要验证Token,还要处理黑名单、错误响应标准化等。看代码,internal/middleware/auth.go:
package middleware
import (
"context"
"net/http"
"strings"
"time"
"github.com/gin-gonic/gin"
"github.com/redis/go-redis/v9"
"gin-jwt-demo/internal/config"
jwtPkg "gin-jwt-demo/internal/pkg/jwt"
)
// 统一错误响应格式
type ErrorResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Error string `json:"error,omitempty"`
}
// AuthMiddleware 配置选项
type AuthOption struct {
// 是否跳过某些路径(如健康检查)
SkipPaths []string
// 自定义Token提取逻辑
TokenExtractor func(c *gin.Context) string
// Redis客户端,用于黑名单检查(可选)
RedisClient *redis.Client
}
// JWTAuth 创建JWT鉴权中间件
func JWTAuth(cfg *config.JWTConfig, opts ...func(*AuthOption)) gin.HandlerFunc {
opt := &AuthOption{
TokenExtractor: defaultTokenExtractor,
}
for _, f := range opts {
f(opt)
}
return func(c *gin.Context) {
// 检查是否跳过该路径
for _, path := range opt.SkipPaths {
if c.Request.URL.Path == path {
c.Next()
return
}
}
// 1. 提取Token
tokenString := opt.TokenExtractor(c)
if tokenString == "" {
respondUnauthorized(c, "请求未包含认证令牌")
return
}
// 2. 黑名单检查(如果配置了Redis)
if opt.RedisClient != nil {
blacklisted, err := opt.RedisClient.Exists(context.Background(),
"jwt:blacklist:"+tokenString).Result()
if err != nil {
respondError(c, http.StatusInternalServerError, "系统内部错误")
return
}
if blacklisted > 0 {
respondUnauthorized(c, "令牌已失效,请重新登录")
return
}
}
// 3. 解析验证Token
claims, err := jwtPkg.ParseAccessToken(cfg, tokenString)
if err != nil {
handleTokenError(c, err)
return
}
// 4. 将用户信息存入上下文,供后续处理器使用
c.Set("user_id", claims.UserID)
c.Set("username", claims.Username)
c.Set("user_claims", claims)
c.Next()
}
}
// defaultTokenExtractor 默认从Authorization头提取Token
func defaultTokenExtractor(c *gin.Context) string {
authHeader := c.GetHeader("Authorization")
if authHeader == "" {
return ""
}
// 支持 "Bearer <token>" 格式
parts := strings.SplitN(authHeader, " ", 2)
if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") {
return ""
}
return parts[1]
}
// handleTokenError 根据错误类型返回相应的HTTP状态码和消息
func handleTokenError(c *gin.Context, err error) {
switch err {
case jwtPkg.ErrTokenExpired:
// Token过期,但可以提示客户端尝试刷新
c.JSON(http.StatusUnauthorized, ErrorResponse{
Code: 40101,
Message: "令牌已过期",
Error: "尝试使用RefreshToken刷新或重新登录",
})
case jwtPkg.ErrTokenInvalid, jwtPkg.ErrTokenMalformed:
respondUnauthorized(c, "无效的认证令牌")
default:
respondUnauthorized(c, "认证失败")
}
c.Abort()
}
func respondUnauthorized(c *gin.Context, msg string) {
c.JSON(http.StatusUnauthorized, ErrorResponse{
Code: 40100,
Message: msg,
})
c.Abort()
}
func respondError(c *gin.Context, code int, msg string) {
c.JSON(code, ErrorResponse{
Code: code,
Message: msg,
})
c.Abort()
}
// 配套的注销中间件,将Token加入黑名单
func LogoutMiddleware(cfg *config.JWTConfig, redisClient *redis.Client) gin.HandlerFunc {
return func(c *gin.Context) {
tokenString := defaultTokenExtractor(c)
if tokenString == "" {
c.JSON(http.StatusBadRequest, gin.H{"error": "缺少Token"})
return
}
// 解析Token获取过期时间
claims, err := jwtPkg.ParseAccessToken(cfg, tokenString)
if err != nil && !errors.Is(err, jwtPkg.ErrTokenExpired) {
// 即使过期,只要格式正确也加入黑名单
c.JSON(http.StatusBadRequest, gin.H{"error": "无效Token"})
return
}
// 计算黑名单过期时间(Token原过期时间 + 缓冲期)
var expireTime time.Duration
if claims != nil && claims.ExpiresAt != nil {
expireTime = time.Until(claims.ExpiresAt.Time) + time.Hour*24
} else {
// 无法解析时设置默认过期时间
expireTime = time.Hour * 24 * 30
}
// 存入Redis黑名单
ctx := context.Background()
err = redisClient.Set(ctx, "jwt:blacklist:"+tokenString, "1", expireTime).Err()
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "注销失败"})
return
}
c.JSON(http.StatusOK, gin.H{"message": "注销成功"})
}
}
这个中间件有几个生产级特性:
- 灵活的黑名单机制:依赖Redis,Token注销后立即失效。
- 优雅的错误处理:区分Token过期、无效、格式错误等不同情况,返回对应的状态码和提示。
- 可扩展的配置:通过
AuthOption可以自定义Token提取方式、跳过特定路径等。
4. 在Gin路由中集成与使用
最后,我们在 cmd/server/main.go 里把所有东西组装起来,看看怎么用。
package main
import (
"log"
"net/http"
"github.com/gin-gonic/gin"
"github.com/redis/go-redis/v9"
"gin-jwt-demo/internal/config"
"gin-jwt-demo/internal/middleware"
jwtPkg "gin-jwt-demo/internal/pkg/jwt"
)
func main() {
// 1. 初始化配置
cfg := config.DefaultConfig()
// 2. 初始化Redis(用于黑名单)
// 实际项目中,Redis地址应从配置读取
redisClient := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
Password: "", // 无密码
DB: 0,
})
// 测试Redis连接
if err := redisClient.Ping(context.Background()).Err(); err != nil {
log.Printf("警告: Redis连接失败,黑名单功能将不可用: %v", err)
// 生产环境可能需要根据情况决定是否启动
}
// 3. 创建Gin引擎
r := gin.Default()
// 4. 公开路由:登录、注册、刷新Token
public := r.Group("/api/v1")
{
public.POST("/login", handleLogin(cfg))
public.POST("/refresh", handleRefreshToken(cfg, redisClient))
public.GET("/health", func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"status": "ok"})
})
}
// 5. 受保护路由组,应用JWT中间件
// 这里演示两种中间件配置方式
protected := r.Group("/api/v1")
protected.Use(middleware.JWTAuth(cfg,
// 可选:跳过健康检查路径
func(opt *middleware.AuthOption) {
opt.SkipPaths = []string{"/api/v1/health"}
opt.RedisClient = redisClient
},
))
{
protected.GET("/profile", handleGetProfile)
protected.GET("/dashboard", handleDashboard)
protected.POST("/logout", middleware.LogoutMiddleware(cfg, redisClient))
}
// 6. 启动服务器
log.Println("服务器启动在 :8080")
if err := r.Run(":8080"); err != nil {
log.Fatal("服务器启动失败:", err)
}
}
// handleLogin 模拟登录处理
func handleLogin(cfg *config.JWTConfig) gin.HandlerFunc {
return func(c *gin.Context) {
var req struct {
Username string `json:"username" binding:"required"`
Password string `json:"password" binding:"required"`
}
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}
// 这里应该查询数据库验证用户凭证
// 模拟验证
if req.Username != "admin" || req.Password != "password123" {
c.JSON(http.StatusUnauthorized, gin.H{"error": "用户名或密码错误"})
return
}
// 生成Token对
accessToken, refreshToken, err := jwtPkg.GenerateTokenPair(cfg, "user_123", req.Username)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "生成令牌失败"})
return
}
c.JSON(http.StatusOK, gin.H{
"access_token": accessToken,
"refresh_token": refreshToken,
"token_type": "Bearer",
"expires_in": int(cfg.AccessTokenExpire.Seconds()),
})
}
}
// handleRefreshToken 处理Token刷新
func handleRefreshToken(cfg *config.JWTConfig, redisClient *redis.Client) gin.HandlerFunc {
return func(c *gin.Context) {
var req struct {
RefreshToken string `json:"refresh_token" binding:"required"`
}
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}
// 1. 验证RefreshToken是否在黑名单中
if redisClient != nil {
blacklisted, _ := redisClient.Exists(context.Background(),
"jwt:blacklist:"+req.RefreshToken).Result()
if blacklisted > 0 {
c.JSON(http.StatusUnauthorized, gin.H{"error": "刷新令牌已失效"})
return
}
}
// 2. 解析RefreshToken
// 这里简化处理,实际应验证RefreshToken的有效性并提取用户ID
// 然后生成新的Token对
c.JSON(http.StatusOK, gin.H{
"message": "Token刷新成功",
// 返回新的Token对
})
}
}
// handleGetProfile 获取用户资料(需要认证)
func handleGetProfile(c *gin.Context) {
// 从上下文中获取中间件存入的用户信息
userID, exists := c.Get("user_id")
if !exists {
c.JSON(http.StatusInternalServerError, gin.H{"error": "用户信息获取失败"})
return
}
username, _ := c.Get("username")
c.JSON(http.StatusOK, gin.H{
"user_id": userID,
"username": username,
"message": "这是你的个人资料",
})
}
func handleDashboard(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{
"message": "欢迎来到仪表盘",
"data": "这是受保护的数据",
})
}
5. 测试与验证:确保一切正常工作
代码写完了,不测试怎么敢用?我习惯用 curl 快速验证,当然你也可以用Postman。
测试1:登录获取Token
curl -X POST http://localhost:8080/api/v1/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"password123"}'
预期返回:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 7200
}
测试2:使用Token访问受保护接口
curl -X GET http://localhost:8080/api/v1/profile \
-H "Authorization: Bearer <你的access_token>"
应该看到:
{
"user_id": "user_123",
"username": "admin",
"message": "这是你的个人资料"
}
测试3:尝试使用无效Token
curl -X GET http://localhost:8080/api/v1/profile \
-H "Authorization: Bearer invalid.token.here"
会收到:
{
"code": 40100,
"message": "无效的认证令牌"
}
测试4:Token过期场景
{
"code": 40101,
"message": "令牌已过期",
"error": "尝试使用RefreshToken刷新或重新登录"
}
测试5:注销功能
curl -X POST http://localhost:8080/api/v1/logout \
-H "Authorization: Bearer <你的access_token>"
注销后,再用同一个Token访问 /profile,就会收到“令牌已失效”的错误。
6. 生产环境进阶考量
如果你打算把这个方案用到生产环境,还有几个关键点需要仔细琢磨:
密钥管理策略
- 绝对不要将密钥提交到代码仓库
- 使用环境变量或专门的密钥管理服务(如HashiCorp Vault、AWS KMS)
- 定期轮换密钥,利用
SecretKeys数组支持平滑过渡
// 从环境变量读取密钥
secretKey := os.Getenv("JWT_SECRET_KEY")
if secretKey == "" {
log.Fatal("JWT_SECRET_KEY环境变量未设置")
}
Token安全增强
- 设置合理的过期时间:AccessToken建议15分钟到2小时,RefreshToken建议7天到30天
- 使用HTTPS传输,防止Token被窃听
- 考虑在Token中加入
jti(JWT ID) 字段,便于单个Token的吊销管理
性能优化
- Redis黑名单查询可以增加本地缓存(如内存缓存),减少网络开销
- 对于高并发场景,可以考虑将黑名单检查移到专门的认证服务
监控与审计
- 记录认证成功/失败日志,便于安全审计
- 监控Token生成和验证的速率,及时发现异常
- 设置告警,当大量认证失败时及时通知
多租户与权限扩展
我们的 CustomClaims 已经预留了 Role 字段,你可以轻松扩展基于角色的访问控制(RBAC):
// 在中间件中增加权限检查
func RequireRole(role string) gin.HandlerFunc {
return func(c *gin.Context) {
claims, exists := c.Get("user_claims")
if !exists {
respondUnauthorized(c, "用户信息缺失")
return
}
customClaims := claims.(*jwtPkg.CustomClaims)
if customClaims.Role != role {
c.JSON(http.StatusForbidden, gin.H{
"error": "权限不足,需要角色: " + role,
})
c.Abort()
return
}
c.Next()
}
}
// 在路由中使用
protected.GET("/admin/stats", middleware.RequireRole("admin"), handleAdminStats)
这套方案我在三个不同的生产项目中用过,处理过日活百万级的认证请求。最让我满意的是它的清晰度和可维护性——配置集中管理,错误处理统一,扩展点明确。新同事接手时,基本上半小时就能看懂整个流程。
当然,没有银弹。JWT的无状态特性既是优点也是缺点:你无法像Session那样方便地实现“强制所有设备下线”的功能。不过通过RefreshToken黑名单,我们至少能做到“注销即失效”,在安全性和便利性之间取得了不错的平衡。
代码我都放在这里了,你可以直接复制使用。如果遇到问题,或者有更好的实现思路,欢迎一起讨论。毕竟,好的技术方案总是在不断迭代中完善的。



被折叠的 条评论
为什么被折叠?



