Spring Boot 3 中 WebFilter 执行顺序全解析

一、过滤器链基础架构

1.1 请求处理流程概览

sequenceDiagram
    Client->>+DispatcherServlet: HTTP请求
    DispatcherServlet->>+FilterChain: 启动过滤器链
    FilterChain->>+WebFilter1: 执行doFilter
    WebFilter1->>+WebFilter2: 调用chain.doFilter
    WebFilter2->>+Controller: 最终到达控制器
    Controller-->>-WebFilter2: 返回响应
    WebFilter2-->>-WebFilter1: 后置处理
    WebFilter1-->>-DispatcherServlet: 完成过滤
    DispatcherServlet-->>-Client: 返回响应

1.2 核心接口定义

public interface WebFilter {
    Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain);
}

public interface WebFilterChain {
    Mono<Void> filter(ServerWebExchange exchange);
}

二、过滤器注册机制

2.1 注册方式对比

注册方式	适用场景	顺序控制方法
@Component + @Order	简单过滤器	通过@Order注解指定数字
FilterRegistrationBean	需要动态配置	setOrder()方法
实现Ordered接口	需要条件排序	getOrder()方法返回优先级数字

2.2 典型配置示例

// 方式1：注解控制
@Component
@Order(1)
public class AuthFilter implements WebFilter {
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        // 认证逻辑
        return chain.filter(exchange);
    }
}

// 方式2：编程式注册
@Configuration
public class FilterConfig {
    @Bean
    public WebFilterChainProxy logFilter() {
        return new WebFilterChainProxy(
            new OrderedWebFilter(new LogFilter(), 2)
        );
    }
}

三、执行顺序控制策略

3.1 顺序决定因素

graph TD
    A[过滤器顺序] --> B[Order值]
    A --> C[注册顺序]
    B --> D[数值越小优先级越高]
    C --> E[Bean定义顺序]
    style D fill:#6f9,stroke:#333

3.2 优先级规则表

排序依据	生效条件	冲突解决方案
@Order注解	所有过滤器中	数值小的先执行
Ordered接口	实现该接口的过滤器	getOrder()返回值决定
注册顺序	无Order注解的过滤器	先注册的先执行
显式Order值设置	FilterRegistrationBean	setOrder()方法设置

四、内置过滤器顺序参考

4.1 Spring Security默认顺序

过滤器类型	Order值	作用
SecurityContext	-100	安全上下文管理
WebAsyncManager	-150	异步请求处理
CORS	-200	跨域请求处理
FormContent	-300	表单内容解析
RequestContext	-400	请求上下文管理

4.2 常用业务过滤器推荐顺序

业务场景	建议Order值	说明
全链路追踪	-50	最早记录请求信息
权限校验	0	早期阻断非法请求
参数校验	50	校验前需完成身份认证
日志记录	100	最后记录完整请求响应
响应包装	200	最终修改响应体

五、执行流程深度分析

5.1 正向处理流程

graph LR
    A[请求进入] --> B[Filter1.preHandle]
    B --> C[Filter2.preHandle]
    C --> D[Controller]
    D --> E[Filter2.postHandle]
    E --> F[Filter1.postHandle]
    F --> G[响应返回]
    style B fill:#bbf,stroke:#333
    style E fill:#f9f,stroke:#333

5.2 异常处理流程

try {
    return filter1.filter(exchange, chain)
        .then(filter2.filter(exchange, chain))
        .then(Mono.defer(() -> controller.handle(exchange)))
        .then(Mono.fromRunnable(() -> filter2.afterCompletion(exchange)))
        .then(Mono.fromRunnable(() -> filter1.afterCompletion(exchange)));
} catch (Exception e) {
    return filter1.onError(exchange, e)
        .then(filter2.onError(exchange, e))
        .then(Mono.error(e));
}

六、调试与验证方法

6.1 调试技巧

@Configuration
public class FilterDebugConfig {
    
    @Bean
    public ApplicationListener<FilterRegisteredEvent<?>> filterDebugListener() {
        return event -> {
            System.out.printf("Filter注册: %s, Order: %d%n",
                event.getFilter().getClass().getSimpleName(),
                event.getOrder());
        };
    }
}

6.2 执行日志分析

