最近在游戏社区和开发者群里经常看到有玩家因为账号安全问题而头疼。尤其是找“代肝”帮忙完成游戏任务时账号密码一给心里就七上八下总担心对方会不会乱动自己的装备、资源甚至用外挂导致封号。这种“把钥匙交给陌生人”的感觉确实让人没有安全感。其实在现代软件架构中尤其是在需要精细化权限控制的场景下比如微服务调用、第三方应用集成有一个非常成熟且优雅的解决方案——通行证Token机制。它完美解决了“既要授权又要限制”的难题。本文将从一个开发者的视角系统性地拆解通行证以常见的 JWT 为例是什么、为什么需要它、以及如何从零开始在你的项目中实现一套安全可控的授权体系。无论你是后端开发者想加固API还是对安全机制感兴趣的爱好者都能从中获得一套可直接复用的实战方案。1. 通行证Token机制核心概念与价值在深入代码之前我们首先要理解通行证机制要解决的核心问题以及它相比传统方案的优势。1.1 什么是通行证Token你可以把通行证想象成一张限时、限范围的门票。用户或客户端在通过身份验证如输入正确的用户名密码后认证服务器不会直接返回一个长期的“万能钥匙”如Session ID而是签发一张包含特定信息的加密票据这就是Token。这张“门票”上会写明持有人是谁用户ID。门票的有效期过期时间。允许进入哪些区域访问权限/角色。由谁签发发行方。客户端获得这张Token后在后续的每一次请求中只需要在HTTP请求头通常是Authorization头里出示这张“门票”资源服务器验证门票真伪和有效性后即可决定是否放行以及允许进行何种操作。整个过程资源服务器无需再去查询中央数据库来确认用户状态实现了无状态Stateless的认证。1.2 为什么需要它对比传统Session的劣势在Token流行之前最常用的方式是Session-Cookie机制。用户登录后服务器在内存或Redis中创建一个Session对象并将唯一的Session ID通过Cookie返回给浏览器。浏览器后续请求自动携带此Cookie服务器通过Session ID查找对应的Session来维持用户状态。这种方式在单体应用时代很有效但在分布式、微服务架构下暴露出诸多问题扩展性差Session通常存储在单台服务器的内存或一个集中的Redis中。当用户量激增、服务需要水平扩展时Session的共享和同步会成为瓶颈和单点故障。CSRF攻击风险基于Cookie的机制容易受到跨站请求伪造攻击需要额外引入Token如CSRF Token来防御增加了复杂度。不适合多端与第三方对于原生App、小程序或需要对外提供API的场景Cookie机制并不友好。Token则可以轻松通过HTTP Header传递。无法实现细粒度授权Session通常只标识“谁登录了”而Token如JWT的Payload中可以携带丰富的用户声明Claims如角色、权限列表方便进行更精细的授权判断。“代肝”问题的映射Session机制就像你把家门钥匙密码复制了一把交给代肝。他有了钥匙就能进入你家登录账号并且只要不修改密码服务器不使能Session他理论上可以一直自由进出。而Token机制则是你给代肝一张仅能打开游戏机特定资源且晚上8点自动失效过期时间的临时门禁卡。他无法进入你的卧室其他敏感功能时间一到卡就作废安全可控得多。1.3 JWT一种流行的Token实现标准JSON Web Token (JWT) 是目前最流行的Token实现标准。它结构清晰、自包含、易于传输。一个JWT通常看起来像这样eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c它由三部分组成用点.分隔Header头部声明Token类型和签名算法如{“alg”: “HS256”, “typ”: “JWT”}经过Base64Url编码。Payload负载存放实际需要传递的数据也就是“声明Claims”如用户ID、过期时间等。同样是Base64Url编码。注意Payload只是编码并非加密所以不要存放密码等敏感信息。Signature签名对前两部分的签名用于验证Token在传输过程中是否被篡改。签名需要用一个密钥Secret来生成。服务端通过验证签名即可确信这个Token是它自己签发的且内容未被修改。这种自包含的特性使得验证方无需查询数据库即可完成认证极大地提升了性能。2. 环境准备与项目搭建我们将使用Spring Boot框架来构建一个演示项目因为它能快速搭建Web应用并且有完善的Security和JWT支持。同时为了模拟“资源服务器”我们会创建两个简单的API端点。2.1 技术栈与版本说明JDK: 17 或 21 (推荐17长期支持版本)Spring Boot: 3.2.x构建工具: Maven 或 Gradle (本文使用Maven)核心依赖:spring-boot-starter-web: Web应用基础spring-boot-starter-security: 安全框架jjwt-api,jjwt-impl,jjwt-jackson: JWT创建和解析库 (我们使用jjwt)lombok: 简化POJO代码可选但推荐重要提示Spring Boot和JWT库版本迭代较快以下示例代码基于常见稳定版本编写。在实际项目中请根据你的Spring Boot版本选择兼容的jjwt依赖。你可以通过 Maven中央仓库 搜索jjwt查看最新版本。2.2 初始化Spring Boot项目你可以通过 Spring Initializr 网站或IDE如IntelliJ IDEA的Spring Initializr功能快速创建项目。选择以下依赖Spring WebSpring SecurityLombok生成项目后解压并用IDE打开。pom.xml文件应该已经包含了基础依赖我们需要手动添加JWT相关的依赖。2.3 添加JWT依赖打开pom.xml文件在dependencies部分添加以下内容!-- JWT 依赖 (请检查最新版本) -- dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.12.3/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.12.3/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.12.3/version scoperuntime/scope /dependency版本注意jjwt0.12.x 版本API与老版本如0.11.x有较大变化更加简洁安全。本文示例基于0.12.3编写。如果你的项目使用老版本需要调整API调用方式。3. 核心组件设计与实现我们的目标是构建一个最小化的认证授权流程用户通过/api/auth/login接口提交用户名密码登录。服务端验证通过后生成一个JWT Token返回给客户端。客户端访问受保护资源如/api/profile时在请求头中携带此Token。服务端有一个过滤器Filter会拦截请求验证Token的有效性签名、过期时间等。验证通过后将用户信息存入安全上下文后续控制器即可获取当前用户信息并进行业务处理。下面我们分步骤实现这些核心组件。3.1 用户实体与登录请求/响应DTO首先定义简单的用户实体和用于传输数据的对象。// 文件路径src/main/java/com/example/demo/dto/LoginRequest.java package com.example.demo.dto; import lombok.Data; Data public class LoginRequest { private String username; private String password; }// 文件路径src/main/java/com/example.demo/dto/LoginResponse.java package com.example.demo.dto; import lombok.Data; Data public class LoginResponse { private String token; // 返回给客户端的JWT Token private String type Bearer; // Token类型通常是Bearer private Long expiresIn; // 过期时间秒 public LoginResponse(String token, Long expiresIn) { this.token token; this.expiresIn expiresIn; } }为了简化我们不连接真实数据库用一个内存中的用户服务来模拟。// 文件路径src/main/java/com/example/demo/service/UserService.java package com.example.demo.service; import com.example.demo.model.User; import jakarta.annotation.PostConstruct; import org.springframework.security.crypto.password.PasswordEncoder; import org.springframework.stereotype.Service; import java.util.HashMap; import java.util.Map; import java.util.Optional; Service public class UserService { // 模拟用户存储 private final MapString, User userStore new HashMap(); private final PasswordEncoder passwordEncoder; public UserService(PasswordEncoder passwordEncoder) { this.passwordEncoder passwordEncoder; } PostConstruct public void initUsers() { // 初始化一个测试用户密码是“123456”但存储的是加密后的密文 userStore.put(player1, new User(player1, passwordEncoder.encode(123456), ROLE_USER)); userStore.put(admin1, new User(admin1, passwordEncoder.encode(admin123), ROLE_ADMIN,ROLE_USER)); } public OptionalUser findByUsername(String username) { return Optional.ofNullable(userStore.get(username)); } }对应的用户模型// 文件路径src/main/java/com/example/demo/model/User.java package com.example.demo.model; import lombok.AllArgsConstructor; import lombok.Data; import org.springframework.security.core.GrantedAuthority; import org.springframework.security.core.authority.SimpleGrantedAuthority; import org.springframework.security.core.userdetails.UserDetails; import java.util.Arrays; import java.util.Collection; import java.util.stream.Collectors; Data AllArgsConstructor public class User implements UserDetails { private String username; private String password; private String roles; // 用逗号分隔的角色字符串如 ROLE_USER,ROLE_ADMIN Override public Collection? extends GrantedAuthority getAuthorities() { // 将角色字符串转换为Spring Security认可的权限对象 return Arrays.stream(roles.split(,)) .map(SimpleGrantedAuthority::new) .collect(Collectors.toList()); } Override public boolean isAccountNonExpired() { return true; } Override public boolean isAccountNonLocked() { return true; } Override public boolean isCredentialsNonExpired() { return true; } Override public boolean isEnabled() { return true; } }3.2 JWT工具类生成与解析Token这是整个机制的核心工具类负责Token的创建、签名和验证。// 文件路径src/main/java/com/example/demo/util/JwtUtil.java package com.example.demo.util; import io.jsonwebtoken.Claims; import io.jsonwebtoken.Jwts; import io.jsonwebtoken.security.Keys; import org.springframework.beans.factory.annotation.Value; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.stereotype.Component; import javax.crypto.SecretKey; import java.util.Date; import java.util.HashMap; import java.util.Map; import java.util.function.Function; Component public class JwtUtil { // 从配置文件中读取密钥和过期时间 Value(${jwt.secret}) private String secret; // 一个足够长且复杂的字符串用于生成签名密钥 Value(${jwt.expiration}) private Long expiration; // Token过期时间单位毫秒 // 根据secret字符串生成安全的密钥 private SecretKey getSigningKey() { return Keys.hmacShaKeyFor(secret.getBytes()); } // 生成Token public String generateToken(UserDetails userDetails) { MapString, Object claims new HashMap(); // 可以将用户角色等信息也放入claims claims.put(roles, userDetails.getAuthorities()); return createToken(claims, userDetails.getUsername()); } private String createToken(MapString, Object claims, String subject) { Date now new Date(); Date expiryDate new Date(now.getTime() expiration); return Jwts.builder() .claims(claims) // 设置自定义声明 .subject(subject) // 设置主题通常是用户名 .issuedAt(now) // 签发时间 .expiration(expiryDate) // 过期时间 .signWith(getSigningKey(), Jwts.SIG.HS256) // 使用HS256算法和密钥签名 .compact(); } // 从Token中解析用户名 public String extractUsername(String token) { return extractClaim(token, Claims::getSubject); } // 从Token中解析过期时间 public Date extractExpiration(String token) { return extractClaim(token, Claims::getExpiration); } // 通用的解析Claim方法 public T T extractClaim(String token, FunctionClaims, T claimsResolver) { final Claims claims extractAllClaims(token); return claimsResolver.apply(claims); } // 解析Token获取所有Claims private Claims extractAllClaims(String token) { return Jwts.parser() .verifyWith(getSigningKey()) // 用相同的密钥验证签名 .build() .parseSignedClaims(token) .getPayload(); } // 验证Token是否过期 private Boolean isTokenExpired(String token) { return extractExpiration(token).before(new Date()); } // 验证Token是否有效未过期且用户名匹配 public Boolean validateToken(String token, UserDetails userDetails) { final String username extractUsername(token); return (username.equals(userDetails.getUsername()) !isTokenExpired(token)); } }关键点解释Value注解从application.properties中读取配置。我们需要在配置文件中定义jwt.secret和jwt.expiration。Keys.hmacShaKeyFor是jjwt 0.12.x推荐的安全密钥生成方式它确保了密钥的强度。Jwts.builder()链式调用构建TokensignWith指定了签名算法和密钥。Jwts.parser()用于解析和验证TokenverifyWith是验证签名的关键。3.3 认证过滤器拦截请求并验证Token我们需要一个过滤器在请求到达控制器之前检查请求头中是否包含有效的JWT Token。// 文件路径src/main/java/com/example/demo/filter/JwtAuthenticationFilter.java package com.example.demo.filter; import com.example.demo.service.UserService; import com.example.demo.util.JwtUtil; import jakarta.servlet.FilterChain; import jakarta.servlet.ServletException; import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.lang.NonNull; import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.security.web.authentication.WebAuthenticationDetailsSource; import org.springframework.stereotype.Component; import org.springframework.util.StringUtils; import org.springframework.web.filter.OncePerRequestFilter; import java.io.IOException; Component public class JwtAuthenticationFilter extends OncePerRequestFilter { Autowired private JwtUtil jwtUtil; Autowired private UserService userService; Override protected void doFilterInternal(NonNull HttpServletRequest request, NonNull HttpServletResponse response, NonNull FilterChain filterChain) throws ServletException, IOException { // 1. 从请求头中获取Token String jwt parseJwt(request); // 2. 如果Token存在且有效 if (StringUtils.hasText(jwt) jwtUtil.validateToken(jwt)) { // 从Token中解析用户名 String username jwtUtil.extractUsername(jwt); // 根据用户名加载用户详情 UserDetails userDetails userService.loadUserByUsername(username); // 创建Authentication对象并设置到SecurityContext中 UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken( userDetails, null, // credentials 通常为null因为认证已完成 userDetails.getAuthorities()); authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request)); SecurityContextHolder.getContext().setAuthentication(authentication); } // 3. 继续执行后续过滤器链 filterChain.doFilter(request, response); } private String parseJwt(HttpServletRequest request) { String headerAuth request.getHeader(Authorization); if (StringUtils.hasText(headerAuth) headerAuth.startsWith(Bearer )) { // 去掉 Bearer 前缀获取纯粹的Token字符串 return headerAuth.substring(7); } return null; } // 辅助方法验证Token有效性简化版仅检查过期和用户存在 // 注意这里需要一个能从Token直接验证有效性的方法我们在JwtUtil中补充 // 实际项目中validateToken可能需要结合数据库查询用户状态如是否被禁用 }注意上面的jwtUtil.validateToken(jwt)方法需要重载因为它之前需要UserDetails参数。我们修改JwtUtil增加一个只验证Token本身签名和过期的方法。在JwtUtil.java中添加// 验证Token签名和过期时间不验证用户 public Boolean validateToken(String token) { try { // 如果解析成功且未过期则返回true extractAllClaims(token); return !isTokenExpired(token); } catch (Exception e) { // 签名无效、格式错误等都会抛出异常 return false; } }同时我们需要在UserService中实现loadUserByUsername方法让它继承UserDetailsService。修改UserService.javapackage com.example.demo.service; // ... 其他import import org.springframework.security.core.userdetails.UserDetails; import org.springframework.security.core.userdetails.UserDetailsService; import org.springframework.security.core.userdetails.UsernameNotFoundException; import org.springframework.stereotype.Service; Service public class UserService implements UserDetailsService { // 实现接口 // ... 原有代码不变 Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { return findByUsername(username) .orElseThrow(() - new UsernameNotFoundException(User not found with username: username)); } }3.4 安全配置整合Spring Security与JWT过滤器现在我们需要配置Spring Security告诉它使用我们的JWT过滤器并放行登录等公开接口。// 文件路径src/main/java/com/example/demo/config/SecurityConfig.java package com.example.demo.config; import com.example.demo.filter.JwtAuthenticationFilter; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.authentication.AuthenticationManager; import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.config.http.SessionCreationPolicy; import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; import org.springframework.security.crypto.password.PasswordEncoder; import org.springframework.security.web.SecurityFilterChain; import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter; Configuration EnableWebSecurity public class SecurityConfig { Autowired private JwtAuthenticationFilter jwtAuthenticationFilter; Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http // 禁用CSRF因为JWT是无状态的不依赖Cookie .csrf(csrf - csrf.disable()) // 设置Session管理为无状态 .sessionManagement(session - session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) // 配置请求授权规则 .authorizeHttpRequests(auth - auth // 公开接口无需认证 .requestMatchers(/api/auth/**).permitAll() .requestMatchers(/error).permitAll() // 允许错误端点访问 // 其他所有请求都需要认证 .anyRequest().authenticated() ) // 在UsernamePasswordAuthenticationFilter之前添加我们的JWT过滤器 .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class); return http.build(); } // 密码编码器用于加密用户密码 Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } // 暴露AuthenticationManager Bean用于手动认证如果需要 Bean public AuthenticationManager authenticationManager(AuthenticationConfiguration authConfig) throws Exception { return authConfig.getAuthenticationManager(); } }配置解读csrf().disable(): JWT通常通过Header传递不依赖Cookie因此可以禁用CSRF防护以简化配置。sessionCreationPolicy(SessionCreationPolicy.STATELESS): 这是实现无状态API的关键告诉Spring Security不要创建和使用HttpSession。addFilterBefore: 将我们的JwtAuthenticationFilter添加到Spring Security过滤器链中位置在UsernamePasswordAuthenticationFilter之前。这样我们的过滤器会先尝试从请求头中提取并验证JWT如果成功就直接完成认证无需走默认的表单登录流程。3.5 认证控制器提供登录接口最后我们创建一个控制器来处理登录请求验证用户凭证并返回JWT Token。// 文件路径src/main/java/com/example/demo/controller/AuthController.java package com.example.demo.controller; import com.example.demo.dto.LoginRequest; import com.example.demo.dto.LoginResponse; import com.example.demo.service.UserService; import com.example.demo.util.JwtUtil; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.http.ResponseEntity; import org.springframework.security.authentication.AuthenticationManager; import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; import org.springframework.security.core.Authentication; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/api/auth) public class AuthController { Autowired private AuthenticationManager authenticationManager; Autowired private JwtUtil jwtUtil; Autowired private UserService userService; PostMapping(/login) public ResponseEntity? login(RequestBody LoginRequest loginRequest) { // 1. 使用Spring Security的AuthenticationManager进行认证 Authentication authentication authenticationManager.authenticate( new UsernamePasswordAuthenticationToken( loginRequest.getUsername(), loginRequest.getPassword() ) ); // 2. 认证成功从Authentication中获取UserDetails UserDetails userDetails (UserDetails) authentication.getPrincipal(); // 3. 为userDetails生成JWT Token String jwtToken jwtUtil.generateToken(userDetails); // 4. 返回Token给客户端 // 假设过期时间是1小时3600000毫秒这个值应该与JwtUtil中读取的配置一致 Long expiresIn 3600L; // 单位秒从配置读取更好 return ResponseEntity.ok(new LoginResponse(jwtToken, expiresIn)); } }3.6 受保护的资源控制器创建一个简单的受保护接口用于测试Token是否生效。// 文件路径src/main/java/com/example/demo/controller/ProfileController.java package com.example.demo.controller; import org.springframework.security.core.Authentication; import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.HashMap; import java.util.Map; RestController RequestMapping(/api/profile) public class ProfileController { GetMapping public MapString, Object getCurrentUserProfile() { // 从SecurityContext中获取当前认证的用户信息 Authentication authentication SecurityContextHolder.getContext().getAuthentication(); String username authentication.getName(); Object authorities authentication.getAuthorities(); MapString, Object profile new HashMap(); profile.put(message, Hello, username ! You have accessed a protected resource.); profile.put(username, username); profile.put(authorities, authorities); profile.put(timestamp, System.currentTimeMillis()); return profile; } }3.7 应用配置文件在src/main/resources/application.properties中添加JWT相关配置# JWT配置 jwt.secretThisIsASuperSecretKeyThatIsAtLeast64BytesLongForHS512AlgorithmButWeUseHS256HereMakeItLongEnough jwt.expiration3600000 # Token过期时间单位毫秒 (1小时) # 可选关闭Spring Security的默认登录页面使错误更清晰 spring.security.filter.dispatcher-typesasync,error,request重要警告jwt.secret在生产环境中绝对不能使用如此简单的字符串也不应该硬编码在配置文件中。必须使用足够长且复杂的随机字符串并通过环境变量或配置中心如Apollo注入。泄露此密钥意味着攻击者可以伪造任意Token。4. 完整实战运行与测试现在所有组件都已就绪。让我们启动应用并进行测试。4.1 启动应用运行Spring Boot主类通常名为DemoApplication。在控制台看到类似Started DemoApplication in x.xxx seconds的日志说明应用启动成功。4.2 测试登录接口获取Token使用curl、Postman 或任何你喜欢的API测试工具。请求示例 (POST /api/auth/login):curl --location http://localhost:8080/api/auth/login \ --header Content-Type: application/json \ --data-raw { username: player1, password: 123456 }预期响应:{ token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...很长的一串字符..., type: Bearer, expiresIn: 3600 }恭喜你已成功获取到JWT Token。复制这个token值用于下一步。4.3 测试受保护接口使用Token使用上一步获取的Token访问受保护的/api/profile接口。请求示例 (GET /api/profile):curl --location http://localhost:8080/api/profile \ --header Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... # 替换为你的真实Token预期响应:{ message: Hello, player1! You have accessed a protected resource., username: player1, authorities: [ { authority: ROLE_USER } ], timestamp: 1712345678901 }这证明你的Token是有效的过滤器成功解析了Token并将用户信息设置到了安全上下文中控制器能够获取到当前用户。4.4 测试无效或过期的Token使用错误的Token修改Header中的Token字符串任意一个字符。不携带Token直接请求/api/profile。使用过期的Token可以修改jwt.expiration为一个很小的值如1000毫秒重新登录获取Token等待一秒后再次请求。以上情况服务端都应该返回401 Unauthorized状态码因为Spring Security的过滤器链拒绝了未认证的请求。5. 进阶实现基于角色的访问控制 (RBAC)上面的例子只做到了“认证”Authentication即识别用户是谁。在实际的“代肝”场景中我们还需要“授权”Authorization即控制用户能做什么。例如普通玩家只能查看自己的角色信息而“代肝”可能被授予“仅可完成日常任务”的权限管理员则拥有所有权限。我们可以利用JWT Payload中存储的角色信息来实现。5.1 在Token中存储角色我们的JwtUtil.generateToken方法已经将用户权限放入了claims。现在我们在过滤器中解析出来并设置到Authentication对象中。修改JwtAuthenticationFilter.doFilterInternal方法中创建Authentication的部分// ... 在验证Token有效且用户存在之后 ... UserDetails userDetails userService.loadUserByUsername(username); // 从Token中解析角色/权限可选因为userDetails中已有 // 这里我们直接使用userDetails中的权限 UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken( userDetails, null, userDetails.getAuthorities()); // 权限集合已在此 // ...5.2 在控制器或服务层进行权限校验Spring Security提供了多种方式进行权限校验。方法级安全控制在启动类或配置类上添加EnableMethodSecurity注解。在控制器方法上使用PreAuthorize注解。修改SecurityConfig在类上添加注解Configuration EnableWebSecurity EnableMethodSecurity // 启用方法级安全控制 public class SecurityConfig { // ... 原有代码 }然后创建两个测试接口// 文件路径src/main/java/com/example/demo/controller/TestController.java package com.example.demo.controller; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/api/test) public class TestController { GetMapping(/user) PreAuthorize(hasRole(USER)) // 需要ROLE_USER角色 public String userEndpoint() { return This is a USER-only endpoint.; } GetMapping(/admin) PreAuthorize(hasRole(ADMIN)) // 需要ROLE_ADMIN角色 public String adminEndpoint() { return This is an ADMIN-only endpoint.; } GetMapping(/task) PreAuthorize(hasAuthority(TASK_EXECUTE)) // 需要特定权限非角色 public String taskEndpoint() { return This endpoint requires TASK_EXECUTE permission.; } }测试用player1(角色ROLE_USER) 的Token访问/api/test/user成功。用player1的Token访问/api/test/admin应返回403 Forbidden。用admin1(角色ROLE_ADMIN,ROLE_USER) 的Token访问/api/test/admin成功。这样我们就实现了基于角色的精细授权。你可以为“代肝”创建一个特殊的角色如ROLE_PROXY并只赋予其调用特定任务接口的权限从而完美解决“乱动手脚”的问题。6. 常见问题与排查思路在实现和集成JWT的过程中你可能会遇到以下典型问题问题现象可能原因排查步骤与解决方案登录成功但访问受保护接口返回4011. Token未正确放置在请求头中。2. Token格式错误缺少Bearer前缀或有多余空格。3. 过滤器配置顺序有误未生效。4. Token已过期。1. 检查请求头Authorization: Bearer your_token格式。2. 在过滤器的parseJwt方法中打印headerAuth确认提取正确。3. 检查SecurityConfig中addFilterBefore的配置。4. 检查服务器时间是否准确Token过期时间设置是否合理。Token验证通过但获取不到用户权限1. 生成Token时未正确存入权限信息。2. 从Token解析权限后未正确设置到Authentication对象。1. 检查JwtUtil.generateToken方法确保claims包含了权限。2. 在过滤器中确认userDetails.getAuthorities()不为空并已传递给UsernamePasswordAuthenticationToken。jjwt相关类找不到或方法签名错误依赖版本不兼容特别是jjwt0.12.x 与 0.11.x API变化大。1. 检查pom.xml中jjwt的版本确保三个artifact版本一致。2. 对照官方文档或本文示例更新API调用方式。0.12.x 使用Jwts.builder().claims()和Jwts.parser().verifyWith()。Spring Security 配置不生效1. 配置类未被扫描到。2. 多个Security配置冲突。3. 请求路径匹配规则错误。1. 确保配置类在Spring Boot主类所在包或其子包下。2. 检查是否有其他WebSecurityConfigurerAdapter或SecurityFilterChainBean。3. 使用requestMatchers(“/api/auth/**”).permitAll()确保登录接口被放行。密码验证失败1. 存储的密码与输入的明文密码加密方式不一致。2.UserService中初始化的密码未加密。1. 确保UserService.initUsers中使用passwordEncoder.encode(“rawPassword”)存储密码。2. 登录时Spring Security的AuthenticationManager会自动使用配置的PasswordEncoder进行比对。7. 生产环境最佳实践与安全加固将JWT用于生产环境必须考虑以下安全性和工程化实践密钥管理绝对不要将密钥硬编码在代码或配置文件中提交到代码仓库。使用环境变量、云服务商的密钥管理服务如AWS KMS, Azure Key Vault或配置中心来管理密钥。定期轮换密钥。轮换后旧的Token会立即失效需要用户重新登录。Token有效期与刷新设置较短的访问令牌Access Token有效期如15-30分钟降低泄露风险。引入刷新令牌Refresh Token机制。刷新令牌有效期较长如7天存储于服务端如数据库用于获取新的访问令牌。这样即使访问令牌泄露攻击窗口也很短。提供令牌吊销接口用于用户主动登出或安全事件发生时使特定令牌失效。Payload安全切勿在Payload中存放敏感信息如密码、手机号。JWT的Payload只是Base64编码可以被轻易解码查看。只存放必要的用户标识如userID和授权信息如角色。传输安全务必使用HTTPS。在HTTP下传输Token相当于明文传递“门禁卡”会被中间人攻击窃取。可以考虑将Token存储在HttpOnly的Cookie中防范XSS但需妥善处理CSRF防护。对于纯API场景使用Authorization Header是更常见的选择。日志与监控记录Token的签发、使用和失效事件特别是登录失败、Token验证失败、权限拒绝等安全事件便于审计和异常排查。监控Token的使用频率异常高频次的请求可能意味着Token被盗用。针对“代肝”场景的特别设计范围Scope限制在Token的Payload中加入scope字段明确此Token只能访问哪些API如scope: [“task:read”, “task:execute”]资源服务器校验该字段。IP绑定签发Token时可记录用户当时的IP地址。验证Token时检查请求IP是否与签发IP一致适用于IP相对固定的场景增加盗用难度。一次性令牌对于极其敏感的操作如交易、修改密码不应使用通用的JWT而应使用一次性验证码或时间戳签名令牌。通过本文从概念到实战的完整梳理你应该已经掌握了如何使用JWT这套“通行证”机制来构建安全、无状态、可扩展的API认证授权体系。它不仅适用于解决“代肝”这类第三方受限访问问题更是现代微服务、前后端分离架构中身份管理的基石。理解其原理谨慎实践安全规范你就能在项目中游刃有余地驾驭这套强大的安全工具。