SpringBoot集成JWT实现Token认证与自动刷新

传统的会话管理机制（Session）在分布式环境下常常面临共享难题，而JWT（JSON Web Token）凭借其无状态特性，已成为当前主流认证方案。服务端无需维护会话状态，用户身份信息直接编码在Token中，既简化了系统架构，也降低了存储开销。

一、JWT 结构

JWT的结构非常清晰，由三部分组成：header（头部）、payload（载荷）和signature（签名），分别对应加密算法、用户数据以及防篡改签名。其具体格式为：header.payload.signature。

二、JWT 工具类

首先，需要一个工具类来封装Token的生成与解析逻辑。以下是一个典型实现，代码通过配置项控制密钥和过期时间，默认密钥为mySecretKey，过期时间为24小时。生成Token时，将用户ID和用户名作为载荷，同时设置签发时间与过期时间；解析时同样基于密钥进行校验。

@Component
public class JwtUtil {

    @Value("${jwt.secret:mySecretKey}")
    private String secret;

    @Value("${jwt.expire:86400000}")
    private long expire;  // 默认24小时

    public String generateToken(Long userId, String username) {
        Date now = new Date();
        return Jwts.builder()
            .setSubject(userId.toString())
            .claim("username", username)
            .setIssuedAt(now)
            .setExpiration(new Date(now.getTime() + expire))
            .signWith(SignatureAlgorithm.HS256, secret)
            .compact();
    }

    public Claims parseToken(String token) {
        return Jwts.parser()
            .setSigningKey(secret)
            .parseClaimsJws(token)
            .getBody();
    }

    public boolean validateToken(String token) {
        try {
            parseToken(token);
            return true;
        } catch (Exception e) {
            return false;
        }
    }
}

三、登录接口

接下来实现一个登录接口，返回包含Token的响应。这里以用户名密码校验为例，验证通过后生成accessToken和refreshToken，同时返回过期时间，便于前端控制刷新时机。

@RestController
@RequestMapping("/auth")
public class AuthController {

    @Autowired
    private JwtUtil jwtUtil;

    @PostMapping("/login")
    public ResultVO> login(
            @RequestParam String username,
            @RequestParam String password) {
        // 校验用户名密码
        if (!"admin".equals(username) || !"123456".equals(password)) {
            return ResultVO.error(401, "用户名或密码错误");
        }

        // 生成 Token
        String accessToken = jwtUtil.generateToken(1001L, username);
        String refreshToken = jwtUtil.generateRefreshToken(1001L);

        Map result = new HashMap<>();
        result.put("accessToken", accessToken);
        result.put("refreshToken", refreshToken);
        result.put("expiresIn", 86400);

        return ResultVO.success(result);
    }
}

四、Token 刷新

当accessToken过期后，客户端可通过refreshToken换取新的accessToken。刷新接口会先校验refreshToken的有效性，若合法则解析出用户信息，再生成新的Token对返回。

@PostMapping("/refresh")
public ResultVO> refresh(
        @RequestParam String refreshToken) {
    if (!jwtUtil.validateToken(refreshToken)) {
        return ResultVO.error(401, "RefreshToken 无效");
    }

    Claims claims = jwtUtil.parseToken(refreshToken);
    Long userId = Long.parseLong(claims.getSubject());
    String username = claims.get("username", String.class);

    String newAccessToken = jwtUtil.generateToken(userId, username);
    String newRefreshToken = jwtUtil.generateRefreshToken(userId);

    return ResultVO.success(Map.of(
        "accessToken", newAccessToken,
        "refreshToken", newRefreshToken
    ));
}

五、拦截器校验

接下来需要配置一个拦截器，在请求到达业务接口前完成Token校验。拦截器从请求头中提取Authorization字段，校验Bearer Token的有效性，并将解析出的用户信息存入请求上下文，方便后续业务逻辑使用。

@Component
public class JwtInterceptor implements HandlerInterceptor {

    @Autowired
    private JwtUtil jwtUtil;

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        String token = request.getHeader("Authorization");
        if (token == null || !token.startsWith("Bearer ")) {
            throw new BusinessException(401, "未登录");
        }

        token = token.substring(7);
        if (!jwtUtil.validateToken(token)) {
            throw new BusinessException(401, "Token 已过期");
        }

        // 将用户信息存入请求上下文
        Claims claims = jwtUtil.parseToken(token);
        request.setAttribute("userId", claims.getSubject());
        request.setAttribute("username", claims.get("username"));

        return true;
    }
}

六、前端调用

前端部分并不复杂，登录后保存Token，后续请求中携带即可。当accessToken过期时，利用refreshToken调用刷新接口获取新的Token，保证用户无感续期。

// 登录
const resp = await fetch('/auth/login', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({username: 'admin', password: '123456'})
});
const { accessToken, refreshToken } = await resp.json();

// 后续请求携带 Token
fetch('/api/user', {
    headers: {'Authorization': 'Bearer ' + accessToken}
});

// Token 过期时用 refreshToken 刷新
async function refreshAccessToken() {
    const resp = await fetch('/auth/refresh', {
        method: 'POST',
        body: new URLSearchParams({refreshToken})
    });
    const data = await resp.json();
    accessToken = data.accessToken;
}

七、安全注意事项

最后，有几个安全要点需要特别注意。第一，JWT载荷中绝对不要存放敏感信息，例如密码。第二，密钥不要硬编码在代码里，应通过配置中心或环境变量管理。第三，accessToken有效期要短，通常设为15-30分钟，而refreshToken可以设置更长一些，比如7天，专门用于刷新accessToken。

总结

总结一下，Session和JWT的核心区别在于有无状态。Session需要服务端存储，在分布式环境下共享困难；JWT无状态，Token本身携带用户信息，天然适合分布式架构。但JWT有一个天生短板：签发后无法主动失效。解决思路就是采用短时效的accessToken配合refreshToken刷新机制，在安全性与用户体验之间取得平衡。