Spring Boot中的过滤器(Filter)怎么配置@WebFilter与FilterRegistrationBean对比

@WebFilter不生效的根本原因是Spring Boot默认不扫描它，必须添加@ServletComponentScan；且无法用@Order控制顺序，加载顺序由类名决定。

@WebFilter 注解为什么经常不生效

根本原因就一个：@WebFilter 是 Servlet 原生规范，Spring Boot 默认不扫描它——必须显式加 @ServletComponentScan 才能被识别。但即使加了，你也无法用 @Order 控制执行顺序，多个 @WebFilter 的加载顺序由类名字母序决定，完全不可控。

常见错误现象包括：

• 加了 @WebFilter(urlPatterns = "/*") 却没任何日志输出，怀疑过滤器没运行
• 同时存在 AuthFilter 和 LogFilter，结果 LogFilter 总在 AuthFilter 之前执行，权限校验逻辑被绕过
• 在测试环境生效，上线后因类加载器差异或 jar 包打包方式不同而失效

适用场景极少：仅限单过滤器、无顺序依赖、且你明确接受 Servlet 容器级管理（比如集成老式 Filter 库）。

FilterRegistrationBean 是唯一可靠的方式

FilterRegistrationBean 把 Filter 当作 Spring Bean 管理，天然支持依赖注入、生命周期回调和精确排序。它的核心优势不是“更高级”，而是“可预测”——setOrder(1) 就是真的排第一，setOrder(2) 就是第二，不会被类名或扫描顺序干扰。

实操建议：

• Filter 实现类用 @Component 或直接 new 出来都行，但推荐不加 @Component，避免被 Spring 自动注册两次
• URL 模式用 addUrlPatterns("/*")，不要用 setUrlPatterns(Arrays.asList("/*"))，后者会覆盖默认的空列表，导致拦截失效
• 务必调用 setFilter(new YourFilter())，漏掉这句等于注册了个空壳
• 如果 Filter 需要注入其他 Bean（比如 RedisTemplate），必须通过构造函数或 @Autowired 在 Filter 类内部完成，不能指望 FilterRegistrationBean 替你做依赖注入

示例关键片段：

@Configuration
public class FilterConfig {
    @Bean
    public FilterRegistrationBean<TimeFilter> timeFilterRegistration() {
        FilterRegistrationBean<TimeFilter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new TimeFilter()); // 必须设 filter 实例
        registration.addUrlPatterns("/*");
        registration.setName("timeFilter");
        registration.setOrder(1); // 这里才真正生效
        return registration;
    }
}

为什么不能混用@WebFilter和FilterRegistrationBean

混用会导致同一个 Filter 被注册两次：一次由 Servlet 容器通过 @WebFilter 加载，一次由 Spring 通过 FilterRegistrationBean 注册。后果是请求被重复处理，比如耗时统计翻倍、Token 校验执行两遍、甚至响应体被写两次引发 IllegalStateException: getWriter() has already been called 错误。

Riffo

Riffo是一个免费的文件智能命名和管理工具

下载

排查方法很简单：启动日志里搜 Filter initializing 或你的 Filter 名字，如果出现两次，基本就是混用了。

安全做法只选一种，且项目初期就定死。团队协作中建议统一禁用 @WebFilter，在代码检查（如 SonarQube）里加规则拦截 @WebFilter 注解的出现。

Filter 和拦截器执行时机的真实差异

很多人以为 “Filter → Interceptor → Controller” 是线性流程，其实 Filter 的 doFilter 方法里包裹了整个请求生命周期——包括 Interceptor 的 preHandle / afterCompletion，甚至 DispatcherServlet 的 doDispatch。所以 Filter 的 chain.doFilter() 一执行，后面所有 Spring Web 层逻辑（含拦截器）才开始跑。

这意味着：

• 你在 Filter 中修改 HttpServletRequest（比如包装 request），Interceptor 拿到的就是已包装的对象；但反过来，Interceptor 改不了 Filter 已经读过的请求体（比如已 parse 的 body）
• Filter 的 destroy() 不会在应用关闭时立即调用，可能延迟几秒甚至更久；而 Interceptor 的 afterCompletion() 是每次请求必达的最后钩子
• Filter 可以处理静态资源（/css/*.js）、错误页（/error）、甚至 Actuator 端点；Interceptor 默认不拦截这些，除非显式配置 excludePathPatterns

真正需要跨框架兼容（比如未来换 Netty 或 WebFlux）的逻辑，别放 Filter 里——那是 Servlet 绑定的，换容器就废。