当前位置：首页 > news >正文

SpringBoot 3.0 + Security 6.0 + JWT：构建现代化Java API安全认证骨架

news 2026/8/8 4:03:54

1. 项目缘起：为什么是SpringBoot 3.0 + Security 6.0 + JWT？

如果你正在构建一个现代化的Java后端服务，尤其是微服务架构下的API，那么“认证”和“授权”是你绕不开的两座大山。过去，我们可能随手写个Filter拦截一下，或者用Shiro框架，但随着Spring生态的日益强大和标准化，Spring Security已经成为了事实上的Java安全框架标准。而JWT（JSON Web Token）作为无状态、可自解析的令牌，在前后端分离、分布式系统中几乎成了身份凭证的代名词。

最近接手一个从零开始的新项目，技术栈选型直接锚定了最新的SpringBoot 3.0和Spring Security 6.0。这不仅仅是追新，更是因为SpringBoot 3.0基于Java 17+和Spring Framework 6，带来了性能提升、更好的GraalVM原生镜像支持等现代特性。而Spring Security 6.0则是一次重大的API重构和理念更新，它更强调函数式、声明式的配置风格，废弃了大量旧的、冗长的配置方式，代码更简洁，意图更清晰。

但当我真正开始整合时，发现网络上大量的教程还停留在SpringBoot 2.x + Security 5.x的时代，很多配置示例直接搬过来会报错，或者达不到预期效果。特别是Security 6.0对WebSecurityConfigurerAdapter的彻底废弃，让很多习惯了继承这个类来配置安全规则的老手一时无从下手。同时，如何将JWT无状态认证优雅地、安全地融入这套新体系中，也需要一番摸索。

所以，这篇文章就是这次“踩坑”与“填坑”的完整记录。我会从一个真实的项目视角，带你一步步搭建一个基于SpringBoot 3.0、Spring Security 6.0和JWT的、生产可用的认证授权骨架。不止是“怎么做”，更重要的是“为什么这么做”，以及那些官方文档不会告诉你的细节和坑点。

2. 环境搭建与核心依赖选型

工欲善其事，必先利其器。第一步，我们得把项目架子搭起来，并理清各个核心组件的作用和版本。

2.1 初始化SpringBoot 3.0项目

使用Spring Initializr（https://start.spring.io/）或者IDE（如IntelliJ IDEA）的Spring Initializr功能创建项目。关键选择如下：

Project: Maven 或 Gradle（本文以Maven为例）
Language: Java
Spring Boot: 3.0.x (最新稳定版，如3.0.6)
Project Metadata: 按需填写Group、Artifact
Packaging: Jar (微服务标准)
Java: 17 或 21 (SpringBoot 3.0最低要求Java 17)

在Dependencies部分，我们至少需要添加：

Spring Web: 构建Web应用的基础。
Spring Security: 安全框架核心。
Lombok: 减少样板代码，非必须但强烈推荐。
Spring Boot DevTools: 开发热重启，提升效率。

生成的pom.xml基础依赖部分如下：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.0.6</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> <scope>runtime</scope> <optional>true</optional> </dependency> <!-- 其他依赖后续逐步添加 --> </dependencies>

2.2 JWT库的选择：JJWT vs java-jwt

Spring Security本身不提供JWT的实现，我们需要引入第三方库。主流的有两个：jjwt(由Auth0维护) 和java-jwt(同样由Auth0维护，但更现代)。这里我推荐使用java-jwt，因为它的API设计更符合现代Java习惯，对Java 8+的日期时间API支持更好，并且是Auth0当前主推的库。

在pom.xml中添加依赖：

<dependency> <groupId>com.auth0</groupId> <artifactId>java-jwt</artifactId> <version>4.4.0</version> <!-- 请检查最新版本 --> </dependency>

注意：很多老教程用的是jjwt(io.jsonwebtoken:jjwt-api/impl/jackson)，那个库的API风格较旧。如果你看到代码里大量使用Jwts.builder().setSubject()这种链式调用，那大概率是jjwt。java-jwt的构建方式更直接，如JWT.create().withSubject()。本文后续代码均基于java-jwt。

2.3 数据库与ORM选型（可选但建议）

虽然认证的核心逻辑不强制依赖数据库，但用户信息、角色权限通常需要持久化。这里以最常用的Spring Data JPA+MySQL为例，添加依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <!-- 或者使用 H2 内存数据库用于测试 --> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency>