2023-08-20 DEBUG o.s.w.s.f.OrderedWebFilterChain     : Invoking filter AuthFilter (order = 1)
2023-08-20 DEBUG o.s.w.s.f.OrderedWebFilterChain     : Invoking filter LogFilter (order = 2)
2023-08-20 DEBUG o.s.w.s.f.OrderedWebFilterChain     : Invoking filter CacheFilter (order = 3)
2023-08-20 DEBUG o.s.w.s.f.OrderedWebFilterChain     : Calling controller method
2023-08-20 DEBUG o.s.w.s.f.OrderedWebFilterChain     : Completed filter CacheFilter
2023-08-20 DEBUG o.s.w.s.f.OrderedWebFilterChain     : Completed filter LogFilter
2023-08-20 DEBUG o.s.w.s.f.OrderedWebFilterChain     : Completed filter AuthFilter

七、性能优化建议

7.1 过滤器编排原则

优化原则	实施建议	收益预估
前置阻断	权限校验类过滤器设置高优先级	减少无效请求处理
轻量先行	简单操作过滤器先执行	降低处理延迟
异步化	耗时操作实现异步过滤器	提高吞吐量
条件执行	实现ShouldFilter接口控制执行条件	减少不必要过滤

7.2 错误配置反模式

// 反例1：循环依赖
@Bean
public WebFilter filterA(WebFilter filterB) {
    return (exchange, chain) -> {
        // 错误逻辑
        return filterB.filter(exchange, chain);
    };
}

// 反例2：阻塞操作
@Bean
public WebFilter blockingFilter() {
    return (exchange, chain) -> {
        Thread.sleep(100); // 阻塞线程
        return chain.filter(exchange);
    };
}

八、高级应用场景

8.1 动态过滤器注册

@Configuration
public class DynamicFilterConfig {
    
    @Autowired
    private List<WebFilter> filters;
    
    @Bean
    public RouterFunction<ServerResponse> dynamicRoute() {
        return route()
            .before(exchange -> {
                // 动态添加前置处理
                return new CustomFilter().filter(exchange, new DefaultWebFilterChain(filters));
            })
            .build();
    }
}

8.2 过滤器短路模式

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class CircuitBreakerFilter implements WebFilter {
    
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        if (isOverloaded()) {
            return Mono.error(new ResponseStatusException(
                HttpStatus.TOO_MANY_REQUESTS, "系统过载"));
        }
        return chain.filter(exchange);
    }
}

九、常见问题解决方案

9.1 顺序失控排查

graph TD
    A[过滤器顺序异常] --> B{检查点}
    B --> C[是否有多重Order定义]
    B --> D[是否有重复注册]
    B --> E[是否手动修改了FilterChain]
    C --> F[统一使用一种排序方式]
    D --> G[检查@ComponentScan范围]
    E --> H[恢复默认配置]

9.2 典型错误案例

问题现象	根本原因	解决方案
过滤器未生效	未正确注册或Order值过大	检查@Component或@Bean定义
部分接口跳过过滤	路径匹配规则错误	调整@WebFilter的urlPatterns
响应修改被覆盖	过滤器顺序不当	提高响应包装过滤器的优先级
异步处理中断	未正确返回Mono	确保所有操作返回Publisher

十、最佳实践总结

10.1 过滤器设计原则

单一职责：每个过滤器只处理一个关注点
无状态：避免在过滤器中存储请求状态
快速失败：尽早阻断非法请求
明确顺序：通过Order值显式控制流程

10.2 配置模板

@Configuration
public class OptimalFilterConfig {

    // 全链路追踪 (最高优先级)
    @Bean
    @Order(Ordered.HIGHEST_PRECEDENCE + 1)
    public WebFilter tracingFilter() {
        return new TracingFilter();
    }

    // 权限控制
    @Bean
    @Order(0)
    public WebFilter authFilter() {
        return new AuthFilter();
    }

    // 请求日志 (最低优先级)
    @Bean
    @Order(Ordered.LOWEST_PRECEDENCE - 1)
    public WebFilter loggingFilter() {
        return new LoggingFilter();
    }
}

关键结论：
Spring Boot 3中的WebFilter执行顺序由Order值严格掌控，遵循以下核心规则：