Spring Security 6+ JWT 配置正确用法详解

Spring Security 6.x 已废弃 OAuth2ResourceServerConfigurer::jwt 等返回子配置器的方法，统一采用 Lambda 风格的 Customizer 方式配置 JWT 认证，本文详解迁移步骤与最佳实践。

先说几个核心判断。Spring Security 6.x 对 JWT 配置这块做了不小的调整，直接砍掉了 OAuth2ResourceServerConfigurer::jwt 这类“返回子配置器”的传统写法，全面转向 Lambda + Customizer 的风格。如果你还在用旧方法写配置，编译时看到的那个 deprecation 警告，就是提醒你该改一改了。这篇内容正好把迁移的关键步骤和最佳实践拆解清楚。

在 Spring Security 6.0 及更高版本中，整个安全配置 DSL 其实经历了一次重大的“内部清洗”。所有那些通过 .and() 链式调用的老路子，以及像 http.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt) 这样返回独立 Configurer 实例的调用方式，都被正式标记为废弃。背后的原因不难理解：为了让配置更一致、更可读，团队决定统一采用接受 Customizer 的重载方法，用 Lambda 来直接定制子模块的行为。

也就是说，以前那种写法，现在行不通了：

http.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt); // ❌ 已废弃

取而代之的是，你需要显式调用 jwt() 方法，并传入 Customizer.withDefaults() 或者你自己的自定义逻辑：

@BeanSecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(authz -> authz
            .anyRequest().authenticated() // ✅ 替代已移除的 antMatchers()/mvcMatchers()
        )
        .sessionManagement(session -> session
            .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
        )
        .httpBasic(Customizer.withDefaults()) // ✅ 替代已废弃的 httpBasic()
        .csrf(csrf -> csrf.disable())
        .headers(headers -> headers
            .frameOptions(frameOptions -> frameOptions.sameOrigin())
        )
        .oauth2ResourceServer(oauth2 -> oauth2
            .jwt(Customizer.withDefaults()) // ✅ 正确用法：Lambda + Customizer
        );
    return http.build();
}

这里有几个关键点值得特别留意。

关键注意事项

• Customizer.withDefaults() 可不是“什么都不做”——它会自动启用默认的 JWT 解析器（底层基于 NimbusJwtDecoder），并尝试从 jwk-set-uri（比如 /oauth2/jwks）加载公钥。如果你需要自定义解码器，比如指定 RSA 公钥、本地密钥，或者换成响应式解码器，那就别偷懒了，改成 jwt(jwt -> jwt.decoder(myCustomDecoder)) 就行。
• 所有旧式的请求匹配方法——antMatchers、mvcMatchers、regexMatchers——在 6.0 中已经被完全移除了。现在必须用 authorizeHttpRequests() 内部的 RequestAuthorizationManager 风格来配置。比如这样写：

  .requestMatchers("/public/**").permitAll().requestMatchers("/api/admin/**").hasRole("ADMIN")

• 如果你正在集成 Spring Boot 3.x，记得确保 spring-boot-starter-oauth2-resource-server 的依赖版本 ≥ 3.0，并且在 application.yml 中配置好 spring.security.oauth2.resourceserver.jwt.jwk-set-uri 或者 public-key-location。

总的来说，Spring Security 6+ 新风格的核心原则其实就一句话：单一 DSL 路径，全面拥抱函数式、不可变、Lambda 驱动的配置方式。及时把 JWT 配置更新过来，不仅能干掉那些烦人的编译警告，更能保证后续版本的兼容性，配置语义也更清晰。这才是长期受益的正解。