Spring Boot + JWT 实现无状态认证

1. JWTJWTJSON Web Token是一种开放标准RFC 7519用于在网络应用环境间安全地将信息作为 JSON 对象传输。JWT 是目前最流行的跨域认证解决方案特别适合前后端分离的架构。1.1 JWT 的结构JWT 由三部分组成用点号.分隔xxxxx.yyyyy.zzzzz │ │ │ │ │ └── Signature签名 │ └───────── Payload负载 └──────────────── Header头部Header包含令牌类型和签名算法{alg:HS256,typ:JWT}Payload包含声明claims如用户信息、过期时间等{username:zhangsan,iat:1516239022,exp:1516242622}Signature使用密钥对前两部分进行签名确保令牌不被篡改1.2 JWT 的优势优势说明无状态服务器不需要保存会话信息令牌自包含用户信息跨域支持天然支持 CORS适合前后端分离架构扩展性强令牌中可以携带自定义信息安全性高使用签名防止篡改支持过期时间2. 项目架构┌─────────────────────────────────────────────────────────────┐ │ 客户端 (Vue 3) │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │ │ │ 登录请求 │ │ 存储 Token │ │ 请求携带 Token │ │ │ └──────────────┘ └──────────────┘ └────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ │ HTTP/REST ▼ ┌─────────────────────────────────────────────────────────────┐ │ 服务端 (Spring Boot) │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │ │ │ 生成 Token │ │ 验证 Token │ │ 授权访问资源 │ │ │ │ (JwtUtil) │ │ (JwtFilter) │ │ (SecurityConfig) │ │ │ └──────────────┘ └──────────────┘ └────────────────────┘ │ └─────────────────────────────────────────────────────────────┘3. 核心组件实现3.1 JwtUtil - JWT 工具类负责生成、解析和验证 JWT 令牌。ComponentpublicclassJwtUtil{// 使用 HS256 算法生成密钥privatefinalKeykeyKeys.secretKeyFor(SignatureAlgorithm.HS256);AutowiredprivateAppConfigappConfig;/** * 生成 JWT 令牌 * param username 用户名 * return JWT 令牌字符串 */publicStringgenerateToken(Stringusername){MapString,ObjectclaimsnewHashMap();claims.put(username,username);returnJwts.builder().setClaims(claims)// 设置自定义声明.setSubject(username)// 设置主题用户名.setIssuedAt(newDate())// 设置签发时间.setExpiration(newDate(System.currentTimeMillis()getExpirationTime()))// 设置过期时间.signWith(key)// 使用密钥签名.compact();// 生成令牌}/** * 从令牌中提取用户名 * param token JWT 令牌 * return 用户名 */publicStringextractUsername(Stringtoken){ClaimsclaimsJwts.parserBuilder().setSigningKey(key)// 设置验证密钥.build().parseClaimsJws(token)// 解析令牌.getBody();// 获取声明体returnclaims.getSubject();}/** * 验证令牌是否有效 * param token JWT 令牌 * return 是否有效 */publicbooleanvalidateToken(Stringtoken){try{Jwts.parserBuilder().setSigningKey(key).build().parseClaimsJws(token);returntrue;// 解析成功令牌有效}catch(Exceptione){returnfalse;// 解析失败令牌无效或过期}}}关键点说明使用Keys.secretKeyFor(SignatureAlgorithm.HS256)生成安全的密钥setExpiration()设置令牌过期时间增强安全性validateToken()捕获所有异常确保令牌验证的健壮性3.2 JwtFilter - JWT 过滤器拦截请求验证 JWT 令牌的有效性。ComponentpublicclassJwtFilterextendsOncePerRequestFilter{privatestaticfinalLoggerloggerLoggerFactory.getLogger(JwtFilter.class);AutowiredprivateJwtUtiljwtUtil;OverrideprotectedvoiddoFilterInternal(HttpServletRequestrequest,HttpServletResponseresponse,FilterChainchain)throwsServletException,IOException{// 从请求头中获取令牌StringauthorizationHeaderrequest.getHeader(Authorization);Stringtokennull;Stringusernamenull;// 检查授权头提取 Bearer Tokenif(authorizationHeader!nullauthorizationHeader.startsWith(Bearer )){tokenauthorizationHeader.substring(7);// 去掉 Bearer 前缀try{usernamejwtUtil.extractUsername(token);}catch(Exceptione){logger.error(Error extracting username from token: {},e.getMessage());}}// 验证令牌并设置认证上下文if(username!nullSecurityContextHolder.getContext().getAuthentication()null){if(jwtUtil.validateToken(token)){// 创建认证令牌UsernamePasswordAuthenticationTokenauthTokennewUsernamePasswordAuthenticationToken(username,null,null);authToken.setDetails(newWebAuthenticationDetailsSource().buildDetails(request));// 设置安全上下文SecurityContextHolder.getContext().setAuthentication(authToken);}}chain.doFilter(request,response);}}关键点说明继承OncePerRequestFilter确保每个请求只过滤一次从Authorization头中提取Bearer Token使用SecurityContextHolder设置认证信息供后续业务使用3.3 SecurityConfig - 安全配置配置 Spring Security定义安全规则和认证方式。ConfigurationEnableWebSecuritypublicclassSecurityConfig{AutowiredprivateJwtFilterjwtFilter;BeanpublicSecurityFilterChainsecurityFilterChain(HttpSecurityhttp)throwsException{http// 配置 CORS.cors(cors-cors.configurationSource(corsConfigurationSource()))// 禁用 CSRF前后端分离不需要.csrf(csrf-csrf.disable())// 配置请求授权.authorizeHttpRequests(authorize-authorize// 允许匿名访问的路径.requestMatchers(/api/v1/users/register,/api/v1/users/login,/api/v1/users/security-question,/api/v1/users/reset-password,/api/v1/captcha/**).permitAll()// AI 相关接口允许匿名访问.requestMatchers(/api/v1/ai-analysis/**,/api/v1/ai-assistant/**).permitAll()// Swagger 文档允许访问.requestMatchers(/swagger-ui.html,/swagger-ui/**,/v3/api-docs/**).permitAll()// 其他请求需要认证.anyRequest().authenticated())// 添加 JWT 过滤器.addFilterBefore(jwtFilter,UsernamePasswordAuthenticationFilter.class);returnhttp.build();}BeanpublicCorsConfigurationSourcecorsConfigurationSource(){CorsConfigurationconfigurationnewCorsConfiguration();configuration.setAllowedOrigins(Arrays.asList(http://localhost:5173));configuration.setAllowedMethods(Arrays.asList(GET,POST,PUT,DELETE,OPTIONS));configuration.setAllowedHeaders(Arrays.asList(Content-Type,Authorization));configuration.setAllowCredentials(true);UrlBasedCorsConfigurationSourcesourcenewUrlBasedCorsConfigurationSource();source.registerCorsConfiguration(/**,configuration);returnsource;}}关键点说明禁用 CSRF 保护前后端分离架构不需要配置白名单路径允许匿名访问登录、注册等接口使用addFilterBefore()将 JWT 过滤器添加到 Spring Security 过滤器链中4. 认证流程4.1 登录流程1. 用户发送登录请求 POST /api/v1/users/login { username: zhangsan, password: password123, captcha: a3f8 } 2. UserController 接收请求验证用户名密码 3. 验证成功调用 JwtUtil.generateToken(username) 生成 JWT 4. 返回响应包含 JWT 令牌 { success: true, data: { token: eyJhbGciOiJIUzI1NiIs..., username: zhangsan } } 5. 前端存储 TokenlocalStorage 或 sessionStorage4.2 请求认证流程1. 用户访问受保护资源请求头携带 Token Authorization: Bearer eyJhbGciOiJIUzI1NiIs... 2. JwtFilter 拦截请求从 Header 提取 Token 3. 验证 Token 有效性签名、过期时间 4. 验证通过设置 SecurityContext 认证信息 5. 请求到达 Controller执行业务逻辑 6. 返回业务数据5. 代码示例5.1 登录接口实现RestControllerRequestMapping(/api/v1/users)publicclassUserController{AutowiredprivateUserServiceuserService;AutowiredprivateJwtUtiljwtUtil;privateBCryptPasswordEncoderpasswordEncodernewBCryptPasswordEncoder();PostMapping(/login)publicUserResponselogin(ValidRequestBodyUserLoginRequestrequest,HttpServletRequesthttpRequest){// 1. 验证验证码Stringcaptcharequest.getCaptcha();if(!validateCaptcha(captcha,httpRequest.getSession())){thrownewRuntimeException(验证码错误);}// 2. 验证用户名密码UseruseruserService.login(request.getUsername(),request.getPassword());// 3. 生成 JWT TokenStringtokenjwtUtil.generateToken(user.getUsername());// 4. 构建响应UserResponseresponsenewUserResponse();response.setToken(token);response.setUsername(user.getUsername());response.setEmail(user.getEmail());// ... 其他用户信息returnresponse;}}5.2 受保护接口示例RestControllerRequestMapping(/api/v1/food-records)publicclassFoodRecordController{GetMappingpublicListFoodRecordgetRecords(RequestParamStringusername){// 由于 JwtFilter 已经验证过 Token// 这里可以直接获取当前认证用户AuthenticationauthSecurityContextHolder.getContext().getAuthentication();StringcurrentUserauth.getName();// 验证只能查询自己的记录if(!currentUser.equals(username)){thrownewRuntimeException(无权访问其他用户的数据);}returnfoodRecordService.findByUsername(username);}}6. 前端集成6.1 登录后存储 Token// 登录成功保存 Tokenconstloginasync(credentials){constresponseawaitapi.post(/api/v1/users/login,credentials);const{token,username}response.data;// 存储到 localStoragelocalStorage.setItem(token,token);localStorage.setItem(username,username);returnresponse.data;};6.2 请求拦截器添加 Token// Axios 请求拦截器api.interceptors.request.use(config{consttokenlocalStorage.getItem(token);if(token){config.headers.AuthorizationBearer${token};}returnconfig;},errorPromise.reject(error));6.3 响应拦截器处理 401// Axios 响应拦截器api.interceptors.response.use(responseresponse.data,error{if(error.response?.status401){// Token 过期或无效清除存储并跳转登录页localStorage.removeItem(token);window.location.href/;}returnPromise.reject(error);});7. 安全注意事项7.1 密钥管理生产环境密钥应存储在环境变量或配置中心不要硬编码密钥轮换定期更换密钥旧令牌会自然失效密钥强度使用足够强度的密钥HS256 自动生成7.2 令牌安全风险防护措施XSS 攻击使用 httpOnly Cookie 存储令牌或做好 XSS 防护CSRF 攻击前后端分离天然免疫 CSRF但仍需验证 Origin令牌泄露设置合理的过期时间通常 1-24 小时重放攻击结合时间戳和随机数或使用短期令牌7.3 传输安全生产环境必须使用 HTTPS敏感接口增加额外的验证如密码修改需要旧密码