【Filter / Interceptor】过滤器（Filter）与拦截器（Interceptor）全方位对比解析（附底层原理 + 核心对比表）

文章目录过滤器Filter与拦截器Interceptor系统性知识体系一、核心定位与体系总览【重点】核心对比表二、过滤器Filter2.1 核心定义与底层原理2.2 核心API与生命周期2.2.1 核心接口2.2.2 生命周期方法2.2.3 关键扩展基类2.3 主流配置方式2.4 能力边界与典型场景能力边界典型使用场景三、拦截器Interceptor3.1 核心定义与底层原理3.2 核心API与生命周期3.2.1 核心接口3.2.2 核心生命周期方法3.2.3 扩展接口3.3 主流配置方式3.4 能力边界与典型场景能力边界典型使用场景四、全链路执行时序与流程详解5.1 完整请求-响应全流程5.2 多组件执行顺序示例五、场景选型与最佳实践6.1 核心选型原则6.2 过滤器最佳实践6.3 拦截器最佳实践六、进阶知识与常见坑点7.1 进阶知识边界7.2 高频坑点避坑指南Filter 高频坑Interceptor 高频坑附1底层原理底层原理的核心差异总结一、过滤器Filter底层原理1. 核心设计模式责任链模式Chain of Responsibility2. Servlet 容器的请求处理流程3. 关键组件FilterChain 的实现机制4. 生命周期的底层管理5. OncePerRequestFilter 的避坑原理二、拦截器Interceptor底层原理1. 核心设计模式责任链模式 Spring AOP 思想2. Spring MVC 的请求分发全流程3. 关键组件HandlerExecutionChain 的组装与执行4. 与 Spring 容器的集成Bean 注入的原理5. 与 Spring AOP 的本质区别附2核心区别一句话总结1. 规范归属与管理主体不同2. 执行层级与触发时机不同3. 依赖注入与上下文能力不同4. 拦截范围与控制粒度不同5. 异常处理能力不同6. 适用场景不同过滤器Filter与拦截器Interceptor系统性知识体系本文从核心定位、底层原理、API规范、执行流程、核心对比、场景选型、最佳实践、避坑指南8个维度构建完整的知识体系明确两者的边界、能力与适用场景。一、核心定位与体系总览过滤器与拦截器是Java Web开发中基于责任链设计模式实现的请求处理组件核心差异在于所属层级与依赖环境是请求全链路处理中不同阶段的流量管控入口组件规范归属执行层级核心定位过滤器FilterJava Servlet/Jakarta EE 规范Web容器Tomcat等层级容器级请求拦截器处理所有进入容器的HTTP请求拦截器InterceptorSpring Framework 规范Spring MVC 上下文层级框架级请求拦截器精细化处理Spring MVC分发的业务请求【重点】核心对比表对比维度过滤器Filter拦截器Interceptor规范归属Java Servlet/Jakarta EE 官方规范Spring Framework 框架规范执行层级Web容器Tomcat等层级Spring MVC 上下文层级依赖环境依赖Web容器不依赖Spring框架依赖Spring容器不强制依赖Web容器触发时机请求进入容器后、Servlet执行前请求进入DispatcherServlet后、Controller执行前拦截范围所有进入容器的HTTP请求静态资源、Servlet、接口等仅DispatcherServlet分发的请求默认仅Controller接口Bean访问能力无法直接注入Spring Bean需额外配置可自由注入Spring容器中所有Bean上下文信息仅能获取请求/响应基础信息可获取Controller方法、注解、ModelAndView等全量MVC上下文执行顺序优先于拦截器执行Order值越小优先级越高晚于过滤器执行注册顺序/Order值越小优先级越高执行控制仅能通过chain.doFilter()控制链路可通过preHandle返回值直接终止请求控制粒度更细异常处理无法被Spring全局异常处理器捕获可被Spring全局异常处理器统一处理适用粒度容器级、全请求通用的无状态处理业务级、细粒度、依赖Spring上下文的处理二、过滤器Filter2.1 核心定义与底层原理Filter是Servlet规范定义的原生组件运行在Web容器中在请求进入Servlet之前、响应返回客户端之前执行是容器层面的请求第一道/最后一道关卡。核心设计模式责任链模式通过FilterChain串联多个Filter形成链式执行核心特性不依赖Spring框架脱离Web容器无法运行可拦截所有映射到容器的请求静态资源、Servlet、JSP、Spring接口等2.2 核心API与生命周期2.2.1 核心接口Java EESpring Boot 2.x及以下javax.servlet.FilterJakarta EESpring Boot 3.x及以上jakarta.servlet.Filter包名变更旧代码需适配2.2.2 生命周期方法方法执行时机核心作用执行次数init(FilterConfig filterConfig)容器启动时Filter实例化后执行初始化Filter配置、加载资源容器生命周期内仅1次doFilter(ServletRequest request, ServletResponse response, FilterChain chain)每次请求匹配到Filter时执行核心请求/响应处理逻辑通过chain.doFilter()调用下一个Filter/目标Servlet每次匹配请求执行1次destroy()容器关闭时Filter销毁前执行资源释放、清理容器生命周期内仅1次2.2.3 关键扩展基类OncePerRequestFilterSpring提供的Filter抽象基类解决原生Filter在请求转发、包含场景下多次执行的问题Spring内置Filter编码、跨域等均继承该类。2.3 主流配置方式注解配置WebFilter标注Filter类配合ServletComponentScan扫描注册缺点无法精准控制执行顺序默认按类名字典序排序Spring Boot 注册Bean配置推荐通过FilterRegistrationBean注册可精准控制顺序、拦截路径、启动顺序传统web.xml配置Servlet原生配置方式现已极少使用2.4 能力边界与典型场景能力边界可操作对象仅ServletRequest/ServletResponse无法直接访问Spring上下文Bean、Spring MVC上下文信息拦截范围所有进入Web容器的请求无法拦截非Web请求、方法级调用异常处理Filter中抛出的异常无法被Spring全局异常处理器RestControllerAdvice捕获典型使用场景全链路请求编码设置CharacterEncodingFilterCORS跨域资源共享处理XSS/CSRF攻击防护、请求参数脱敏全链路日志追踪TraceId透传全局黑白名单、接口限流静态资源缓存控制、响应压缩三、拦截器Interceptor3.1 核心定义与底层原理Interceptor是Spring MVC原生组件基于Spring AOP思想实现运行在DispatcherServlet请求分发流程中是Spring上下文层面的业务请求管控组件。核心设计模式责任链模式通过HandlerExecutionChain串联多个Interceptor形成链式执行核心特性依赖Spring容器可访问Spring上下文中所有Bean可获取Spring MVC全链路上下文信息支持细粒度的请求管控3.2 核心API与生命周期3.2.1 核心接口org.springframework.web.servlet.HandlerInterceptorSpring 5.3之后废弃HandlerInterceptorAdapter适配类直接通过接口default方法实现自定义逻辑。3.2.2 核心生命周期方法方法执行时机核心作用执行规则preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)Controller方法执行前前置校验鉴权、限流等返回true放行false终止请求按注册顺序正序执行仅返回true才会触发后续方法postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView)Controller方法执行后视图渲染前后置处理可修改ModelAndView、统一追加响应参数按注册顺序倒序执行afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)整个请求处理完成视图渲染完毕后资源清理、异常收尾处理按注册顺序倒序执行仅对应preHandle返回true的拦截器会执行3.2.3 扩展接口AsyncHandlerInterceptor继承HandlerInterceptor新增afterConcurrentHandlingStarted方法专门处理Spring异步请求的拦截场景。3.3 主流配置方式Spring Boot Java配置推荐实现WebMvcConfigurer接口重写addInterceptors方法注册拦截器、配置拦截/排除路径、控制执行顺序Spring MVC XML配置通过mvc:interceptors标签配置现已极少使用3.4 能力边界与典型场景能力边界可操作对象HttpServletRequest/HttpServletResponse、HandlerMethodController方法元信息、ModelAndView、Spring容器所有Bean拦截范围仅DispatcherServlet分发的请求默认仅Controller接口静态资源需额外配置映射才能拦截无法拦截非Spring管理的类、非Web请求异常处理可被Spring全局异常处理器捕获支持与Spring异常体系无缝集成典型使用场景登录认证、接口权限校验基于Token/角色的细粒度鉴权接口访问日志记录入参、出参、执行耗时统计接口幂等性校验、重复提交拦截国际化、主题切换、用户上下文透传Controller层统一参数预处理/响应后处理业务级接口限流、灰度发布控制四、全链路执行时序与流程详解5.1 完整请求-响应全流程客户端发送HTTP请求 ↓ Web服务器Tomcat接收请求进入Servlet容器 ↓ 【过滤器链 正序执行】所有Filter的doFilter() 前置逻辑 ↓ 过滤器链末端进入DispatcherServlet ↓ DispatcherServlet通过HandlerMapping匹配目标Controller ↓ 【拦截器链 正序执行】所有Interceptor的preHandle()方法 ↓ 所有preHandle()均返回true执行Controller目标方法 ↓ Controller执行完毕返回ModelAndView ↓ 【拦截器链 倒序执行】所有Interceptor的postHandle()方法 ↓ DispatcherServlet执行视图渲染 ↓ 【拦截器链 倒序执行】所有Interceptor的afterCompletion()方法 ↓ 【过滤器链 倒序执行】所有Filter的doFilter() 后置逻辑 ↓ Web容器将响应结果返回客户端5.2 多组件执行顺序示例假设存在2个FilterFilter1 Order1、Filter2 Order22个InterceptorInterceptor1 Order1、Interceptor2 Order2最终执行顺序为Filter1 前置逻辑 → Filter2 前置逻辑 → Interceptor1.preHandle() → Interceptor2.preHandle() → Controller方法执行 → Interceptor2.postHandle() → Interceptor1.postHandle() → 视图渲染 → Interceptor2.afterCompletion() → Interceptor1.afterCompletion() → Filter2 后置逻辑 → Filter1 后置逻辑五、场景选型与最佳实践6.1 核心选型原则容器级、全请求通用的无业务逻辑处理优先用Filter例编码设置、跨域处理、XSS防护、全链路TraceId透传业务级、依赖Spring Bean、细粒度的Controller层处理优先用Interceptor例登录鉴权、权限校验、业务日志、幂等性控制Service/Dao层的方法级管控用Spring AOP而非Interceptor/Filter6.2 过滤器最佳实践优先使用FilterRegistrationBean注册精准控制Order、拦截路径避免WebFilter的顺序问题继承OncePerRequestFilter实现自定义Filter避免一次请求多次执行读取请求体时必须使用ContentCachingRequestWrapper包装Request避免流只能读取一次导致Controller无法获取参数Filter中仅做通用、无状态的处理禁止写入业务逻辑禁止耗时操作Filter中异常需自行处理或转发到错误页面无法依赖Spring全局异常处理器Spring Boot 3.x必须使用jakarta.servlet包下的Filter接口避免导包错误导致不生效6.3 拦截器最佳实践自定义拦截器必须注册为Spring Bean配置类中用Bean声明禁止在addInterceptors中直接new对象否则会导致Bean注入为nullpreHandle()返回false时必须手动写入响应数据避免客户端收到空白响应禁止在postHandle()中修改响应体此时响应流可能已提交会抛出IllegalStateExceptionafterCompletion()中必须清理ThreadLocal、临时资源避免线程复用导致的数据错乱与内存泄漏异步请求必须实现AsyncHandlerInterceptor接口避免拦截逻辑失效配置拦截路径时必须排除静态资源、健康检查、错误页面等非业务请求路径六、进阶知识与常见坑点7.1 进阶知识边界Filter、Interceptor、Spring AOP的粒度差异Filter容器级粒度最粗管控所有进入容器的请求InterceptorMVC框架级粒度中等管控Controller层请求AOP方法级粒度最细管控任意Spring Bean的方法Service、Dao等拦截器的扩展能力可通过handler参数获取HandlerMethod对象解析Controller方法上的自定义注解实现基于注解的精细化管控例仅标注LoginRequired的接口执行鉴权过滤器的全局生效规则Filter的默认拦截路径为/*可匹配所有请求而Interceptor默认仅匹配/路径下的DispatcherServlet分发请求需手动配置通配符7.2 高频坑点避坑指南Filter 高频坑❌ 导包错误Spring Boot 3.x使用javax.servlet.Filter导致Filter不生效❌ 读取请求流后未包装Request导致Controller参数为空❌ 用WebFilter注册无法控制执行顺序导致逻辑异常❌ Filter中抛出异常未做处理导致服务返回500错误无法被全局异常捕获Interceptor 高频坑❌ 直接new拦截器对象注册导致Autowired注入的Bean为null❌ preHandle返回false未设置响应导致客户端空白页❌ ThreadLocal在afterCompletion中未清理导致数据泄露❌ 静态资源被拦截导致页面样式、图片加载失败❌ 异步请求使用普通HandlerInterceptor导致拦截逻辑不完整❌ postHandle中修改响应体导致流提交异常附1底层原理以下从核心设计模式、容器/框架处理流程、关键组件实现、生命周期管理等维度深入解析两者的底层工作机制。底层原理的核心差异总结维度过滤器Filter拦截器Interceptor管理主体Web 容器Tomcat 等Spring 容器链实现载体ApplicationFilterChain数组索引HandlerExecutionChainList索引依赖注入默认不支持需手动获取 Spring 上下文原生支持直接注入 Spring Bean设计模式纯责任链模式责任链模式 AOP 思想执行嵌入点Web 容器请求管道Spring MVCDispatcherServlet核心流程一、过滤器Filter底层原理1. 核心设计模式责任链模式Chain of ResponsibilityFilter 是 Servlet 规范对责任链模式的原生实现角色划分Filter抽象处理者每个 Filter 是一个具体处理节点FilterChain责任链管理器串联所有 Filter控制链路流转流转逻辑请求依次经过链上的每个 Filter通过chain.doFilter()显式调用下一个节点最终到达目标 Servlet响应则沿原链路反向返回。2. Servlet 容器的请求处理流程以 Tomcat 为例Filter 的底层执行嵌入在容器的请求管道中客户端请求 → Tomcat Connector接收连接 → Engine → Host → Context → FilterChain依次执行所有 Filter 的 doFilter 前置逻辑 → 目标 Servlet处理业务 → FilterChain依次执行所有 Filter 的 doFilter 后置逻辑 → 响应返回客户端核心机制Filter 是容器级的“请求拦截器”在 Servlet 执行前后插入逻辑完全由 Web 容器而非 Spring管理生命周期。3. 关键组件FilterChain 的实现机制Tomcat 中的FilterChain实现类为ApplicationFilterChain底层是一个数组 索引的结构内部维护Filter[] filters数组存储所有匹配的 Filter维护int pos索引记录当前执行到的 Filter 位置调用chain.doFilter()时若pos filters.length则pos调用下一个 Filter 的doFilter()若pos filters.length则调用目标 Servlet 的service()方法4. 生命周期的底层管理Filter 的生命周期完全由 Web 容器控制实例化容器启动时扫描web.xml、WebFilter或 Spring Boot 的FilterRegistrationBean通过反射创建 Filter 实例单例模式全局唯一初始化调用init(FilterConfig config)传入容器封装的配置信息初始化参数、ServletContext 等销毁容器关闭时调用destroy()释放资源随后 Filter 实例被 GC 回收5.OncePerRequestFilter的避坑原理Spring 提供的OncePerRequestFilter解决了原生 Filter 重复执行的问题底层通过请求属性标记实现在第一次执行时向HttpServletRequest中设置一个属性如filterName.FILTERED后续执行前检查该属性是否存在若存在则跳过核心逻辑确保一次请求仅执行一次doFilterInternal()用户自定义的核心方法二、拦截器Interceptor底层原理1. 核心设计模式责任链模式 Spring AOP 思想Interceptor 是 Spring MVC 基于责任链模式的实现同时融合了 AOP 的“环绕通知”思想责任链模式通过HandlerExecutionChain串联多个 Interceptor按顺序执行前置/后置逻辑AOP 思想在 Controller 方法执行前后插入横切逻辑类似 AOP 的Before、AfterReturning、After但不依赖动态代理而是嵌入在 Spring MVC 的请求分发流程中2. Spring MVC 的请求分发全流程Interceptor 的底层执行嵌入在DispatcherServlet的核心逻辑中客户端请求 → DispatcherServlet 接收 → HandlerMapping 匹配目标 HandlerController 方法 → 组装 HandlerExecutionChain包含 Handler 所有匹配的 Interceptor → 依次执行所有 Interceptor 的 preHandle()正序 → 若所有 preHandle() 返回 true调用 HandlerAdapter 执行 Controller 方法 → 依次执行所有 Interceptor 的 postHandle()倒序 → 视图渲染若需要 → 依次执行所有 Interceptor 的 afterCompletion()倒序 → 响应返回客户端核心机制Interceptor 是 Spring MVC 框架级的“请求拦截器”完全由 Spring 容器管理可访问 Spring 上下文中的所有 Bean。3. 关键组件HandlerExecutionChain 的组装与执行HandlerExecutionChain是 Interceptor 链的核心载体底层结构与执行逻辑如下内部结构Object handler目标 Controller 方法封装为HandlerMethod对象ListHandlerInterceptor interceptors匹配到的 Interceptor 列表int interceptorIndex记录当前执行到的 Interceptor 索引用于倒序执行后置方法执行逻辑preHandle 正序执行遍历interceptors依次调用preHandle()若返回false则直接倒序调用已执行 Interceptor 的afterCompletion()终止请求postHandle 倒序执行Controller 执行完后从interceptorIndex开始倒序调用postHandle()afterCompletion 倒序执行视图渲染完后从interceptorIndex开始倒序调用afterCompletion()4. 与 Spring 容器的集成Bean 注入的原理Interceptor 能直接注入 Spring Bean 的底层原因Interceptor 本身是 Spring 容器管理的 Bean通过Component注册或配置类中Bean声明Spring 在组装HandlerExecutionChain时直接从容器中获取 Interceptor 实例因此支持依赖注入Autowired、构造器注入等对比Filter 由 Web 容器实例化默认无法访问 Spring Bean需通过WebApplicationContextUtils手动获取容器上下文5. 与 Spring AOP 的本质区别虽然 Interceptor 融合了 AOP 思想但与纯 Spring AOP 有本质不同维度InterceptorSpring AOP实现方式嵌入 Spring MVC 请求分发流程基于责任链基于动态代理JDK 动态代理/CGLIB拦截范围仅 Controller 层请求任意 Spring Bean 的方法Service、Dao 等上下文信息可获取HttpServletRequest/HttpServletResponse、HandlerMethod仅能获取方法参数、返回值等方法级信息执行时机仅在 Web 请求流程中生效任意方法调用时生效包括非 Web 场景附2核心区别一句话总结Filter是「Web 容器的门卫」管所有进容器的请求Interceptor是「Spring MVC 的管家」专管业务请求的精细化管控。两者均是基于责任链模式的请求处理组件但在所属层级、依赖环境、能力边界上有本质差异核心区别如下1. 规范归属与管理主体不同过滤器Filter属于Java Servlet/Jakarta EE 官方规范由Web 容器Tomcat、Jetty 等直接管理生命周期脱离 Web 容器无法运行。拦截器Interceptor属于Spring Framework 框架规范由Spring 容器管理生命周期依赖 Spring 环境才能生效。2. 执行层级与触发时机不同过滤器执行在Web 容器层级触发时机为「请求进入容器后、Servlet 执行前」是请求的「第一道关卡」。拦截器执行在Spring MVC 上下文层级触发时机为「请求进入 DispatcherServlet 后、Controller 执行前」嵌入在 Spring MVC 的请求分发流程中。3. 依赖注入与上下文能力不同过滤器默认无法直接注入 Spring Bean需手动获取 Spring 上下文仅能获取ServletRequest/ServletResponse等基础请求/响应信息。拦截器原生支持依赖注入可自由注入 Spring 容器中的任意 Bean还能获取HandlerMethodController 方法元信息、ModelAndView等全量 Spring MVC 上下文。4. 拦截范围与控制粒度不同过滤器拦截所有进入 Web 容器的 HTTP 请求包括静态资源、Servlet、JSP、Spring 接口等控制粒度较粗。拦截器默认仅拦截DispatcherServlet 分发的请求通常是 Controller 接口需手动配置才能拦截静态资源支持基于注解、路径的细粒度控制。5. 异常处理能力不同过滤器抛出的异常无法被 Spring 全局异常处理器RestControllerAdvice捕获需自行处理转发错误页或手动写入响应。拦截器抛出的异常可被 Spring 全局异常处理器统一处理与 Spring 异常体系无缝集成。6. 适用场景不同过滤器适合容器级、全请求通用的无状态处理如请求编码设置CharacterEncodingFilterCORS 跨域处理XSS/CSRF 攻击防护全链路 TraceId 透传拦截器适合业务级、依赖 Spring 上下文的细粒度处理如登录认证、权限校验接口访问日志、执行耗时统计接口幂等性校验业务级限流、灰度发布控制