SpringSecurity6实战：如何正确配置WebSecurityCustomizer避免自定义过滤器重复执行
Spring Security 6实战：深度解析WebSecurityCustomizer与过滤器链控制策略
在前后端分离架构成为主流的今天，Spring Security作为Java生态中最成熟的安全框架，其最新版本6.x系列带来了诸多突破性改进。但当我们尝试将自定义JWT过滤器集成到安全体系时，一个令人困扰的问题频繁出现：明明通过requestMatchers().permitAll()配置了免认证路径，为何自定义过滤器依然会被执行？这不仅导致性能损耗，更可能引发意料之外的逻辑错误。
本文将带你深入Spring Security 6的过滤器链机制，通过三个典型场景的解决方案对比，揭示WebSecurityCustomizer的正确使用姿势。无论你是正在升级旧系统还是构建全新安全层，这些实战经验都能帮你避开我踩过的那些"坑"。
1. 问题本质：认证与授权的执行边界
当我们查看一个典型的JWT认证流程时，预期中的请求处理顺序应该是：
- 请求到达服务器
- 安全头部处理（XSS防护等）
- 认证阶段：解析JWT令牌并建立Authentication对象
- 授权阶段：检查请求权限（permitAll在此生效）
- 业务逻辑处理
但实际观察到的执行链却是：
// 伪代码展示过滤器执行顺序 void doFilterInternal() { writeSecureHeaders(); // 安全头部 jwtFilter.doFilter(); // 自定义JWT过滤器执行 checkPermitAll(); // permitAll检查 businessLogic(); // 业务逻辑 }这种差异源于Spring Security的核心设计哲学：认证必须先于授权。正如框架贡献者Rob Winch在GitHub issue中指出的："permitAll()只影响授权决策，而认证过滤器（如JWT校验）必须在授权前执行，因为授权决策可能需要认证信息"。
1.1 两种解决方案的对比
| 方案 | 原理 | 适用场景 | 副作用 |
|---|---|---|---|
| WebSecurityCustomizer | 完全绕过安全过滤器链 | 静态资源、纯公开API | 丢失安全头部等防护 |
| SecurityFilterChain | 控制过滤器执行条件 | 需要部分安全特性的接口 | 需精确配置匹配规则 |
关键洞察：如果路径只需要"免认证"而非"完全忽略安全"，应优先选择SecurityFilterChain配置。
2. WebSecurityCustomizer的精准控制
Spring Security 6中，WebSecurityCustomizer的配置方式较旧版本有显著变化。以下是避免自定义过滤器重复执行的标准做法：
@Configuration @EnableWebSecurity public class SecurityConfig { @Bean public WebSecurityCustomizer webSecurityCustomizer() { return (web) -> web.ignoring() .requestMatchers( "/public/**", "/swagger-ui/**", "/v3/api-docs/**" ); } // 其他配置... }这种配置下，匹配的路径将完全跳过整个安全过滤器链，包括：
- 安全头部（如CSP、X-XSS-Protection）
- CSRF防护
- 所有认证过滤器
- 授权逻辑
2.1 动态路径忽略策略
对于需要运行时判断的路径，可以结合自定义RequestMatcher实现：
@Bean public WebSecurityCustomizer dynamicIgnoringCustomizer() { return (web) -> web.ignoring() .requestMatchers(new DynamicRequestMatcher()); } private static class DynamicRequestMatcher implements RequestMatcher { @Override public boolean matches(HttpServletRequest request) { String path = request.getRequestURI(); return path.startsWith("/cache/") || path.endsWith(".hot-update.js"); } }3. 混合策略：SecurityFilterChain的精细调控
对于需要保留部分安全特性（如CSP头部）的公开接口，更优解是通过SecurityFilterChain控制过滤器执行：
@Bean public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .csrf().disable() .sessionManagement().sessionCreationPolicy(STATELESS) .and() .authorizeHttpRequests(registry -> registry .requestMatchers("/api/public/**").permitAll() .anyRequest().authenticated() ) .addFilterBefore(jwtFilter(), UsernamePasswordAuthenticationFilter.class); return http.build(); } // 关键：避免将自定义过滤器注册为Spring Bean public JwtAuthenticationFilter jwtFilter() { return new JwtAuthenticationFilter(userService); }这里有两个技术要点：
- 避免过滤器Bean化：自定义过滤器通过方法实例化而非
@Bean，防止被自动注册到全局过滤器链 - 显式排序：通过
addFilterBefore明确指定过滤器位置
3.1 过滤器执行条件控制
对于更复杂的场景，可以在过滤器内部添加路径检查：
public class ConditionalJwtFilter extends OncePerRequestFilter { private final List<RequestMatcher> excludeMatchers = List.of( new AntPathRequestMatcher("/health"), new AntPathRequestMatcher("/metrics") ); @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) { if (shouldNotFilter(request)) { chain.doFilter(request, response); return; } // JWT验证逻辑... } private boolean shouldNotFilter(HttpServletRequest request) { return excludeMatchers.stream() .anyMatch(matcher -> matcher.matches(request)); } }4. 性能优化与调试技巧
当安全配置复杂时，如何验证过滤器链是否按预期工作？Spring Security提供了内置的调试工具：
# 启用调试日志 logging.level.org.springframework.security=DEBUG典型调试日志会显示：
Security filter chain: [ WebAsyncManagerIntegrationFilter SecurityContextPersistenceFilter HeaderWriterFilter LogoutFilter JwtAuthenticationFilter # 自定义过滤器 UsernamePasswordAuthenticationFilter DefaultLoginPageGeneratingFilter DefaultLogoutPageGeneratingFilter RequestCacheAwareFilter SecurityContextHolderAwareRequestFilter AnonymousAuthenticationFilter ExceptionTranslationFilter FilterSecurityInterceptor ]对于性能敏感场景，建议：
- 使用
@ConditionalOnProperty控制安全配置加载 - 对静态资源启用缓存控制头
- 定期审查过滤器链长度（通过
FilterRegistrationBean）
@Autowired private FilterRegistrationBean<?>[] filterRegistrations; @PostConstruct public void logFilterChain() { Arrays.stream(filterRegistrations) .sorted(Comparator.comparingInt(FilterRegistrationBean::getOrder)) .forEach(reg -> log.info("Filter {} order {}", reg.getFilterName(), reg.getOrder())); }在微服务架构下，这些配置策略需要与API网关的安全策略协调一致。比如网关层已经处理了JWT验证时，服务内部可以完全禁用相关过滤器。