Spring Boot JWT过滤器配置指南

在Spring Boot应用中集成JWT（JSON Web Token）进行认证是常见的做法。然而，默认的JWT过滤器通常会拦截所有请求，这在某些场景下可能不是最优解。例如，我们可能只希望对/api/**开头的接口进行JWT认证，而其他公共接口（如/login、/register）则无需经过JWT过滤器处理。本文将指导您如何通过Spring Security提供的AbstractAuthenticationProcessingFilter和RequestMatcher接口，实现JWT过滤器针对特定URL模式的精确控制。

核心概念解析

要实现JWT过滤器的精确控制，我们需要理解Spring Security中的几个关键组件：

• AbstractAuthenticationProcessingFilter: 这是Spring Security提供的一个抽象基类，用于实现基于请求的认证过滤器。它的核心特性是，只会处理那些与其内部RequestMatcher匹配的请求。通过继承它，我们可以将自定义的认证逻辑（如JWT验证）绑定到特定的URL模式上。
• RequestMatcher: 这是一个接口，定义了如何匹配传入的HttpServletRequest。当RequestMatcher的matches()方法返回true时，AbstractAuthenticationProcessingFilter才会执行其认证逻辑。
• AntPathRequestMatcher: RequestMatcher接口的一个常用实现，允许我们使用Ant风格的路径模式（如/api/**, /users/*）来匹配URL。
• OrRequestMatcher: 另一个RequestMatcher实现，用于组合多个RequestMatcher。如果其中任何一个子匹配器匹配成功，则OrRequestMatcher返回true。这在需要匹配多个不连续的URL模式时非常有用。

实现步骤

我们将通过以下三个主要步骤来配置JWT过滤器：

步骤一：创建自定义JWT认证过滤器

首先，您的JWT认证过滤器需要继承AbstractAuthenticationProcessingFilter。这意味着它将不再是一个简单的Filter实现，而是具备了根据RequestMatcher选择性执行的能力。

import org.springframework.security.core.Authentication;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter;
import org.springframework.security.web.util.matcher.RequestMatcher;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

// 假设您已有一个用于处理JWT的AuthenticationManager
// 或者您可以在attemptAuthentication方法中直接处理JWT验证逻辑
public class CustomJwtAuthenticationFilter extends AbstractAuthenticationProcessingFilter {

    // 构造函数接收一个RequestMatcher，用于定义哪些URL需要此过滤器处理
    public CustomJwtAuthenticationFilter(RequestMatcher requiresAuthenticationRequestMatcher) {
        super(requiresAuthenticationRequestMatcher);
    }

    /**
     * 这是AbstractAuthenticationProcessingFilter的核心方法，
     * 当请求URL与构造函数中传入的RequestMatcher匹配时，此方法会被调用。
     * 在这里，您将实现从请求中提取JWT并进行认证的逻辑。
     */
    @Override
    public Authentication attemptAuthentication(HttpServletRequest request, HttpServletResponse response)
            throws AuthenticationException, IOException {
        // 1. 从请求头（如Authorization: Bearer ）中提取JWT
        String authHeader = request.getHeader("Authorization");
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            // 如果没有有效的JWT，可以抛出异常或返回null
            // AbstractAuthenticationProcessingFilter 会将AuthenticationException传递给AuthenticationEntryPoint
            throw new AuthenticationServiceException("JWT Token is missing or invalid");
        }
        String jwtToken = authHeader.substring(7); // 移除 "Bearer " 前缀

        // 2. 根据JWT创建Authentication对象（例如，一个包含JWT字符串的UsernamePasswordAuthenticationToken）
        // 这里只是一个示例，实际的JWT解析和用户查找逻辑会更复杂
        // 您可能需要一个JwtTokenProvider或类似的Service来验证和解析JWT
        // 假设您有一个JwtAuthenticationToken，它包含了JWT信息
        JwtAuthenticationToken authenticationToken = new JwtAuthenticationToken(jwtToken);

        // 3. 将AuthenticationToken提交给AuthenticationManager进行认证
        // getAuthenticationManager() 方法由 AbstractAuthenticationProcessingFilter 提供
        // 并且需要在SecurityConfig中暴露AuthenticationManager Bean
        return getAuthenticationManager().authenticate(authenticationToken);
    }

    // 您可能还需要重写 successfulAuthentication 和 unsuccessfulAuthentication 方法
    // 以处理认证成功或失败后的逻辑（如设置SecurityContext、返回错误信息等）
}

步骤二：定义URL匹配器

接下来，我们需要创建一个RequestMatcher实例，它能准确识别出我们希望JWT过滤器处理的URL模式。根据需求，我们可以使用AntPathRequestMatcher或OrRequestMatcher。

示例：匹配`/api/`路径**

import org.springframework.security.web.util.matcher.AntPathRequestMatcher;
import org.springframework.security.web.util.matcher.RequestMatcher;
import org.springframework.security.web.util.matcher.OrRequestMatcher;
import javax.servlet.http.HttpServletRequest;
import java.util.List;
import java.util.stream.Collectors;

// 这是一个辅助类，用于生成匹配特定API路径的RequestMatcher
public class ApiUrlRequestMatcher {

