拦截器与 JWT 联合使用详解

1. 核心概念1.1 什么是 JWTJWT 是一个开放标准RFC 7519用于在各方之间以 JSON 对象的形式安全地传输信息。该信息可以被验证和信任因为它是数字签名的。JWT 结构Header头部包含令牌类型JWT和签名算法如 HS256、RS256。Payload负载包含声明claims如用户 ID、用户名、过期时间等。Signature签名对前两部分进行签名防止数据被篡改。典型场景用户登录成功后服务器生成一个 JWT 返回给客户端。客户端在后续请求的Authorization头中携带该令牌服务器验证令牌的合法性。1.2 什么是拦截器在 Spring MVC 中拦截器HandlerInterceptor用于在请求处理前后执行通用逻辑如日志记录权限校验请求参数预处理拦截器与 Servlet 的Filter类似但更贴近 Spring MVC 的 Handler 执行流程。2. 联合使用的工作流程用户登录客户端发送用户名/密码服务器验证通过后生成 JWT 并返回。客户端存储 JWT通常存储在localStorage或HttpOnly Cookie中。携带 JWT 请求客户端在后续请求的Authorization头中添加Bearer JWT。拦截器拦截请求对于需要认证的接口拦截器从请求头中提取 JWT验证其有效性。验证通过将用户信息如用户 ID存入ThreadLocal或请求属性供后续业务逻辑使用。验证失败返回 401 Unauthorized 或 403 Forbidden。3. 代码实现Spring Boot 示例3.1 引入依赖xmldependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.11.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.11.5/version scoperuntime/scope /dependency3.2 JWT 工具类提供生成、解析、验证 JWT 的方法。javaimport io.jsonwebtoken.*; import io.jsonwebtoken.security.Keys; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import java.security.Key; import java.util.Date; Component public class JwtUtil { Value(${jwt.secret}) private String secret; Value(${jwt.expiration}) private Long expiration; private Key getSigningKey() { return Keys.hmacShaKeyFor(secret.getBytes()); } // 生成 JWT public String generateToken(String username) { Date now new Date(); Date expiryDate new Date(now.getTime() expiration); return Jwts.builder() .setSubject(username) .setIssuedAt(now) .setExpiration(expiryDate) .signWith(getSigningKey(), SignatureAlgorithm.HS256) .compact(); } // 从 JWT 中获取用户名 public String getUsernameFromToken(String token) { return Jwts.parserBuilder() .setSigningKey(getSigningKey()) .build() .parseClaimsJws(token) .getBody() .getSubject(); } // 验证 JWT 是否有效 public boolean validateToken(String token) { try { Jwts.parserBuilder().setSigningKey(getSigningKey()).build().parseClaimsJws(token); return true; } catch (JwtException | IllegalArgumentException e) { // 可以根据异常类型返回更具体的错误信息 return false; } } }3.3 自定义拦截器实现HandlerInterceptor在preHandle方法中完成 JWT 的提取和验证。javaimport org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import org.springframework.web.servlet.HandlerInterceptor; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; Component public class JwtInterceptor implements HandlerInterceptor { Autowired private JwtUtil jwtUtil; Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 从请求头中获取 Authorization 字段 String authHeader request.getHeader(Authorization); if (authHeader ! null authHeader.startsWith(Bearer )) { String token authHeader.substring(7); if (jwtUtil.validateToken(token)) { // 将用户信息存入请求属性供后续 Controller 使用 String username jwtUtil.getUsernameFromToken(token); request.setAttribute(username, username); return true; } } // 验证失败返回 401 状态码 response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); response.getWriter().write(Unauthorized: Invalid or missing token); return false; } }3.4 配置拦截器路径通过实现WebMvcConfigurer来注册拦截器并指定需要拦截的路径。javaimport org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; Configuration public class WebConfig implements WebMvcConfigurer { Autowired private JwtInterceptor jwtInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(jwtInterceptor) .addPathPatterns(/api/**) // 拦截所有 /api/** 路径 .excludePathPatterns(/api/login, /api/register); // 排除登录注册接口 } }3.5 Controller 中使用用户信息在 Controller 中可以通过RequestAttribute获取拦截器中存入的用户信息。javaRestController RequestMapping(/api/user) public class UserController { GetMapping(/info) public String getUserInfo(RequestAttribute(username) String username) { return Current user: username; } }4. 常见问题与解决方案4.1 如何区分“未登录”和“令牌无效”拦截器可以返回不同的 HTTP 状态码401 Unauthorized未提供令牌或令牌格式错误。403 Forbidden令牌有效但权限不足需结合权限校验。javaif (authHeader null || !authHeader.startsWith(Bearer )) { response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); response.getWriter().write(Missing token); return false; } if (!jwtUtil.validateToken(token)) { response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); response.getWriter().write(Invalid token); return false; }4.2 如何支持 token 刷新方案一在 token 过期前客户端主动请求刷新接口获取新 token。方案二在拦截器中检测到 token 即将过期时通过响应头返回新 token如X-New-Token客户端更新存储。4.3 如何将用户信息传递给 Service 层推荐使用ThreadLocal或RequestContextHolder在任意层获取用户信息避免在方法参数中层层传递。javapublic class UserContext { private static final ThreadLocalString currentUser new ThreadLocal(); public static void setCurrentUser(String username) { currentUser.set(username); } public static String getCurrentUser() { return currentUser.get(); } public static void clear() { currentUser.remove(); } }在拦截器中使用javaUserContext.setCurrentUser(username);在拦截器的afterCompletion中清理javaOverride public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { UserContext.clear(); }4.4 如何应对集群/分布式环境JWT 本身是无状态的只要各节点使用相同的 secret 即可验证。如需实现 token 黑名单如注销可使用 Redis 存储已注销的 token拦截器校验时额外检查黑名单。4.5 拦截器 vs Filter 如何选择Filter基于 Servlet 规范适用于所有请求包括静态资源更底层。InterceptorSpring 提供可访问 Handler 信息更便于与 Spring MVC 集成。对于 JWT 校验两者均可。但 Interceptor 可以更方便地获取HandlerMethod信息便于实现细粒度的权限控制如基于注解的权限校验。5. 进阶结合注解实现细粒度权限控制5.1 自定义注解javaTarget(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface RequireRole { String[] value(); }5.2 在拦截器中解析注解在preHandle中获取HandlerMethod检查是否标注了RequireRole注解并根据用户角色决定是否放行。javaOverride public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 只对 HandlerMethod 类型进行处理 if (!(handler instanceof HandlerMethod)) { return true; } HandlerMethod handlerMethod (HandlerMethod) handler; RequireRole requireRole handlerMethod.getMethodAnnotation(RequireRole.class); if (requireRole null) { return true; // 没有权限注解直接放行 } // 从 token 中获取用户角色假设 JWT 中包含 roles 字段 String token extractToken(request); if (token null || !jwtUtil.validateToken(token)) { response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); return false; } ListString roles jwtUtil.getRolesFromToken(token); boolean hasRole Arrays.stream(requireRole.value()).anyMatch(roles::contains); if (!hasRole) { response.setStatus(HttpServletResponse.SC_FORBIDDEN); return false; } return true; }5.3 在 Controller 中使用javaGetMapping(/admin) RequireRole(ADMIN) public String adminOnly() { return Admin content; }6. 总结JWT提供了一种无状态的认证方式适合分布式系统。拦截器是 Spring MVC 中实现请求拦截的利器与 JWT 结合可以统一处理认证和授权。关键点包括token 的生成与验证、拦截器的路径配置、用户信息的传递以及异常处理。进阶用法包括结合注解实现细粒度权限控制、支持 token 刷新、分布式环境下的黑名单机制等。通过合理设计拦截器与 JWT 的联合使用能够为应用提供简洁、高效、可扩展的认证授权解决方案。