1. 项目概述与核心价值最近在重构一个老的后台管理系统用户登录认证这块儿一直用的是传统的Session-Cookie方案。随着微服务拆分和前后端分离架构的普及这套方案在扩展性和维护性上的短板越来越明显。每次新开一个服务都得考虑Session共享的问题用Redis吧确实能解决但总觉得架构上不够“清爽”。正好团队里有个新启动的SPA项目技术选型时大家一致决定用JWT来做无状态认证。我花了点时间把SpringBoot集成JWT的流程从头到尾捋了一遍踩了几个坑也总结出一些能让集成过程更顺滑的实践技巧。这篇文章我就把这次从零到一的完整过程包括背后的设计思考、具体的代码实现以及那些官方文档里不会写的“坑点”都详细记录下来。JWT全称JSON Web Token本质上是一个开放标准它定义了一种紧凑且自包含的方式用于在各方之间安全地传输信息。你可以把它想象成一张“数字身份证”。当用户首次登录成功时服务器端会签发一张包含用户身份信息如用户ID、角色的JWT令牌给客户端通常是浏览器。此后客户端在请求需要认证的接口时只需在HTTP请求头中带上这张“身份证”服务器端通过验证令牌的签名即可确认用户身份无需再去查询数据库或Session存储。这对于构建可扩展的分布式系统特别是前后端分离、移动端应用来说优势非常明显服务端彻底无状态天然支持水平扩展令牌本身携带信息减少了查库次数跨语言、跨平台支持性好。那么这个方案具体适合谁呢如果你正在开发一个新的SpringBoot项目并且采用了前后端分离的架构或者你正在将原有的单体应用向微服务架构迁移受困于状态管理亦或是你需要为移动App提供API接口那么集成JWT进行认证会是一个值得认真考虑的选择。接下来我会从设计思路、依赖选型、代码实现、安全增强到上线排查一步步带你走完整个流程。2. 整体设计与核心思路拆解在动手写代码之前理清整体设计思路至关重要。我们不能仅仅满足于“跑通”更要明白每一步选择背后的原因以及如何规避潜在的风险。2.1 为何选择JWT而非Session首先我们需要明确JWT解决的核心痛点。在传统的Session方案中用户的登录状态保存在服务端的内存或Redis中客户端仅持有一个Session ID。这种方式的弊端在于服务端是有状态的。在集群环境下你必须借助额外的中间件如Redis来实现Session共享这增加了系统的复杂度和运维成本。此外对于原生移动App或第三方API调用处理Cookie并不总是那么方便。JWT采用了一种截然不同的思路将状态信息直接编码到令牌中并附上签名以确保其不可篡改。服务端在签发令牌后就“忘记”了它后续的认证只需验证签名和令牌有效性即可。这种无状态特性使得任何一个服务实例都能独立处理认证请求极大地提升了系统的伸缩能力。对于我们的SPA项目前端Vue/React可以将获取到的JWT存储在localStorage或Cookie中并在每次请求API时自动携带流程非常清晰。2.2 JWT令牌的结构与安全考量一个JWT令牌由三部分组成以点号分隔Header.Payload.Signature。Header通常包含令牌类型typ: “JWT”和所使用的签名算法alg如HS256、RS256。Payload这是令牌的核心包含所谓的“声明”。声明分为三种预定义的注册声明如iss签发者、exp过期时间、公共声明和私有声明。我们最常用的就是私有声明用来存放用户ID、用户名、角色等信息。这里有一个非常重要的注意事项Payload部分仅仅是Base64Url编码并非加密。因此绝对禁止在Payload中存放任何敏感信息例如用户密码、银行卡号等。Signature签名部分。服务器使用Header中声明的算法一个密钥Secret对编码后的Header和Payload进行签名。这个签名用于验证消息在传输过程中未被篡改同时也是验证令牌签发方的依据。算法选择上HS256HMAC SHA-256使用一个对称密钥进行签名和验证简单高效适合单服务场景。而RS256RSA SHA-256使用非对称加密私钥用于签名公钥用于验证更适合多服务、需要分离签发和验证职责的微服务场景。在我们的初期集成中从简单出发选择HS256。2.3 集成后的核心流程集成的核心目标是构建一个完整的认证闭环流程如下登录接口用户提交用户名密码。服务端校验通过后生成JWT令牌包含用户信息、过期时间等返回给客户端。令牌存储与携带客户端如前端收到令牌后需要安全地存储起来通常放在Authorization请求头中格式为Bearer token。接口认证对于需要认证的API服务端通过一个过滤器Filter或拦截器Interceptor从请求头中提取JWT令牌并进行验证签名是否有效、是否过期等。验证通过后将用户信息存入本次请求的上下文如Spring Security的SecurityContext供后续业务逻辑使用。令牌刷新为了平衡安全性与用户体验通常会设计一个刷新令牌的机制。当访问令牌Access Token临近过期时客户端可以使用一个有效期更长的刷新令牌Refresh Token来获取新的访问令牌而无需用户重新登录。这个流程看似清晰但其中每一步都有细节需要打磨比如如何优雅地处理令牌过期、如何实现强制下线JWT的无状态特性使其无法像Session那样直接失效需要额外设计、如何防止令牌被盗用等。我们会在后续章节逐一展开。3. 依赖引入与基础配置理论清晰后我们开始动手。首先创建一个标准的SpringBoot项目这里我使用Spring Initializr选择Spring Web依赖。然后我们需要引入JWT相关的库。3.1 JJWT库的选择与引入Java领域最流行的JWT库是jjwt由Auth0维护。它API设计清晰文档完善。截至我写作时推荐使用jjwt-api、jjwt-impl、jjwt-jackson这三个组件的0.12.x及以上版本。这个版本系列重构了API更安全、更符合现代Java开发习惯。在你的pom.xml文件中添加以下依赖dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.12.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.12.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.12.5/version scoperuntime/scope /dependency注意jjwt-impl和jjwt-jackson设置为runtime作用域是因为你的代码在编译期只需要依赖jjwt-api中定义的接口。具体的实现和JSON处理在运行时提供这符合良好的依赖管理实践。3.2 核心配置参数管理我们需要将JWT相关的配置集中管理例如密钥、令牌有效期等。在application.yml或application.properties中配置jwt: secret: your-256-bit-secret-your-256-bit-secret-your-256-bit-secret # 用于HS256签名的密钥至少32字符 access-token-expire-time: 7200 # 访问令牌过期时间单位秒例如2小时7200秒 refresh-token-expire-time: 604800 # 刷新令牌过期时间单位秒例如7天604800秒 token-header: Authorization # 客户端传递令牌的请求头名称 token-prefix: Bearer # 令牌前缀通常为Bearer注意后面有个空格这里有几个关键点密钥Secret这是HS256算法的核心必须足够复杂且保密。在生产环境中绝对不要将明文密钥写在配置文件中提交到代码仓库。应该使用环境变量、配置中心或密钥管理服务来注入。示例中的your-256-bit-secret...只是一个占位符。过期时间访问令牌Access Token有效期较短用于日常API调用即使泄露危害窗口也较小。刷新令牌Refresh Token有效期较长用于获取新的访问令牌它需要被更安全地存储例如服务端可将其与用户关联并存入数据库使用时校验状态。请求头格式这是行业标准做法Authorization: Bearer your-jwt-token。注意Bearer后面有一个空格。接下来我们创建一个配置类JwtProperties来映射这些配置import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; Data Component ConfigurationProperties(prefix jwt) public class JwtProperties { private String secret; private Long accessTokenExpireTime; private Long refreshTokenExpireTime; private String tokenHeader; private String tokenPrefix; }确保你的项目已经引入了Lombok依赖以便使用Data注解自动生成getter和setter。4. JWT工具类封装签发与解析的核心有了配置我们就可以创建最核心的JWT工具类。这个类将封装令牌的生成、解析、验证等所有操作。我将其设计为Component方便在其他地方注入使用。4.1 构建JwtUtil工具类import io.jsonwebtoken.Claims; import io.jsonwebtoken.Jwts; import io.jsonwebtoken.security.Keys; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import javax.crypto.SecretKey; import java.util.Date; import java.util.HashMap; import java.util.Map; Component public class JwtUtil { Autowired private JwtProperties jwtProperties; // 生成安全的密钥对象 private SecretKey getSigningKey() { // 将配置的字符串密钥转换为jjwt需要的SecretKey对象 return Keys.hmacShaKeyFor(jwtProperties.getSecret().getBytes(StandardCharsets.UTF_8)); } /** * 生成访问令牌 * param userId 用户唯一标识 * param username 用户名 * param extraClaims 额外的声明信息如角色 * return 生成的JWT字符串 */ public String generateAccessToken(String userId, String username, MapString, Object extraClaims) { MapString, Object claims new HashMap(); claims.put(userId, userId); claims.put(username, username); if (extraClaims ! null) { claims.putAll(extraClaims); } return buildToken(claims, jwtProperties.getAccessTokenExpireTime()); } /** * 生成刷新令牌通常只包含用户ID用于换取新的访问令牌 * param userId 用户唯一标识 * return 生成的刷新令牌JWT字符串 */ public String generateRefreshToken(String userId) { MapString, Object claims new HashMap(); claims.put(userId, userId); claims.put(type, refresh); // 明确令牌类型防止误用 return buildToken(claims, jwtProperties.getRefreshTokenExpireTime()); } /** * 构建JWT令牌的通用方法 */ private String buildToken(MapString, Object claims, Long expiration) { Date now new Date(); Date expiryDate new Date(now.getTime() expiration * 1000); return Jwts.builder() .claims(claims) // 设置声明Payload .issuedAt(now) // 签发时间 (iat) .expiration(expiryDate) // 过期时间 (exp) .signWith(getSigningKey(), Jwts.SIG.HS256) // 使用HS256算法和密钥签名 .compact(); // 压缩生成最终的字符串 } /** * 从令牌中解析所有声明Claims * param token JWT令牌 * return Claims 对象 */ public Claims parseToken(String token) { return Jwts.parser() .verifyWith(getSigningKey()) // 设置验证密钥 .build() .parseSignedClaims(token) // 解析并验证签名 .getPayload(); // 获取Payload部分 } /** * 验证令牌是否有效未过期且签名正确 * param token JWT令牌 * return 是否有效 */ public boolean validateToken(String token) { try { parseToken(token); // 如果解析成功说明签名有效且未过期过期会抛出ExpiredJwtException return true; } catch (Exception e) { // 可以在这里根据不同的异常如过期、签名错误、格式错误进行更精细的日志记录或处理 return false; } } /** * 从令牌中获取用户ID */ public String getUserIdFromToken(String token) { Claims claims parseToken(token); return claims.get(userId, String.class); } /** * 从令牌中获取用户名 */ public String getUsernameFromToken(String token) { Claims claims parseToken(token); return claims.get(username, String.class); } /** * 检查令牌是否即将过期例如在到期前5分钟内 * param token JWT令牌 * param minutes 提前多少分钟视为“即将过期” * return 是否即将过期 */ public boolean isTokenAboutToExpire(String token, int minutes) { try { Claims claims parseToken(token); Date expiration claims.getExpiration(); Date now new Date(); // 计算距离过期还有多少毫秒 long timeUntilExpiry expiration.getTime() - now.getTime(); return timeUntilExpiry (minutes * 60 * 1000); } catch (Exception e) { return true; // 如果解析失败视为无效/过期 } } }这个工具类涵盖了基本操作。generateAccessToken方法用于在用户登录成功后签发访问令牌我将用户ID和用户名作为标准声明放入。generateRefreshToken专门用于生成刷新令牌并标记了类型。parseToken和validateToken是验证的核心。isTokenAboutToExpire方法为后续实现令牌自动刷新提供了可能。4.2 关于密钥安全与算法升级的思考在上面的代码中密钥是通过配置文件读取的字符串转换而来。这在开发环境很方便但在生产环境是高危行为。务必通过环境变量如JWT_SECRET注入或者在应用启动时从安全的密钥管理系统获取。另外虽然我们使用了HS256但如果你规划的是微服务架构未来可能会有独立的认证授权服务Auth Server和多个资源服务Resource Server。那时RS256非对称加密会是更好的选择。Auth Server用私钥签名各个Resource Server用公钥验证私钥可以得到更严密的保护。从HS256迁移到RS256主要改动在于密钥的生成、配置和工具类中的signWith/verifyWith方法。5. 实现登录接口与令牌颁发工具类准备就绪接下来实现用户登录的逻辑。我假设你已经有一个User实体和对应的UserService用于根据用户名查询用户并验证密码密码需加密存储如BCrypt。这里我们聚焦于登录成功后的令牌颁发流程。5.1 定义统一的响应格式首先定义一个通用的API响应体方便前端处理Data public class ApiResponseT { private Integer code; // 状态码如200成功401未授权 private String message; // 提示信息 private T data; // 响应数据 public static T ApiResponseT success(T data) { ApiResponseT response new ApiResponse(); response.setCode(200); response.setMessage(success); response.setData(data); return response; } // 可以补充error等静态工厂方法 }5.2 登录请求与响应DTO创建登录请求和登录响应的数据传输对象Data public class LoginRequest { NotBlank(message 用户名不能为空) private String username; NotBlank(message 密码不能为空) private String password; } Data public class LoginResponse { private String accessToken; // 访问令牌 private String refreshToken; // 刷新令牌 private String tokenType Bearer; // 令牌类型 private Long expiresIn; // 访问令牌过期时间秒 private UserInfo userInfo; // 基本的用户信息如用户名、头像等 Data public static class UserInfo { private String userId; private String username; private String avatar; // ... 其他不敏感的用户信息 } }5.3 实现AuthController现在实现登录接口RestController RequestMapping(/api/auth) public class AuthController { Autowired private UserService userService; Autowired private JwtUtil jwtUtil; Autowired private JwtProperties jwtProperties; PostMapping(/login) public ApiResponseLoginResponse login(Valid RequestBody LoginRequest loginRequest) { // 1. 验证用户凭证 User user userService.authenticate(loginRequest.getUsername(), loginRequest.getPassword()); if (user null) { // 这里应该抛出定义好的业务异常由全局异常处理器统一返回401 throw new UnauthorizedException(用户名或密码错误); } // 2. 准备JWT的声明Claims可以加入用户角色等 MapString, Object extraClaims new HashMap(); // 假设用户有角色信息 extraClaims.put(roles, user.getRoles()); // 例如 [ROLE_ADMIN, ROLE_USER] // 3. 生成访问令牌和刷新令牌 String accessToken jwtUtil.generateAccessToken(user.getId().toString(), user.getUsername(), extraClaims); String refreshToken jwtUtil.generateRefreshToken(user.getId().toString()); // 4. 构建响应 LoginResponse response new LoginResponse(); response.setAccessToken(accessToken); response.setRefreshToken(refreshToken); response.setExpiresIn(jwtProperties.getAccessTokenExpireTime()); LoginResponse.UserInfo userInfo new LoginResponse.UserInfo(); userInfo.setUserId(user.getId().toString()); userInfo.setUsername(user.getUsername()); userInfo.setAvatar(user.getAvatar()); response.setUserInfo(userInfo); // 5. 可选将刷新令牌与用户关联存储到数据库或缓存用于后续刷新和吊销 // refreshTokenService.saveRefreshToken(user.getId(), refreshToken); return ApiResponse.success(response); } }登录接口的核心逻辑清晰验证用户 - 生成双Token - 返回给客户端。这里我生成了两个TokenaccessToken用于API访问有效期短refreshToken用于获取新的accessToken有效期长。这是一种常见的增强安全性的实践。实操心得在返回refreshToken时一种更安全的做法是将其通过HttpOnly、Secure的Cookie返回给前端而不是放在JSON响应体里。这样可以有效防止XSS攻击窃取刷新令牌。访问令牌由于有效期短且前端需要主动将其放入Authorization头可以放在响应体中。这需要根据你的前端架构和安全要求进行权衡。6. 实现JWT请求过滤器守卫每一条API令牌发下去了下一步就是如何验证它。我们通过实现一个Servlet Filter过滤器来拦截所有需要认证的请求提取并验证JWT。6.1 创建JwtAuthenticationFilterComponent public class JwtAuthenticationFilter extends OncePerRequestFilter { // OncePerRequestFilter确保一次请求只过滤一次 Autowired private JwtUtil jwtUtil; Autowired private JwtProperties jwtProperties; Autowired private UserDetailsService userDetailsService; // Spring Security的核心接口用于加载用户详情 Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // 1. 从请求头获取令牌 String authHeader request.getHeader(jwtProperties.getTokenHeader()); String token null; if (authHeader ! null authHeader.startsWith(jwtProperties.getTokenPrefix() )) { // 去掉Bearer 前缀获取纯Token字符串 token authHeader.substring(jwtProperties.getTokenPrefix().length() 1); } // 2. 验证令牌 if (token ! null jwtUtil.validateToken(token)) { try { // 3. 从令牌中解析用户名 String username jwtUtil.getUsernameFromToken(token); // 4. 加载用户详情这里可以从数据库查也可以像下面一样从Token声明中构建 if (username ! null SecurityContextHolder.getContext().getAuthentication() null) { // 方式一从数据库加载用户权限信息更准确可检查用户状态是否被禁用 // UserDetails userDetails userDetailsService.loadUserByUsername(username); // 方式二直接从JWT的声明中构建UserDetails性能更好但无法实时反映用户状态变更 Claims claims jwtUtil.parseToken(token); String userId claims.get(userId, String.class); SuppressWarnings(unchecked) ListString roles claims.get(roles, List.class); // 将角色列表转换为Spring Security需要的GrantedAuthority集合 ListGrantedAuthority authorities roles.stream() .map(role - new SimpleGrantedAuthority(role)) .collect(Collectors.toList()); UserDetails userDetails new org.springframework.security.core.userdetails.User( username, , authorities // 密码置空因为JWT已证明身份 ); // 5. 创建Authentication对象并设置到SecurityContext UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities()); // 可以在这里将userId等额外信息放入details authentication.setDetails(new HashMapString, Object() {{ put(userId, userId); }}); SecurityContextHolder.getContext().setAuthentication(authentication); } } catch (Exception e) { // 令牌解析或验证失败记录日志但不中断过滤器链由后续的授权机制处理返回403 logger.error(JWT令牌处理失败: e.getMessage()); // 可以选择清理SecurityContext确保后续是未认证状态 SecurityContextHolder.clearContext(); } } // 6. 继续执行过滤器链 filterChain.doFilter(request, response); } }这个过滤器是整个认证流程的枢纽。它做了以下几件事提取Token从标准的Authorization: Bearer token头中提取JWT字符串。验证Token调用JwtUtil.validateToken验证签名和过期时间。构建认证信息验证通过后从Token中提取用户信息如用户名、角色。这里我演示了两种构建UserDetails的方式。从数据库加载可以确保用户状态如是否被禁用是最新的但会增加一次数据库查询。从Token声明构建性能更好实现了完全的无状态但无法实时处理用户权限变更或账户封禁。在实际项目中需要根据安全要求的严格程度进行权衡。对于后台管理系统可能更倾向于从数据库加载。设置安全上下文将构建好的Authentication对象存入SecurityContextHolder。这样在本次请求的后续任何地方如Controller、Service层都可以通过SecurityContextHolder.getContext().getAuthentication()获取到当前登录用户的信息。6.2 配置Filter生效创建了Filter之后需要将其注册到Spring的过滤器链中。如果你使用了Spring Security推荐可以在Security配置类中将其添加在合适的位点通常是在用户名密码认证过滤器之前。如果你没有使用Spring Security则需要通过Configuration类手动注册一个FilterRegistrationBean。这里展示集成Spring Security的配置方式Configuration EnableWebSecurity public class SecurityConfig { Autowired private JwtAuthenticationFilter jwtAuthenticationFilter; Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http // 禁用CSRF因为JWT是无状态的且常用于API场景。如果是带有Web页面的应用需谨慎评估。 .csrf(csrf - csrf.disable()) // 配置会话管理为无状态 .sessionManagement(session - session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(authz - authz // 公开登录接口无需认证 .requestMatchers(/api/auth/login, /api/auth/refresh).permitAll() // 其他所有请求都需要认证 .anyRequest().authenticated() ) // 在UsernamePasswordAuthenticationFilter之前添加我们的JWT过滤器 .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class); return http.build(); } // 配置一个不做任何编码的密码编码器因为我们用JWT不需要PasswordEncoder // 但UserService里验证密码时可能还需要BCrypt所以这个Bean可能用于其他地方 Bean public PasswordEncoder passwordEncoder() { return NoOpPasswordEncoder.getInstance(); // 仅用于演示生产环境根据密码校验方式决定 } }这个配置做了关键几件事关闭CSRF适用于纯API、设置无状态会话、放行登录和刷新令牌接口、保护其他所有接口最后将我们的JwtAuthenticationFilter插入到Spring Security的过滤器链中。7. 实现令牌刷新与安全增强机制基本的登录和认证已经完成但一个健壮的认证系统还需要考虑令牌的刷新、以及如何应对JWT固有的短板如无法主动失效。7.1 刷新令牌接口客户端在访问令牌过期前可以使用刷新令牌来获取一组新的令牌而无需用户重新输入密码。RestController RequestMapping(/api/auth) public class AuthController { // ... 之前的login方法 PostMapping(/refresh) public ApiResponseLoginResponse refreshToken(RequestBody RefreshTokenRequest request) { String refreshToken request.getRefreshToken(); // 1. 验证刷新令牌本身是否有效 if (!jwtUtil.validateToken(refreshToken)) { throw new UnauthorizedException(刷新令牌无效或已过期); } // 2. 解析刷新令牌获取用户ID Claims claims jwtUtil.parseToken(refreshToken); if (!refresh.equals(claims.get(type, String.class))) { throw new UnauthorizedException(令牌类型错误); } String userId claims.get(userId, String.class); // 3. 关键校验刷新令牌是否在服务端的“白名单”或未被吊销 // 这里需要查询数据库或缓存检查此refreshToken是否与该用户绑定且状态有效 // boolean isValid refreshTokenService.validateRefreshToken(userId, refreshToken); // if (!isValid) { // throw new UnauthorizedException(刷新令牌已被吊销); // } // 如果验证通过可以删除旧的刷新令牌实现单次使用增强安全可选 // 4. 根据用户ID查询最新的用户信息因为用户角色可能已变更 User user userService.findById(userId); if (user null) { throw new UnauthorizedException(用户不存在); } // 5. 生成新的访问令牌和刷新令牌 MapString, Object extraClaims new HashMap(); extraClaims.put(roles, user.getRoles()); String newAccessToken jwtUtil.generateAccessToken(userId, user.getUsername(), extraClaims); String newRefreshToken jwtUtil.generateRefreshToken(userId); // 6. 更新服务端存储的刷新令牌如果实现了存储的话 // refreshTokenService.updateRefreshToken(userId, newRefreshToken); // 7. 返回新的令牌对 LoginResponse response new LoginResponse(); response.setAccessToken(newAccessToken); response.setRefreshToken(newRefreshToken); response.setExpiresIn(jwtProperties.getAccessTokenExpireTime()); // ... 设置userInfo return ApiResponse.success(response); } }刷新令牌接口的核心安全点在于服务端状态校验。虽然JWT本身可自验证但为了能够主动吊销令牌如用户退出登录、修改密码后使旧令牌失效我们需要将刷新令牌在服务端存一份比如在数据库中关联用户ID并在刷新时校验其有效性。这是一种“有状态”与“无状态”的折中方案用很小的状态管理代价换来了重要的安全控制能力。7.2 实现令牌黑名单/白名单机制访问令牌Access Token由于有效期短通常不单独做服务端存储校验。但如果你有“立即踢人下线”这种强需求可以引入一个短期的“黑名单”或“令牌版本号”机制。黑名单用户退出登录或修改密码时将尚未过期的访问令牌的唯一标识如jti声明JWT ID存入Redis并设置一个略长于令牌剩余有效期的TTL。在过滤器中除了验证签名和过期时间还要检查该令牌是否在黑名单中。令牌版本号在用户表中增加一个tokenVersion字段。生成JWT时将tokenVersion放入声明。当用户修改密码或强制下线时递增其tokenVersion。在验证JWT时不仅验证签名和过期还要从声明中取出tokenVersion与数据库中的当前版本比对不一致则拒绝。这两种方式都引入了少量的服务端状态但实现了对JWT生命周期的主动管理。7.3 前端令牌存储与自动携带的最佳实践前端拿到令牌后如何安全地存储和自动附加到请求中也很重要。存储位置访问令牌可以存储在内存Vue/React的状态管理如Vuex/Pinia、Redux或localStorage/sessionStorage。存储在内存更安全防XSS但页面刷新会丢失。存储在localStorage持久化好但需防范XSS攻击窃取。权衡之下对于大多数SPA将Access Token存入localStorage是常见做法但必须确保你的网站没有XSS漏洞。刷新令牌如前所述最好通过HttpOnly、Secure、SameSiteStrict的Cookie来存储这样JavaScript无法访问能有效防御XSS。自动携带使用Axios等HTTP库的请求拦截器自动从localStorage读取Access Token并添加到Authorization头。// axios实例配置 import axios from axios; const apiClient axios.create({ baseURL: process.env.VUE_APP_API_BASE_URL, }); // 请求拦截器 apiClient.interceptors.request.use( (config) { const token localStorage.getItem(access_token); if (token) { config.headers.Authorization Bearer ${token}; } return config; }, (error) { return Promise.reject(error); } );令牌刷新与请求重试在响应拦截器中检查如果接口返回401令牌过期则尝试调用刷新令牌接口获取新令牌然后用新令牌重试失败的请求。这个过程对上层业务透明。// 响应拦截器 - 处理令牌刷新 let isRefreshing false; let failedQueue []; apiClient.interceptors.response.use( (response) response, async (error) { const originalRequest error.config; if (error.response?.status 401 !originalRequest._retry) { if (isRefreshing) { // 如果正在刷新将失败的请求加入队列 return new Promise((resolve, reject) { failedQueue.push({ resolve, reject }); }).then(() { return apiClient(originalRequest); }).catch(err { return Promise.reject(err); }); } originalRequest._retry true; isRefreshing true; try { // 调用刷新令牌接口 const refreshToken getRefreshTokenFromCookie(); // 从Cookie获取 const { data } await axios.post(/api/auth/refresh, { refreshToken }); // 存储新的访问令牌 localStorage.setItem(access_token, data.data.accessToken); // 可能更新Cookie中的刷新令牌 setRefreshTokenToCookie(data.data.refreshToken); // 重试所有队列中的请求 failedQueue.forEach(pending pending.resolve()); // 重试当前请求 return apiClient(originalRequest); } catch (refreshError) { // 刷新失败清空令牌跳转到登录页 failedQueue.forEach(pending pending.reject(refreshError)); localStorage.removeItem(access_token); // 清除刷新令牌Cookie clearRefreshTokenCookie(); window.location.href /login; return Promise.reject(refreshError); } finally { isRefreshing false; failedQueue []; } } return Promise.reject(error); } );这套前端拦截器逻辑能较好地处理令牌过期的场景实现无感刷新提升用户体验。8. 常见问题、排查技巧与进阶思考在实际开发和上线后你肯定会遇到各种各样的问题。下面是我总结的一些典型场景和排查思路。8.1 问题排查速查表问题现象可能原因排查步骤与解决方案登录成功但访问接口返回401 Unauthorized1. 请求头未携带Token或格式错误。2. Token已过期。3. Token签名验证失败密钥不一致。4. 过滤器配置路径有误未拦截到请求。1. 检查浏览器开发者工具的Network标签确认请求头是否有Authorization: Bearer token注意Bearer后有一个空格。2. 检查Token的exp声明是否已过当前时间。可以在 jwt.io 解码查看。3. 对比签发和验证时使用的jwt.secret是否完全一致。检查是否有环境变量覆盖问题。4. 检查Spring Security的配置确保目标接口路径不在permitAll()范围内且过滤器已正确添加。接口访问返回403 Forbidden1. 用户角色/权限不足。2. SecurityContext中未设置认证信息。1. 检查JWT的roles声明是否包含访问该接口所需的权限。在Controller方法上使用PreAuthorize(hasRole(ADMIN))进行测试。2. 在过滤器中打断点确认SecurityContextHolder.getContext().getAuthentication()是否成功设置。检查Token解析过程是否抛出异常被捕获。刷新令牌接口调用失败1. 刷新令牌过期。2. 刷新令牌类型错误误用了Access Token。3. 服务端存储的刷新令牌状态无效如已被使用或吊销。1. 检查刷新令牌的exp。2. 在刷新令牌的Payload中加入”type”: “refresh”声明并在验证时检查。3. 如果实现了服务端存储检查数据库或缓存中该令牌是否存在且状态为有效。生产环境密钥泄露风险密钥硬编码在配置文件并提交到代码仓库。立即轮换密钥并通过环境变量、配置中心如Nacos, Apollo或云服务商密钥管理服务如AWS KMS,阿里云KMS来管理密钥。所有服务器使用统一的密钥源。如何让已颁发的JWT立即失效JWT本身无法作废。采用7.2中提到的黑名单或令牌版本号机制。退出登录或修改密码时将旧Token标识加入黑名单设置合理TTL或递增用户的tokenVersion。8.2 性能与安全进阶思考Token过长问题JWT的Payload会Base64编码后直接放在Token里如果放入过多信息如用户完整信息、权限列表过长会导致Token体积膨胀增加每次请求的带宽消耗。解决方案是Payload只存放最核心的用户标识如userId权限等信息在服务端验证时通过userId实时查询缓存获取。这是一种空间换时间的权衡。注销与踢人下线这是JWT的经典难题。除了上面提到的黑名单/版本号还可以采用“短期令牌频繁刷新”的策略。将Access Token有效期设置得非常短如15分钟并强制前端定期如每10分钟使用Refresh Token刷新。当需要踢人时服务端只需吊销用户的Refresh Token即可旧的Access Token会在很短时间内自然过期。防止令牌盗用与重放攻击使用HTTPS这是最基本的要求防止令牌在传输中被窃听。绑定客户端指纹在生成Token时可以加入客户端的某些指纹信息如IP地址、User-Agent的哈希值验证时进行比对。但这会影响用户体验如用户切换网络IP会导致Token失效。设置合理的过期时间缩短Access Token有效期降低泄露后的风险窗口。多端登录与并发管理一个用户可能在手机、电脑同时登录。如果使用单一的Refresh Token在一端刷新后另一端的Refresh Token就会失效如果实现了单次使用。更复杂的场景需要维护一个Refresh Token列表并可能提供“查看登录设备”、“远程注销”等功能这时的状态管理就更加复杂。8.3 与Spring Security的深度集成我们的例子中只是简单使用了Spring Security的上下文。实际上Spring Security提供了强大的注解支持如PreAuthorize,PostAuthorize,Secured等可以非常优雅地在方法级别进行权限控制。RestController RequestMapping(/api/admin) public class AdminController { GetMapping(/users) PreAuthorize(hasRole(ADMIN)) // 必须拥有ROLE_ADMIN角色 public ApiResponseListUser listUsers() { // ... } DeleteMapping(/user/{id}) PreAuthorize(hasAuthority(USER_DELETE)) // 必须拥有USER_DELETE权限 public ApiResponseVoid deleteUser(PathVariable Long id) { // ... } }要启用这些注解需要在Security配置类上加上EnableGlobalMethodSecurity(prePostEnabled true, securedEnabled true)。这样结合JWT过滤器设置的权限信息就能实现细粒度的接口授权。集成JWT到SpringBoot项目远不止是引入一个库、写一个工具类那么简单。它涉及到认证架构的选择、安全与性能的权衡、前后端的协同以及生产环境的运维。从简单的HS256对称加密到复杂的RS256非对称加密与微服务网关集成从无状态的令牌到有状态的吊销管理每一步都需要根据你的实际业务场景做出决策。我分享的这个方案是一个兼顾了实用性、安全性和可扩展性的起点。在实际项目中你可能会遇到更复杂的需求比如多因素认证、OAuth2.0集成等但理解了JWT和Spring Security这套核心机制再去扩展其他功能就会游刃有余。最关键的是始终把安全放在第一位妥善管理你的密钥并设计好令牌的生命周期。
SpringBoot集成JWT实现无状态认证：从Session到Token的架构升级实践
1. 项目概述与核心价值最近在重构一个老的后台管理系统用户登录认证这块儿一直用的是传统的Session-Cookie方案。随着微服务拆分和前后端分离架构的普及这套方案在扩展性和维护性上的短板越来越明显。每次新开一个服务都得考虑Session共享的问题用Redis吧确实能解决但总觉得架构上不够“清爽”。正好团队里有个新启动的SPA项目技术选型时大家一致决定用JWT来做无状态认证。我花了点时间把SpringBoot集成JWT的流程从头到尾捋了一遍踩了几个坑也总结出一些能让集成过程更顺滑的实践技巧。这篇文章我就把这次从零到一的完整过程包括背后的设计思考、具体的代码实现以及那些官方文档里不会写的“坑点”都详细记录下来。JWT全称JSON Web Token本质上是一个开放标准它定义了一种紧凑且自包含的方式用于在各方之间安全地传输信息。你可以把它想象成一张“数字身份证”。当用户首次登录成功时服务器端会签发一张包含用户身份信息如用户ID、角色的JWT令牌给客户端通常是浏览器。此后客户端在请求需要认证的接口时只需在HTTP请求头中带上这张“身份证”服务器端通过验证令牌的签名即可确认用户身份无需再去查询数据库或Session存储。这对于构建可扩展的分布式系统特别是前后端分离、移动端应用来说优势非常明显服务端彻底无状态天然支持水平扩展令牌本身携带信息减少了查库次数跨语言、跨平台支持性好。那么这个方案具体适合谁呢如果你正在开发一个新的SpringBoot项目并且采用了前后端分离的架构或者你正在将原有的单体应用向微服务架构迁移受困于状态管理亦或是你需要为移动App提供API接口那么集成JWT进行认证会是一个值得认真考虑的选择。接下来我会从设计思路、依赖选型、代码实现、安全增强到上线排查一步步带你走完整个流程。2. 整体设计与核心思路拆解在动手写代码之前理清整体设计思路至关重要。我们不能仅仅满足于“跑通”更要明白每一步选择背后的原因以及如何规避潜在的风险。2.1 为何选择JWT而非Session首先我们需要明确JWT解决的核心痛点。在传统的Session方案中用户的登录状态保存在服务端的内存或Redis中客户端仅持有一个Session ID。这种方式的弊端在于服务端是有状态的。在集群环境下你必须借助额外的中间件如Redis来实现Session共享这增加了系统的复杂度和运维成本。此外对于原生移动App或第三方API调用处理Cookie并不总是那么方便。JWT采用了一种截然不同的思路将状态信息直接编码到令牌中并附上签名以确保其不可篡改。服务端在签发令牌后就“忘记”了它后续的认证只需验证签名和令牌有效性即可。这种无状态特性使得任何一个服务实例都能独立处理认证请求极大地提升了系统的伸缩能力。对于我们的SPA项目前端Vue/React可以将获取到的JWT存储在localStorage或Cookie中并在每次请求API时自动携带流程非常清晰。2.2 JWT令牌的结构与安全考量一个JWT令牌由三部分组成以点号分隔Header.Payload.Signature。Header通常包含令牌类型typ: “JWT”和所使用的签名算法alg如HS256、RS256。Payload这是令牌的核心包含所谓的“声明”。声明分为三种预定义的注册声明如iss签发者、exp过期时间、公共声明和私有声明。我们最常用的就是私有声明用来存放用户ID、用户名、角色等信息。这里有一个非常重要的注意事项Payload部分仅仅是Base64Url编码并非加密。因此绝对禁止在Payload中存放任何敏感信息例如用户密码、银行卡号等。Signature签名部分。服务器使用Header中声明的算法一个密钥Secret对编码后的Header和Payload进行签名。这个签名用于验证消息在传输过程中未被篡改同时也是验证令牌签发方的依据。算法选择上HS256HMAC SHA-256使用一个对称密钥进行签名和验证简单高效适合单服务场景。而RS256RSA SHA-256使用非对称加密私钥用于签名公钥用于验证更适合多服务、需要分离签发和验证职责的微服务场景。在我们的初期集成中从简单出发选择HS256。2.3 集成后的核心流程集成的核心目标是构建一个完整的认证闭环流程如下登录接口用户提交用户名密码。服务端校验通过后生成JWT令牌包含用户信息、过期时间等返回给客户端。令牌存储与携带客户端如前端收到令牌后需要安全地存储起来通常放在Authorization请求头中格式为Bearer token。接口认证对于需要认证的API服务端通过一个过滤器Filter或拦截器Interceptor从请求头中提取JWT令牌并进行验证签名是否有效、是否过期等。验证通过后将用户信息存入本次请求的上下文如Spring Security的SecurityContext供后续业务逻辑使用。令牌刷新为了平衡安全性与用户体验通常会设计一个刷新令牌的机制。当访问令牌Access Token临近过期时客户端可以使用一个有效期更长的刷新令牌Refresh Token来获取新的访问令牌而无需用户重新登录。这个流程看似清晰但其中每一步都有细节需要打磨比如如何优雅地处理令牌过期、如何实现强制下线JWT的无状态特性使其无法像Session那样直接失效需要额外设计、如何防止令牌被盗用等。我们会在后续章节逐一展开。3. 依赖引入与基础配置理论清晰后我们开始动手。首先创建一个标准的SpringBoot项目这里我使用Spring Initializr选择Spring Web依赖。然后我们需要引入JWT相关的库。3.1 JJWT库的选择与引入Java领域最流行的JWT库是jjwt由Auth0维护。它API设计清晰文档完善。截至我写作时推荐使用jjwt-api、jjwt-impl、jjwt-jackson这三个组件的0.12.x及以上版本。这个版本系列重构了API更安全、更符合现代Java开发习惯。在你的pom.xml文件中添加以下依赖dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.12.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.12.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.12.5/version scoperuntime/scope /dependency注意jjwt-impl和jjwt-jackson设置为runtime作用域是因为你的代码在编译期只需要依赖jjwt-api中定义的接口。具体的实现和JSON处理在运行时提供这符合良好的依赖管理实践。3.2 核心配置参数管理我们需要将JWT相关的配置集中管理例如密钥、令牌有效期等。在application.yml或application.properties中配置jwt: secret: your-256-bit-secret-your-256-bit-secret-your-256-bit-secret # 用于HS256签名的密钥至少32字符 access-token-expire-time: 7200 # 访问令牌过期时间单位秒例如2小时7200秒 refresh-token-expire-time: 604800 # 刷新令牌过期时间单位秒例如7天604800秒 token-header: Authorization # 客户端传递令牌的请求头名称 token-prefix: Bearer # 令牌前缀通常为Bearer注意后面有个空格这里有几个关键点密钥Secret这是HS256算法的核心必须足够复杂且保密。在生产环境中绝对不要将明文密钥写在配置文件中提交到代码仓库。应该使用环境变量、配置中心或密钥管理服务来注入。示例中的your-256-bit-secret...只是一个占位符。过期时间访问令牌Access Token有效期较短用于日常API调用即使泄露危害窗口也较小。刷新令牌Refresh Token有效期较长用于获取新的访问令牌它需要被更安全地存储例如服务端可将其与用户关联并存入数据库使用时校验状态。请求头格式这是行业标准做法Authorization: Bearer your-jwt-token。注意Bearer后面有一个空格。接下来我们创建一个配置类JwtProperties来映射这些配置import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; Data Component ConfigurationProperties(prefix jwt) public class JwtProperties { private String secret; private Long accessTokenExpireTime; private Long refreshTokenExpireTime; private String tokenHeader; private String tokenPrefix; }确保你的项目已经引入了Lombok依赖以便使用Data注解自动生成getter和setter。4. JWT工具类封装签发与解析的核心有了配置我们就可以创建最核心的JWT工具类。这个类将封装令牌的生成、解析、验证等所有操作。我将其设计为Component方便在其他地方注入使用。4.1 构建JwtUtil工具类import io.jsonwebtoken.Claims; import io.jsonwebtoken.Jwts; import io.jsonwebtoken.security.Keys; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import javax.crypto.SecretKey; import java.util.Date; import java.util.HashMap; import java.util.Map; Component public class JwtUtil { Autowired private JwtProperties jwtProperties; // 生成安全的密钥对象 private SecretKey getSigningKey() { // 将配置的字符串密钥转换为jjwt需要的SecretKey对象 return Keys.hmacShaKeyFor(jwtProperties.getSecret().getBytes(StandardCharsets.UTF_8)); } /** * 生成访问令牌 * param userId 用户唯一标识 * param username 用户名 * param extraClaims 额外的声明信息如角色 * return 生成的JWT字符串 */ public String generateAccessToken(String userId, String username, MapString, Object extraClaims) { MapString, Object claims new HashMap(); claims.put(userId, userId); claims.put(username, username); if (extraClaims ! null) { claims.putAll(extraClaims); } return buildToken(claims, jwtProperties.getAccessTokenExpireTime()); } /** * 生成刷新令牌通常只包含用户ID用于换取新的访问令牌 * param userId 用户唯一标识 * return 生成的刷新令牌JWT字符串 */ public String generateRefreshToken(String userId) { MapString, Object claims new HashMap(); claims.put(userId, userId); claims.put(type, refresh); // 明确令牌类型防止误用 return buildToken(claims, jwtProperties.getRefreshTokenExpireTime()); } /** * 构建JWT令牌的通用方法 */ private String buildToken(MapString, Object claims, Long expiration) { Date now new Date(); Date expiryDate new Date(now.getTime() expiration * 1000); return Jwts.builder() .claims(claims) // 设置声明Payload .issuedAt(now) // 签发时间 (iat) .expiration(expiryDate) // 过期时间 (exp) .signWith(getSigningKey(), Jwts.SIG.HS256) // 使用HS256算法和密钥签名 .compact(); // 压缩生成最终的字符串 } /** * 从令牌中解析所有声明Claims * param token JWT令牌 * return Claims 对象 */ public Claims parseToken(String token) { return Jwts.parser() .verifyWith(getSigningKey()) // 设置验证密钥 .build() .parseSignedClaims(token) // 解析并验证签名 .getPayload(); // 获取Payload部分 } /** * 验证令牌是否有效未过期且签名正确 * param token JWT令牌 * return 是否有效 */ public boolean validateToken(String token) { try { parseToken(token); // 如果解析成功说明签名有效且未过期过期会抛出ExpiredJwtException return true; } catch (Exception e) { // 可以在这里根据不同的异常如过期、签名错误、格式错误进行更精细的日志记录或处理 return false; } } /** * 从令牌中获取用户ID */ public String getUserIdFromToken(String token) { Claims claims parseToken(token); return claims.get(userId, String.class); } /** * 从令牌中获取用户名 */ public String getUsernameFromToken(String token) { Claims claims parseToken(token); return claims.get(username, String.class); } /** * 检查令牌是否即将过期例如在到期前5分钟内 * param token JWT令牌 * param minutes 提前多少分钟视为“即将过期” * return 是否即将过期 */ public boolean isTokenAboutToExpire(String token, int minutes) { try { Claims claims parseToken(token); Date expiration claims.getExpiration(); Date now new Date(); // 计算距离过期还有多少毫秒 long timeUntilExpiry expiration.getTime() - now.getTime(); return timeUntilExpiry (minutes * 60 * 1000); } catch (Exception e) { return true; // 如果解析失败视为无效/过期 } } }这个工具类涵盖了基本操作。generateAccessToken方法用于在用户登录成功后签发访问令牌我将用户ID和用户名作为标准声明放入。generateRefreshToken专门用于生成刷新令牌并标记了类型。parseToken和validateToken是验证的核心。isTokenAboutToExpire方法为后续实现令牌自动刷新提供了可能。4.2 关于密钥安全与算法升级的思考在上面的代码中密钥是通过配置文件读取的字符串转换而来。这在开发环境很方便但在生产环境是高危行为。务必通过环境变量如JWT_SECRET注入或者在应用启动时从安全的密钥管理系统获取。另外虽然我们使用了HS256但如果你规划的是微服务架构未来可能会有独立的认证授权服务Auth Server和多个资源服务Resource Server。那时RS256非对称加密会是更好的选择。Auth Server用私钥签名各个Resource Server用公钥验证私钥可以得到更严密的保护。从HS256迁移到RS256主要改动在于密钥的生成、配置和工具类中的signWith/verifyWith方法。5. 实现登录接口与令牌颁发工具类准备就绪接下来实现用户登录的逻辑。我假设你已经有一个User实体和对应的UserService用于根据用户名查询用户并验证密码密码需加密存储如BCrypt。这里我们聚焦于登录成功后的令牌颁发流程。5.1 定义统一的响应格式首先定义一个通用的API响应体方便前端处理Data public class ApiResponseT { private Integer code; // 状态码如200成功401未授权 private String message; // 提示信息 private T data; // 响应数据 public static T ApiResponseT success(T data) { ApiResponseT response new ApiResponse(); response.setCode(200); response.setMessage(success); response.setData(data); return response; } // 可以补充error等静态工厂方法 }5.2 登录请求与响应DTO创建登录请求和登录响应的数据传输对象Data public class LoginRequest { NotBlank(message 用户名不能为空) private String username; NotBlank(message 密码不能为空) private String password; } Data public class LoginResponse { private String accessToken; // 访问令牌 private String refreshToken; // 刷新令牌 private String tokenType Bearer; // 令牌类型 private Long expiresIn; // 访问令牌过期时间秒 private UserInfo userInfo; // 基本的用户信息如用户名、头像等 Data public static class UserInfo { private String userId; private String username; private String avatar; // ... 其他不敏感的用户信息 } }5.3 实现AuthController现在实现登录接口RestController RequestMapping(/api/auth) public class AuthController { Autowired private UserService userService; Autowired private JwtUtil jwtUtil; Autowired private JwtProperties jwtProperties; PostMapping(/login) public ApiResponseLoginResponse login(Valid RequestBody LoginRequest loginRequest) { // 1. 验证用户凭证 User user userService.authenticate(loginRequest.getUsername(), loginRequest.getPassword()); if (user null) { // 这里应该抛出定义好的业务异常由全局异常处理器统一返回401 throw new UnauthorizedException(用户名或密码错误); } // 2. 准备JWT的声明Claims可以加入用户角色等 MapString, Object extraClaims new HashMap(); // 假设用户有角色信息 extraClaims.put(roles, user.getRoles()); // 例如 [ROLE_ADMIN, ROLE_USER] // 3. 生成访问令牌和刷新令牌 String accessToken jwtUtil.generateAccessToken(user.getId().toString(), user.getUsername(), extraClaims); String refreshToken jwtUtil.generateRefreshToken(user.getId().toString()); // 4. 构建响应 LoginResponse response new LoginResponse(); response.setAccessToken(accessToken); response.setRefreshToken(refreshToken); response.setExpiresIn(jwtProperties.getAccessTokenExpireTime()); LoginResponse.UserInfo userInfo new LoginResponse.UserInfo(); userInfo.setUserId(user.getId().toString()); userInfo.setUsername(user.getUsername()); userInfo.setAvatar(user.getAvatar()); response.setUserInfo(userInfo); // 5. 可选将刷新令牌与用户关联存储到数据库或缓存用于后续刷新和吊销 // refreshTokenService.saveRefreshToken(user.getId(), refreshToken); return ApiResponse.success(response); } }登录接口的核心逻辑清晰验证用户 - 生成双Token - 返回给客户端。这里我生成了两个TokenaccessToken用于API访问有效期短refreshToken用于获取新的accessToken有效期长。这是一种常见的增强安全性的实践。实操心得在返回refreshToken时一种更安全的做法是将其通过HttpOnly、Secure的Cookie返回给前端而不是放在JSON响应体里。这样可以有效防止XSS攻击窃取刷新令牌。访问令牌由于有效期短且前端需要主动将其放入Authorization头可以放在响应体中。这需要根据你的前端架构和安全要求进行权衡。6. 实现JWT请求过滤器守卫每一条API令牌发下去了下一步就是如何验证它。我们通过实现一个Servlet Filter过滤器来拦截所有需要认证的请求提取并验证JWT。6.1 创建JwtAuthenticationFilterComponent public class JwtAuthenticationFilter extends OncePerRequestFilter { // OncePerRequestFilter确保一次请求只过滤一次 Autowired private JwtUtil jwtUtil; Autowired private JwtProperties jwtProperties; Autowired private UserDetailsService userDetailsService; // Spring Security的核心接口用于加载用户详情 Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // 1. 从请求头获取令牌 String authHeader request.getHeader(jwtProperties.getTokenHeader()); String token null; if (authHeader ! null authHeader.startsWith(jwtProperties.getTokenPrefix() )) { // 去掉Bearer 前缀获取纯Token字符串 token authHeader.substring(jwtProperties.getTokenPrefix().length() 1); } // 2. 验证令牌 if (token ! null jwtUtil.validateToken(token)) { try { // 3. 从令牌中解析用户名 String username jwtUtil.getUsernameFromToken(token); // 4. 加载用户详情这里可以从数据库查也可以像下面一样从Token声明中构建 if (username ! null SecurityContextHolder.getContext().getAuthentication() null) { // 方式一从数据库加载用户权限信息更准确可检查用户状态是否被禁用 // UserDetails userDetails userDetailsService.loadUserByUsername(username); // 方式二直接从JWT的声明中构建UserDetails性能更好但无法实时反映用户状态变更 Claims claims jwtUtil.parseToken(token); String userId claims.get(userId, String.class); SuppressWarnings(unchecked) ListString roles claims.get(roles, List.class); // 将角色列表转换为Spring Security需要的GrantedAuthority集合 ListGrantedAuthority authorities roles.stream() .map(role - new SimpleGrantedAuthority(role)) .collect(Collectors.toList()); UserDetails userDetails new org.springframework.security.core.userdetails.User( username, , authorities // 密码置空因为JWT已证明身份 ); // 5. 创建Authentication对象并设置到SecurityContext UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities()); // 可以在这里将userId等额外信息放入details authentication.setDetails(new HashMapString, Object() {{ put(userId, userId); }}); SecurityContextHolder.getContext().setAuthentication(authentication); } } catch (Exception e) { // 令牌解析或验证失败记录日志但不中断过滤器链由后续的授权机制处理返回403 logger.error(JWT令牌处理失败: e.getMessage()); // 可以选择清理SecurityContext确保后续是未认证状态 SecurityContextHolder.clearContext(); } } // 6. 继续执行过滤器链 filterChain.doFilter(request, response); } }这个过滤器是整个认证流程的枢纽。它做了以下几件事提取Token从标准的Authorization: Bearer token头中提取JWT字符串。验证Token调用JwtUtil.validateToken验证签名和过期时间。构建认证信息验证通过后从Token中提取用户信息如用户名、角色。这里我演示了两种构建UserDetails的方式。从数据库加载可以确保用户状态如是否被禁用是最新的但会增加一次数据库查询。从Token声明构建性能更好实现了完全的无状态但无法实时处理用户权限变更或账户封禁。在实际项目中需要根据安全要求的严格程度进行权衡。对于后台管理系统可能更倾向于从数据库加载。设置安全上下文将构建好的Authentication对象存入SecurityContextHolder。这样在本次请求的后续任何地方如Controller、Service层都可以通过SecurityContextHolder.getContext().getAuthentication()获取到当前登录用户的信息。6.2 配置Filter生效创建了Filter之后需要将其注册到Spring的过滤器链中。如果你使用了Spring Security推荐可以在Security配置类中将其添加在合适的位点通常是在用户名密码认证过滤器之前。如果你没有使用Spring Security则需要通过Configuration类手动注册一个FilterRegistrationBean。这里展示集成Spring Security的配置方式Configuration EnableWebSecurity public class SecurityConfig { Autowired private JwtAuthenticationFilter jwtAuthenticationFilter; Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http // 禁用CSRF因为JWT是无状态的且常用于API场景。如果是带有Web页面的应用需谨慎评估。 .csrf(csrf - csrf.disable()) // 配置会话管理为无状态 .sessionManagement(session - session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(authz - authz // 公开登录接口无需认证 .requestMatchers(/api/auth/login, /api/auth/refresh).permitAll() // 其他所有请求都需要认证 .anyRequest().authenticated() ) // 在UsernamePasswordAuthenticationFilter之前添加我们的JWT过滤器 .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class); return http.build(); } // 配置一个不做任何编码的密码编码器因为我们用JWT不需要PasswordEncoder // 但UserService里验证密码时可能还需要BCrypt所以这个Bean可能用于其他地方 Bean public PasswordEncoder passwordEncoder() { return NoOpPasswordEncoder.getInstance(); // 仅用于演示生产环境根据密码校验方式决定 } }这个配置做了关键几件事关闭CSRF适用于纯API、设置无状态会话、放行登录和刷新令牌接口、保护其他所有接口最后将我们的JwtAuthenticationFilter插入到Spring Security的过滤器链中。7. 实现令牌刷新与安全增强机制基本的登录和认证已经完成但一个健壮的认证系统还需要考虑令牌的刷新、以及如何应对JWT固有的短板如无法主动失效。7.1 刷新令牌接口客户端在访问令牌过期前可以使用刷新令牌来获取一组新的令牌而无需用户重新输入密码。RestController RequestMapping(/api/auth) public class AuthController { // ... 之前的login方法 PostMapping(/refresh) public ApiResponseLoginResponse refreshToken(RequestBody RefreshTokenRequest request) { String refreshToken request.getRefreshToken(); // 1. 验证刷新令牌本身是否有效 if (!jwtUtil.validateToken(refreshToken)) { throw new UnauthorizedException(刷新令牌无效或已过期); } // 2. 解析刷新令牌获取用户ID Claims claims jwtUtil.parseToken(refreshToken); if (!refresh.equals(claims.get(type, String.class))) { throw new UnauthorizedException(令牌类型错误); } String userId claims.get(userId, String.class); // 3. 关键校验刷新令牌是否在服务端的“白名单”或未被吊销 // 这里需要查询数据库或缓存检查此refreshToken是否与该用户绑定且状态有效 // boolean isValid refreshTokenService.validateRefreshToken(userId, refreshToken); // if (!isValid) { // throw new UnauthorizedException(刷新令牌已被吊销); // } // 如果验证通过可以删除旧的刷新令牌实现单次使用增强安全可选 // 4. 根据用户ID查询最新的用户信息因为用户角色可能已变更 User user userService.findById(userId); if (user null) { throw new UnauthorizedException(用户不存在); } // 5. 生成新的访问令牌和刷新令牌 MapString, Object extraClaims new HashMap(); extraClaims.put(roles, user.getRoles()); String newAccessToken jwtUtil.generateAccessToken(userId, user.getUsername(), extraClaims); String newRefreshToken jwtUtil.generateRefreshToken(userId); // 6. 更新服务端存储的刷新令牌如果实现了存储的话 // refreshTokenService.updateRefreshToken(userId, newRefreshToken); // 7. 返回新的令牌对 LoginResponse response new LoginResponse(); response.setAccessToken(newAccessToken); response.setRefreshToken(newRefreshToken); response.setExpiresIn(jwtProperties.getAccessTokenExpireTime()); // ... 设置userInfo return ApiResponse.success(response); } }刷新令牌接口的核心安全点在于服务端状态校验。虽然JWT本身可自验证但为了能够主动吊销令牌如用户退出登录、修改密码后使旧令牌失效我们需要将刷新令牌在服务端存一份比如在数据库中关联用户ID并在刷新时校验其有效性。这是一种“有状态”与“无状态”的折中方案用很小的状态管理代价换来了重要的安全控制能力。7.2 实现令牌黑名单/白名单机制访问令牌Access Token由于有效期短通常不单独做服务端存储校验。但如果你有“立即踢人下线”这种强需求可以引入一个短期的“黑名单”或“令牌版本号”机制。黑名单用户退出登录或修改密码时将尚未过期的访问令牌的唯一标识如jti声明JWT ID存入Redis并设置一个略长于令牌剩余有效期的TTL。在过滤器中除了验证签名和过期时间还要检查该令牌是否在黑名单中。令牌版本号在用户表中增加一个tokenVersion字段。生成JWT时将tokenVersion放入声明。当用户修改密码或强制下线时递增其tokenVersion。在验证JWT时不仅验证签名和过期还要从声明中取出tokenVersion与数据库中的当前版本比对不一致则拒绝。这两种方式都引入了少量的服务端状态但实现了对JWT生命周期的主动管理。7.3 前端令牌存储与自动携带的最佳实践前端拿到令牌后如何安全地存储和自动附加到请求中也很重要。存储位置访问令牌可以存储在内存Vue/React的状态管理如Vuex/Pinia、Redux或localStorage/sessionStorage。存储在内存更安全防XSS但页面刷新会丢失。存储在localStorage持久化好但需防范XSS攻击窃取。权衡之下对于大多数SPA将Access Token存入localStorage是常见做法但必须确保你的网站没有XSS漏洞。刷新令牌如前所述最好通过HttpOnly、Secure、SameSiteStrict的Cookie来存储这样JavaScript无法访问能有效防御XSS。自动携带使用Axios等HTTP库的请求拦截器自动从localStorage读取Access Token并添加到Authorization头。// axios实例配置 import axios from axios; const apiClient axios.create({ baseURL: process.env.VUE_APP_API_BASE_URL, }); // 请求拦截器 apiClient.interceptors.request.use( (config) { const token localStorage.getItem(access_token); if (token) { config.headers.Authorization Bearer ${token}; } return config; }, (error) { return Promise.reject(error); } );令牌刷新与请求重试在响应拦截器中检查如果接口返回401令牌过期则尝试调用刷新令牌接口获取新令牌然后用新令牌重试失败的请求。这个过程对上层业务透明。// 响应拦截器 - 处理令牌刷新 let isRefreshing false; let failedQueue []; apiClient.interceptors.response.use( (response) response, async (error) { const originalRequest error.config; if (error.response?.status 401 !originalRequest._retry) { if (isRefreshing) { // 如果正在刷新将失败的请求加入队列 return new Promise((resolve, reject) { failedQueue.push({ resolve, reject }); }).then(() { return apiClient(originalRequest); }).catch(err { return Promise.reject(err); }); } originalRequest._retry true; isRefreshing true; try { // 调用刷新令牌接口 const refreshToken getRefreshTokenFromCookie(); // 从Cookie获取 const { data } await axios.post(/api/auth/refresh, { refreshToken }); // 存储新的访问令牌 localStorage.setItem(access_token, data.data.accessToken); // 可能更新Cookie中的刷新令牌 setRefreshTokenToCookie(data.data.refreshToken); // 重试所有队列中的请求 failedQueue.forEach(pending pending.resolve()); // 重试当前请求 return apiClient(originalRequest); } catch (refreshError) { // 刷新失败清空令牌跳转到登录页 failedQueue.forEach(pending pending.reject(refreshError)); localStorage.removeItem(access_token); // 清除刷新令牌Cookie clearRefreshTokenCookie(); window.location.href /login; return Promise.reject(refreshError); } finally { isRefreshing false; failedQueue []; } } return Promise.reject(error); } );这套前端拦截器逻辑能较好地处理令牌过期的场景实现无感刷新提升用户体验。8. 常见问题、排查技巧与进阶思考在实际开发和上线后你肯定会遇到各种各样的问题。下面是我总结的一些典型场景和排查思路。8.1 问题排查速查表问题现象可能原因排查步骤与解决方案登录成功但访问接口返回401 Unauthorized1. 请求头未携带Token或格式错误。2. Token已过期。3. Token签名验证失败密钥不一致。4. 过滤器配置路径有误未拦截到请求。1. 检查浏览器开发者工具的Network标签确认请求头是否有Authorization: Bearer token注意Bearer后有一个空格。2. 检查Token的exp声明是否已过当前时间。可以在 jwt.io 解码查看。3. 对比签发和验证时使用的jwt.secret是否完全一致。检查是否有环境变量覆盖问题。4. 检查Spring Security的配置确保目标接口路径不在permitAll()范围内且过滤器已正确添加。接口访问返回403 Forbidden1. 用户角色/权限不足。2. SecurityContext中未设置认证信息。1. 检查JWT的roles声明是否包含访问该接口所需的权限。在Controller方法上使用PreAuthorize(hasRole(ADMIN))进行测试。2. 在过滤器中打断点确认SecurityContextHolder.getContext().getAuthentication()是否成功设置。检查Token解析过程是否抛出异常被捕获。刷新令牌接口调用失败1. 刷新令牌过期。2. 刷新令牌类型错误误用了Access Token。3. 服务端存储的刷新令牌状态无效如已被使用或吊销。1. 检查刷新令牌的exp。2. 在刷新令牌的Payload中加入”type”: “refresh”声明并在验证时检查。3. 如果实现了服务端存储检查数据库或缓存中该令牌是否存在且状态为有效。生产环境密钥泄露风险密钥硬编码在配置文件并提交到代码仓库。立即轮换密钥并通过环境变量、配置中心如Nacos, Apollo或云服务商密钥管理服务如AWS KMS,阿里云KMS来管理密钥。所有服务器使用统一的密钥源。如何让已颁发的JWT立即失效JWT本身无法作废。采用7.2中提到的黑名单或令牌版本号机制。退出登录或修改密码时将旧Token标识加入黑名单设置合理TTL或递增用户的tokenVersion。8.2 性能与安全进阶思考Token过长问题JWT的Payload会Base64编码后直接放在Token里如果放入过多信息如用户完整信息、权限列表过长会导致Token体积膨胀增加每次请求的带宽消耗。解决方案是Payload只存放最核心的用户标识如userId权限等信息在服务端验证时通过userId实时查询缓存获取。这是一种空间换时间的权衡。注销与踢人下线这是JWT的经典难题。除了上面提到的黑名单/版本号还可以采用“短期令牌频繁刷新”的策略。将Access Token有效期设置得非常短如15分钟并强制前端定期如每10分钟使用Refresh Token刷新。当需要踢人时服务端只需吊销用户的Refresh Token即可旧的Access Token会在很短时间内自然过期。防止令牌盗用与重放攻击使用HTTPS这是最基本的要求防止令牌在传输中被窃听。绑定客户端指纹在生成Token时可以加入客户端的某些指纹信息如IP地址、User-Agent的哈希值验证时进行比对。但这会影响用户体验如用户切换网络IP会导致Token失效。设置合理的过期时间缩短Access Token有效期降低泄露后的风险窗口。多端登录与并发管理一个用户可能在手机、电脑同时登录。如果使用单一的Refresh Token在一端刷新后另一端的Refresh Token就会失效如果实现了单次使用。更复杂的场景需要维护一个Refresh Token列表并可能提供“查看登录设备”、“远程注销”等功能这时的状态管理就更加复杂。8.3 与Spring Security的深度集成我们的例子中只是简单使用了Spring Security的上下文。实际上Spring Security提供了强大的注解支持如PreAuthorize,PostAuthorize,Secured等可以非常优雅地在方法级别进行权限控制。RestController RequestMapping(/api/admin) public class AdminController { GetMapping(/users) PreAuthorize(hasRole(ADMIN)) // 必须拥有ROLE_ADMIN角色 public ApiResponseListUser listUsers() { // ... } DeleteMapping(/user/{id}) PreAuthorize(hasAuthority(USER_DELETE)) // 必须拥有USER_DELETE权限 public ApiResponseVoid deleteUser(PathVariable Long id) { // ... } }要启用这些注解需要在Security配置类上加上EnableGlobalMethodSecurity(prePostEnabled true, securedEnabled true)。这样结合JWT过滤器设置的权限信息就能实现细粒度的接口授权。集成JWT到SpringBoot项目远不止是引入一个库、写一个工具类那么简单。它涉及到认证架构的选择、安全与性能的权衡、前后端的协同以及生产环境的运维。从简单的HS256对称加密到复杂的RS256非对称加密与微服务网关集成从无状态的令牌到有状态的吊销管理每一步都需要根据你的实际业务场景做出决策。我分享的这个方案是一个兼顾了实用性、安全性和可扩展性的起点。在实际项目中你可能会遇到更复杂的需求比如多因素认证、OAuth2.0集成等但理解了JWT和Spring Security这套核心机制再去扩展其他功能就会游刃有余。最关键的是始终把安全放在第一位妥善管理你的密钥并设计好令牌的生命周期。