在application.yml或application.properties中配置数据源。至此，最基本的环境就准备好了。接下来，我们将进入核心的安全配置环节，这是与旧版本差异最大、也最容易出错的地方。

3. 重构安全配置：告别WebSecurityConfigurerAdapter

Spring Security 6.0 最大的变化之一就是彻底移除了WebSecurityConfigurerAdapter这个我们用了很多年的配置基类。新的推荐方式是使用基于组件的、函数式的配置风格。这起初会让人不习惯，但用熟了会发现代码更清晰、更灵活。

3.1 创建Security配置类：@Bean是核心

我们不再继承任何类，而是创建一个普通的配置类，并用@Configuration和@EnableWebSecurity注解标记。所有的配置都通过@Bean方法来定义。

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; 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 { // 核心配置：安全过滤器链 @Bean public SecurityFilterChain filterChain(HttpSecurity http, JwtAuthenticationFilter jwtAuthFilter) throws Exception { http // 禁用CSRF（因为使用无状态的JWT，CSRF防护通常不需要） .csrf(csrf -> csrf.disable()) // 配置会话管理为无状态 .sessionManagement(session -> session .sessionCreationPolicy(SessionCreationPolicy.STATELESS) ) // 配置请求授权规则 .authorizeHttpRequests(auth -> auth // 公开接口：登录、注册、Swagger文档等 .requestMatchers("/api/auth/login", "/api/auth/register", "/swagger-ui/**", "/v3/api-docs/**").permitAll() // 需要特定角色的接口 .requestMatchers("/api/admin/**").hasRole("ADMIN") .requestMatchers("/api/user/**").hasAnyRole("USER", "ADMIN") // 其他所有请求都需要认证 .anyRequest().authenticated() ) // 在UsernamePasswordAuthenticationFilter之前添加我们自定义的JWT过滤器 .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class); return http.build(); } // 密码编码器Bean：必须提供，用于密码校验 @Bean public PasswordEncoder passwordEncoder() { // 使用BCrypt强哈希算法，这是目前最安全且推荐的方式 return new BCryptPasswordEncoder(); } }

关键点解析：

SecurityFilterChainBean：这是安全配置的核心。我们通过HttpSecurity对象来配置所有安全规则。注意参数注入的JwtAuthenticationFilter，这是我们后面要实现的自定义JWT过滤器。
函数式DSL：.csrf(csrf -> csrf.disable())这种写法就是Security 6.0引入的Lambda DSL（领域特定语言）。它让配置的意图更明确，避免了之前大量调用.and()的链式写法，代码可读性更高。
无状态会话：SessionCreationPolicy.STATELESS是关键。它告诉Spring Security不要创建和使用HttpSession，我们的认证状态完全由JWT维护。这是实现RESTful无状态API的前提。
请求匹配：.requestMatchers()方法替代了旧的.antMatchers()和.mvcMatchers()。它更强大，可以匹配路径、HTTP方法等。注意角色名前面不需要加ROLE_前缀，hasRole("ADMIN")内部会自动处理。
过滤器顺序：.addFilterBefore()确保我们的JWT过滤器在Spring Security默认的用户名密码认证过滤器之前执行。这样，如果请求头中有有效的JWT，就可以直接完成认证，无需走到表单登录逻辑。

3.2 自定义用户详情服务：连接数据库

Spring Security需要知道如何根据用户名加载用户信息（包括密码、角色等）。我们需要实现UserDetailsService接口。

首先，定义用户实体和角色（这里使用简单的单表结构，实际项目可能更复杂）：

import jakarta.persistence.*; 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.Collection; import java.util.List; import java.util.stream.Collectors; @Entity @Table(name = "sys_user") @Data public class User implements UserDetails { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(unique = true, nullable = false) private String username; @Column(nullable = false) private String password; private String email; // 用户角色，假设用逗号分隔的字符串存储，如 "ROLE_USER,ROLE_ADMIN" private String roles; // 实现UserDetails接口的方法 @Override public Collection<? extends GrantedAuthority> getAuthorities() { if (roles == null || roles.isEmpty()) { return List.of(); } // 将逗号分隔的角色字符串转换为GrantedAuthority集合 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; } }

然后，创建UserDetailsService的实现：

import lombok.RequiredArgsConstructor; 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 @RequiredArgsConstructor public class UserDetailsServiceImpl implements UserDetailsService { private final UserRepository userRepository; // 假设有对应的JPA Repository @Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { User user = userRepository.findByUsername(username) .orElseThrow(() -> new UsernameNotFoundException("用户不存在: " + username)); // 注意：这里返回的User对象就是我们上面定义的实体类，它已经实现了UserDetails // Spring Security会调用它的getAuthorities()等方法获取权限信息 return user; } }

实操心得：在getAuthorities()方法中，我直接解析了数据库中的角色字符串。在实际生产环境中，角色和权限的管理可能更复杂，比如有独立的角色表、权限表，并通过中间表关联。那时，你需要在这里编写更复杂的逻辑，从数据库关联查询出该用户的所有权限点（GrantedAuthority）。一个常见的做法是，GrantedAuthority的字符串格式可以是ROLE_ADMIN这样的角色，也可以是user:delete这样的具体权限。

4. JWT工具类设计与令牌管理

有了安全框架的基础，接下来是JWT的核心：如何生成、解析和验证令牌。我们将创建一个工具类来封装这些操作。

4.1 配置JWT密钥与过期时间

首先，在application.yml中配置JWT相关的参数。绝对不要将密钥硬编码在代码中！

jwt: secret: your-256-bit-secret-key-must-be-very-long-and-secure # 用于签名的密钥，至少32位以上 expiration: 86400000 # 令牌过期时间（毫秒），这里设置24小时 token-prefix: "Bearer " # 令牌在HTTP头中的前缀 header: Authorization # HTTP头名称

然后，创建一个配置类来读取这些值：

import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; @Component @ConfigurationProperties(prefix = "jwt") @Data public class JwtProperties { private String secret; private long expiration; private String tokenPrefix; private String header; }

4.2 实现JWT工具类

这是整个认证流程的发动机。我们使用java-jwt库。

import com.auth0.jwt.JWT; import com.auth0.jwt.JWTVerifier; import com.auth0.jwt.algorithms.Algorithm; import com.auth0.jwt.exceptions.JWTVerificationException; import com.auth0.jwt.interfaces.DecodedJWT; import lombok.RequiredArgsConstructor; import org.springframework.stereotype.Component; import java.util.Date; @Component @RequiredArgsConstructor public class JwtUtil { private final JwtProperties jwtProperties; /** * 生成JWT令牌 * @param username 用户名 * @param authorities 权限集合 * @return 签名的JWT字符串 */ public String generateToken(String username, Collection<? extends GrantedAuthority> authorities) { // 1. 将权限集合转换为字符串列表，存入JWT的`auth`声明 List<String> authorityList = authorities.stream() .map(GrantedAuthority::getAuthority) .collect(Collectors.toList()); // 2. 计算过期时间 Date now = new Date(); Date expiryDate = new Date(now.getTime() + jwtProperties.getExpiration()); // 3. 创建并签名JWT return JWT.create() .withSubject(username) // 标准声明：主题，通常放用户名 .withClaim("auth", authorityList) // 自定义声明：存放权限 .withIssuedAt(now) // 签发时间 .withExpiresAt(expiryDate) // 过期时间 .sign(Algorithm.HMAC256(jwtProperties.getSecret())); // 使用HMAC256算法和密钥签名 } /** * 从令牌中解析用户名 */ public String getUsernameFromToken(String token) { DecodedJWT decodedJWT = decodeToken(token); return decodedJWT.getSubject(); } /** * 从令牌中解析权限列表 */ public List<GrantedAuthority> getAuthoritiesFromToken(String token) { DecodedJWT decodedJWT = decodeToken(token); // 从自定义声明`auth`中获取权限字符串列表 List<String> authorityList = decodedJWT.getClaim("auth").asList(String.class); if (authorityList == null) { return new ArrayList<>(); } return authorityList.stream() .map(SimpleGrantedAuthority::new) .collect(Collectors.toList()); } /** * 验证令牌是否有效（签名正确且未过期） */ public boolean validateToken(String token) { try { // 构建验证器 JWTVerifier verifier = JWT.require(Algorithm.HMAC256(jwtProperties.getSecret())) .build(); verifier.verify(token); // 验证失败会抛出异常 return true; } catch (JWTVerificationException e) { // 日志记录验证失败详情，便于调试 // log.error("JWT token验证失败: {}", e.getMessage()); return false; } } /** * 解码令牌（内部方法，供其他方法调用） */ private DecodedJWT decodeToken(String token) { // 注意：这里只是解码，不验证签名！验证应在validateToken中完成。 // 直接解码用于从有效的令牌中提取信息。 return JWT.decode(token); } }

关键点与避坑指南：

密钥安全：jwt.secret必须是足够长且随机的字符串。在生产环境，应该从环境变量或配置中心获取，绝不能提交到代码仓库。
算法选择：Algorithm.HMAC256是使用对称密钥的算法，简单高效。如果你的服务需要多个服务验证同一个JWT（在微服务中），可以考虑使用非对称算法（如RSA），一个服务用私钥签发，其他服务用公钥验证。
声明（Claims）：withSubject是标准声明。我自定义了一个auth声明来存储权限列表。你也可以存放用户ID、邮箱等其他必要信息，但切忌存放敏感信息（如密码），因为JWT payload是Base64编码，可以被解码查看。
验证与解码分离：validateToken方法做了完整的验证（签名+过期）。而getUsernameFromToken等方法内部调用的decodeToken只是解码。这是一个重要的设计：确保在从请求中拿到token后，先调用validateToken，验证通过后再解码获取用户信息。如果直接解码一个无效或过期的token，会抛出异常。
异常处理：validateToken中捕获了JWTVerificationException，并返回false。在实际过滤器中，我们需要根据这个结果来决定是放行还是拒绝请求。

5. 实现JWT认证过滤器：连接Security与令牌

这是整个流程的桥梁。这个过滤器的职责是：拦截每个请求，从Authorization头中提取JWT，验证其有效性，如果有效，则根据令牌中的信息构造一个Authentication对象，并放入SecurityContextHolder，这样Spring Security就知道当前请求的用户是谁、有什么权限。

5.1 创建JwtAuthenticationFilter

import jakarta.servlet.FilterChain; import jakarta.servlet.ServletException; import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse; import lombok.RequiredArgsConstructor; import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.security.core.userdetails.UserDetailsService; 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 @RequiredArgsConstructor public class JwtAuthenticationFilter extends OncePerRequestFilter { private final JwtUtil jwtUtil; private final UserDetailsService userDetailsService; private final JwtProperties jwtProperties; @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // 1. 从请求头中获取JWT令牌 String jwt = getJwtFromRequest(request); // 2. 验证令牌 if (StringUtils.hasText(jwt) && jwtUtil.validateToken(jwt)) { // 3. 从令牌中获取用户名 String username = jwtUtil.getUsernameFromToken(jwt); // 4. 检查Security上下文中是否已有认证信息（防止重复认证） if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) { // 5. 根据用户名加载用户详情（从数据库） UserDetails userDetails = userDetailsService.loadUserByUsername(username); // 6. 从令牌中获取权限（避免每次查数据库） // 注意：这里直接从JWT的`auth`声明中还原权限，确保JWT生成时包含了正确的权限。 // 如果权限可能动态变化，则需要重新查询数据库，但这会牺牲无状态性。 Collection<? extends GrantedAuthority> authorities = jwtUtil.getAuthoritiesFromToken(jwt); // 7. 创建Authentication对象 UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(userDetails, null, authorities); authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request)); // 8. 将Authentication对象存入SecurityContext SecurityContextHolder.getContext().setAuthentication(authentication); } } // 9. 继续执行过滤器链 filterChain.doFilter(request, response); } /** * 从Authorization请求头中提取Bearer Token */ private String getJwtFromRequest(HttpServletRequest request) { String bearerToken = request.getHeader(jwtProperties.getHeader()); if (StringUtils.hasText(bearerToken) && bearerToken.startsWith(jwtProperties.getTokenPrefix())) { // 去掉"Bearer "前缀，返回纯Token字符串 return bearerToken.substring(jwtProperties.getTokenPrefix().length()); } return null; } }

5.2 过滤器工作流程与关键决策

这个过滤器是认证的核心，有几个关键设计决策需要理解：

为什么用OncePerRequestFilter？它确保在一次请求中，这个过滤器只被执行一次，避免重复处理。
UserDetailsService.loadUserByUsername的调用是必须的吗？不一定。如果我们完全信任JWT中携带的信息（用户名和权限），并且权限不会在令牌有效期内发生变化，我们可以直接使用JWT中的信息构建Authentication对象，而无需查询数据库。这能极大提升性能，是JWT无状态的优势。但是，这带来了安全权衡：如果用户权限被修改，或者账号被禁用，在旧令牌过期前，系统依然会认为其拥有旧权限。这就需要引入令牌黑名单或较短的令牌有效期等机制来补偿。
本文的折中方案：我在这里仍然调用了UserDetailsService，主要是为了获取完整的UserDetails对象（其中包含账号是否启用、是否过期等状态）。权限则直接从JWT中获取，避免了为权限再次查询数据库。这是一种兼顾安全校验和性能的常见做法。如果你追求极致的无状态和性能，并且有其他方式（如广播消息使旧令牌失效）来处理权限变更，可以跳过数据库查询。
SecurityContextHolder的作用：它是一个线程局部变量（ThreadLocal），存储了当前请求线程的认证信息。一旦在这里设置了Authentication，后续的控制器、服务层都可以通过SecurityContextHolder.getContext().getAuthentication()来获取当前用户信息，也可以通过@AuthenticationPrincipal注解注入。

6. 构建认证API：登录、注册与令牌刷新

安全框架和过滤器准备好了，现在需要提供入口让用户获取JWT。我们将创建几个RESTful API。

6.1 用户注册与密码加密

首先，创建一个注册的DTO和控制器。

// RegisterRequest.java @Data public class RegisterRequest { @NotBlank private String username; @NotBlank private String password; private String email; } // AuthController.java @RestController @RequestMapping("/api/auth") @RequiredArgsConstructor public class AuthController { private final UserRepository userRepository; private final PasswordEncoder passwordEncoder; @PostMapping("/register") public ResponseEntity<?> register(@Valid @RequestBody RegisterRequest request) { // 1. 检查用户名是否已存在 if (userRepository.existsByUsername(request.getUsername())) { return ResponseEntity.badRequest().body("用户名已存在"); } // 2. 创建用户实体，密码必须加密存储！ User user = new User(); user.setUsername(request.getUsername()); user.setPassword(passwordEncoder.encode(request.getPassword())); // 关键！ user.setEmail(request.getEmail()); user.setRoles("ROLE_USER"); // 默认角色 // 3. 保存用户 userRepository.save(user); return ResponseEntity.ok("注册成功"); } }

核心安全原则：永远不要明文存储密码！passwordEncoder.encode()方法使用BCrypt算法生成一个加盐的哈希值，即使两个用户密码相同，哈希值也不同，能有效抵御彩虹表攻击。在登录校验时，Spring Security会用相同的PasswordEncoder来比对。

6.2 用户登录与JWT签发

登录接口是JWT的签发端。

// LoginRequest.java @Data public class LoginRequest { @NotBlank private String username; @NotBlank private String password; } // LoginResponse.java @Data @AllArgsConstructor public class LoginResponse { private String token; private String type = "Bearer"; private Long expiresIn; // 过期时间戳（毫秒） private String username; private List<String> authorities; } // 在AuthController中继续添加 private final AuthenticationManager authenticationManager; private final JwtUtil jwtUtil; @PostMapping("/login") public ResponseEntity<?> login(@Valid @RequestBody LoginRequest request) { try { // 1. 使用Spring Security的AuthenticationManager进行认证 // 它会自动调用我们配置的UserDetailsService和PasswordEncoder Authentication authentication = authenticationManager.authenticate( new UsernamePasswordAuthenticationToken(request.getUsername(), request.getPassword()) ); // 2. 认证成功，将Authentication对象存入SecurityContext（可选，但建议） SecurityContextHolder.getContext().setAuthentication(authentication); // 3. 获取当前用户详情和权限 UserDetails userDetails = (UserDetails) authentication.getPrincipal(); Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities(); // 4. 生成JWT令牌 String jwt = jwtUtil.generateToken(userDetails.getUsername(), authorities); // 5. 构造响应 List<String> authorityList = authorities.stream() .map(GrantedAuthority::getAuthority) .collect(Collectors.toList()); LoginResponse response = new LoginResponse( jwt, "Bearer", System.currentTimeMillis() + jwtUtil.getExpiration(), // 计算过期时间戳 userDetails.getUsername(), authorityList ); return ResponseEntity.ok(response); } catch (BadCredentialsException e) { // 用户名或密码错误 return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("用户名或密码错误"); } catch (Exception e) { // 其他认证异常 return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("登录失败"); } }

关键点解析：

AuthenticationManager：这是Spring Security的核心认证接口。我们通过它来触发完整的认证流程。它会使用我们注入的UserDetailsService来加载用户，并用PasswordEncoder来校验密码。
认证流程：authenticationManager.authenticate()调用成功后，返回的Authentication对象已经是“已认证”状态，其中包含了从数据库加载的UserDetails。这意味着用户名和密码是正确的。
令牌生成时机：只有在密码验证通过后，我们才用该用户的用户名和权限生成JWT。确保令牌的合法性基于成功的密码认证。

6.3 令牌刷新机制

JWT一旦签发，在过期前无法主动使其失效（除非使用黑名单，但这破坏了无状态性）。因此，常见的做法是使用“刷新令牌”机制。

访问令牌：短期有效（如30分钟），用于API访问。
刷新令牌：长期有效（如7天），仅用于获取新的访问令牌，不能直接访问API。

实现思路：

登录时，同时返回access_token和refresh_token。
提供一个/api/auth/refresh接口，接收有效的refresh_token，返回新的access_token。
refresh_token可以存储在后端数据库或Redis中，并关联用户ID，这样可以实现单点登录、强制下线等功能。

由于篇幅所限，这里给出一个简化的刷新接口概念，不包含完整的双令牌存储逻辑：

@PostMapping("/refresh") public ResponseEntity<?> refreshToken(@RequestHeader("Authorization") String refreshToken) { // 1. 验证refreshToken的有效性（可能需要单独的密钥或存储校验） // 2. 从refreshToken中解析出用户标识（如user id） // 3. 根据用户标识查询最新的权限信息（可选） // 4. 生成新的access_token // 5. 返回新的access_token // 注意：refreshToken本身也应该有有效期和更新机制 return ResponseEntity.ok("新的访问令牌"); }

实现完整的刷新令牌机制需要考虑更多安全细节，如刷新令牌的存储、轮换、撤销等，建议参考OAuth 2.0的Refresh Token流程。

7. 权限控制进阶：方法级安全与自定义注解

除了在SecurityFilterChain中配置URL路径的权限，我们经常需要在方法级别进行更细粒度的控制。Spring Security提供了强大的方法级安全支持。

7.1 启用全局方法安全

在主配置类或安全配置类上添加@EnableMethodSecurity注解。

@Configuration @EnableWebSecurity @EnableMethodSecurity // 启用方法级安全注解 public class SecurityConfig { // ... 其他配置 }

7.2 使用@PreAuthorize和@PostAuthorize

现在，你可以在Service层或Controller层的方法上使用注解了。

@Service public class UserService { // 要求拥有ADMIN角色才能执行此方法 @PreAuthorize("hasRole('ADMIN')") public List<User> getAllUsers() { return userRepository.findAll(); } // 要求拥有`user:delete`权限，或者自己是该用户的所有者 @PreAuthorize("hasAuthority('user:delete') or #id == authentication.principal.id") public void deleteUser(Long id) { // authentication.principal 可以获取到当前的UserDetails对象 userRepository.deleteById(id); } // 方法执行后校验返回值，仅允许返回自己的用户信息 @PostAuthorize("returnObject.username == authentication.principal.username") public User getUserProfile(Long id) { return userRepository.findById(id).orElseThrow(); } }

@PreAuthorize：在方法执行前进行权限校验。@PostAuthorize：在方法执行后进行权限校验，可以访问方法的返回值（returnObject）。SpEL表达式：注解内的字符串是Spring表达式语言（SpEL），非常强大。authentication.principal就是当前认证的主体（我们的User对象）。#id可以引用方法的参数。

7.3 自定义权限校验注解

如果你觉得SpEL表达式写起来麻烦，或者有复杂的、可复用的业务权限逻辑，可以自定义注解。

例如，自定义一个@RequiresPermission注解：

@Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @PreAuthorize("@permissionChecker.hasPermission(#request, authentication)") public @interface RequiresPermission { String value(); // 权限字符串，如 `user:create` }

然后创建一个PermissionCheckerBean来处理逻辑：

@Component("permissionChecker") public class PermissionChecker { public boolean hasPermission(String requiredPermission, Authentication authentication) { UserDetails userDetails = (UserDetails) authentication.getPrincipal(); // 这里可以实现复杂的权限逻辑，比如检查角色、部门权限等 return userDetails.getAuthorities().stream() .anyMatch(auth -> auth.getAuthority().equals(requiredPermission)); } }

使用方式：

@RequiresPermission("user:create") public User createUser(User user) { return userRepository.save(user); }

这样，代码的可读性和可维护性就大大提高了。

8. 测试、部署与生产环境考量

8.1 编写集成测试

使用@SpringBootTest和@AutoConfigureMockMvc来测试你的安全API。

@SpringBootTest @AutoConfigureMockMvc class AuthControllerTest { @Autowired private MockMvc mockMvc; @Test @WithMockUser(username = "testuser", roles = {"USER"}) // 模拟一个已认证用户 void testAuthenticatedEndpoint() throws Exception { mockMvc.perform(get("/api/user/profile")) .andExpect(status().isOk()); } @Test void testLoginSuccess() throws Exception { // 1. 先确保数据库有该用户（可以在@BeforeEach中准备数据） // 2. 模拟登录请求 String requestBody = "{\"username\":\"admin\",\"password\":\"password\"}"; mockMvc.perform(post("/api/auth/login") .contentType(MediaType.APPLICATION_JSON) .content(requestBody)) .andExpect(status().isOk()) .andExpect(jsonPath("$.token").exists()); } @Test void testAccessProtectedApiWithoutToken() throws Exception { mockMvc.perform(get("/api/user/profile")) .andExpect(status().isForbidden()); // 或 isUnauthorized，取决于配置 } }

8.2 生产环境配置要点

密钥管理：jwt.secret必须使用强随机字符串，并通过环境变量（如JWT_SECRET）或云平台的密钥管理服务注入，绝对不要写在配置文件中提交到代码库。
HTTPS：JWT在网络上传输，必须使用HTTPS来防止令牌被窃听。
令牌存储：前端通常将JWT存储在localStorage或sessionStorage中，但这有XSS风险。更安全的方式是使用HttpOnly的Cookie，但需要妥善处理跨域问题。这是一个安全与便利的权衡。
注销与令牌过期：由于JWT是无状态的，服务端无法直接“注销”一个令牌。通常的做法是：
- 设置较短的访问令牌有效期（如15-30分钟）。
- 使用刷新令牌机制来获取新令牌。
- 如果需要立即失效，可以维护一个很小的令牌黑名单（在Redis中存储已注销但未过期的令牌ID），但这会引入状态。另一种方案是改变签名密钥，使所有旧令牌立即失效（影响所有用户）。
监控与日志：记录认证失败、权限拒绝的日志，便于审计和安全分析。但注意不要在日志中打印完整的JWT。
CORS配置：如果前端与API不同源，需要在Spring Boot中配置CORS。

@Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); CorsConfiguration config = new CorsConfiguration(); config.setAllowCredentials(true); // 允许携带凭证（如Cookie） config.addAllowedOrigin("https://your-frontend-domain.com"); // 允许的源，生产环境要具体指定 config.addAllowedHeader("*"); config.addAllowedMethod("*"); source.registerCorsConfiguration("/**", config); return new CorsFilter(source); }

8.3 常见问题排查

问题：登录成功，但访问API返回403。
- 排查：检查JWT过滤器是否正确配置并添加到过滤器链。检查令牌是否被正确地从请求头中提取（前缀Bearer和空格）。检查SecurityContextHolder中是否成功设置了Authentication。检查URL路径的权限配置（.authorizeHttpRequests）是否匹配。
问题：自定义的UserDetailsService没有被调用。
- 排查：确保你的UserDetailsService实现类被@Service注解，并且Spring能够扫描到。在SecurityConfig中，AuthenticationManager会自动使用它。
问题：BCrypt密码编码器校验失败。
- 排查：确保注册时和登录时使用的是同一个PasswordEncoderBean。检查数据库中的密码字段长度是否足够长（BCrypt哈希值通常60位以上）。
问题：Swagger UI或Actuator端点被拦截。
- 排查：在SecurityFilterChain的.requestMatchers()中，为开发或监控相关的路径添加.permitAll()，例如：.requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/actuator/health").permitAll()。

经过以上八个部分的拆解与实践，一个基于SpringBoot 3.0、Spring Security 6.0和JWT的现代化安全后端骨架就搭建完成了。这套组合拳提供了从用户认证、权限管理到API保护的一站式解决方案。关键在于理解Spring Security 6.0基于组件的配置哲学，以及JWT无状态认证与有状态会话之间的权衡。在实际项目中，你可能还需要根据业务需求，集成OAuth 2.0、细化权限模型、加入审计日志等，但这个骨架已经为你打下了坚实、安全且现代的基础。

查看全文

http://www.jsqmd.com/news/1350403/