    /**
     * 创建一个RequestMatcher，用于匹配所有以指定模式开头的API路径。
     *
     * @param patterns 期望匹配的URL模式列表，例如 "/api/**", "/admin/**"
     * @return 组合后的RequestMatcher
     */
    public static RequestMatcher createApiMatcher(List patterns) {
        // 将每个模式转换为AntPathRequestMatcher
        List matchers = patterns.stream()
                .map(AntPathRequestMatcher::new)
                .collect(Collectors.toList());
        // 使用OrRequestMatcher将所有模式组合起来
        return new OrRequestMatcher(matchers);
    }

    /**
     * 单个AntPathRequestMatcher的简单示例
     */
    public static RequestMatcher createSingleApiMatcher(String pattern) {
        return new AntPathRequestMatcher(pattern);
    }
}

步骤三：配置Spring Security链

最后，在您的Spring Security配置类（通常是继承WebSecurityConfigurerAdapter的类）中，实例化CustomJwtAuthenticationFilter并将其添加到安全过滤器链中。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.security.web.util.matcher.RequestMatcher;
import java.util.Arrays; // For List.of in older Java versions

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    // 假设您有一个JwtAuthenticationEntryPoint来处理认证失败的响应
    // @Autowired
    // private JwtAuthenticationEntryPoint jwtAuthenticationEntryPoint;

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // 1. 定义需要JWT过滤器处理的URL模式
        RequestMatcher jwtFilterMatcher = ApiUrlRequestMatcher.createApiMatcher(
                Arrays.asList("/api/**", "/admin/**") // 示例：匹配 /api/** 和 /admin/**
        );
        // 或者只匹配一个模式:
        // RequestMatcher jwtFilterMatcher = ApiUrlRequestMatcher.createSingleApiMatcher("/api/**");


        // 2. 创建CustomJwtAuthenticationFilter实例
        // 注意：这里需要确保CustomJwtAuthenticationFilter能获取到AuthenticationManager
        // 可以通过setAuthenticationManager()方法设置，或者在构造函数中传入
        CustomJwtAuthenticationFilter customJwtAuthenticationFilter = new CustomJwtAuthenticationFilter(jwtFilterMatcher);
        customJwtAuthenticationFilter.setAuthenticationManager(authenticationManagerBean()); // 注入AuthenticationManager


        http.csrf().disable() // 禁用CSRF，因为JWT是无状态的
            .authorizeRequests()
                // 确保这些路径需要认证，以便JWT过滤器能发挥作用
                .antMatchers("/api/**", "/admin/**").authenticated() // 这些路径需要认证
                .antMatchers("/users").authenticated() // 示例：/users也需要认证，但可能不是通过JWT过滤器
                .anyRequest().permitAll() // 其他所有请求都允许访问，无需认证
            .and()
                // 配置会话管理为无状态，适用于JWT
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .and()
                // 配置异常处理，如认证入口点和拒绝访问页面
                // .exceptionHandling()
                //     .authenticationEntryPoint(jwtAuthenticationEntryPoint)
                //     .accessDeniedPage("/403")
            // .and()
                // 配置表单登录（如果您的应用同时支持表单登录）
                // 这里的配置与JWT过滤器是并行的，互不影响
                .formLogin()
                    .loginPage("/login")
                    .defaultSuccessUrl("/users")
                    .failureUrl("/login?error=true")
                    .permitAll()
            .and()
                // 配置登出
                .logout()
                    .logoutSuccessUrl("/")
                    .permitAll()
            .and()
                // 将自定义JWT过滤器添加到Spring Security过滤器链中
                // 确保它在UsernamePasswordAuthenticationFilter之前执行，
                // 这样JWT认证可以在默认的表单登录认证之前进行
                .addFilterBefore(customJwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);
    }

    // 暴露AuthenticationManager为一个Bean，以便CustomJwtAuthenticationFilter可以使用它
    @Bean
    @Override
    public AuthenticationManager authenticationManagerBean() throws Exception {
        return super.authenticationManagerBean();
    }

    // 您可能还需要配置PasswordEncoder和UserDetailsService等
    // @Override
    // protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    //     auth.userDetailsService(userDetailsService).passwordEncoder(passwordEncoder());
    // }
}

注意事项与最佳实践

1. 过滤器顺序: addFilterBefore(customJwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class) 是关键。它确保了您的JWT过滤器在Spring Security默认的基于用户名密码的表单登录过滤器之前执行。对于匹配的请求，JWT认证会先尝试完成。
2. 授权配置: 在authorizeRequests()中，antMatchers("/api/**").authenticated()（或其他您希望JWT过滤器处理的路径）是必不可少的。这告诉Spring Security这些路径需要认证。如果请求通过了JWT过滤器并成功认证，它将满足authenticated()的要求。
3. AuthenticationManager的注入: AbstractAuthenticationProcessingFilter需要一个AuthenticationManager来处理认证逻辑。通常，您可以通过重写authenticationManagerBean()方法将其暴露为一个Bean，然后在您的自定义过滤器中注入或设置。
4. 无状态会话: 对于JWT认证，将sessionCreationPolicy设置为SessionCreationPolicy.STATELESS至关重要。这表示您的应用不会创建或使用HTTP会话来存储用户状态，所有