Filter-拦截机制
[TOC]
FilterChain 过滤链
双向调用栈与洋葱模型
在实际 Web 应用中,单个请求往往会同时命中多个过滤器的拦截规则(例如依次经过字符集编码过滤器、跨域过滤器、认证过滤器与日志过滤器)。Web 容器会将当前请求匹配到的所有 Filter 按既定顺序串联起来,组装成一个 jakarta.servlet.FilterChain(过滤链)实例,采用责任链设计模式(Chain of Responsibility Pattern)协调各节点的执行。

前置正序与后置逆序
FilterChain 的执行并非简单的线性单向传递,而是依托 JVM 方法调用栈形成的双向洋葱模型(Onion Model)。假设过滤链中依次包含 Filter A 与 Filter B,终端为目标 Servlet:
前置入栈(FIFO 先进先出):请求到达时,容器首先调用
Filter A的拦截方法(执行A的前置逻辑);当Filter A调用放行方法时,Filter A的方法栈帧挂起,控制权压栈进入Filter B(执行B的前置逻辑);Filter B再次调用放行方法后,最终压栈调用目标Servlet的业务方法。后置出栈(LIFO 后进先出):目标
Servlet执行完毕返回后,首先恢复栈顶Filter B的方法栈帧(执行B放行语句之后的后置逻辑);待Filter B执行完毕返回后,再恢复最外层Filter A的方法栈帧(执行A的后置逻辑),最后将响应交还给 Web 容器。
因此,多个过滤器的整体执行轨迹严格遵循对称嵌套顺序:
**Filter A 前置 -> Filter B 前置 -> Servlet 执行 -> Filter B 后置 -> Filter A 后置**。
多过滤器协同示例
以下示例展示了外层日志过滤器 LogFilter 在过滤链中的环绕执行过程。当其与下游过滤器组合时,前置输出与后置输出将自然包裹所有下游节点的执行逻辑:
package com.example.filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
// 1. 外层日志过滤器:最先执行前置逻辑,最后执行后置逻辑
public class LogFilter extends HttpFilter {
// 2. 重写 HTTP 拦截方法,围绕放行调用构建环绕通知
@Override
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
System.out.println("[LogFilter] 1. 前置处理:请求进入");
// 3. 压栈放行:将控制权移交至链中下一个 Filter 或目标 Servlet
chain.doFilter(request, response);
// 4. 出栈回溯:下游节点全部执行完毕后,恢复当前栈帧执行后置逻辑
System.out.println("[LogFilter] 4. 后置处理:响应返回");
}
}过滤链排序规则
当多个过滤器同时匹配同一个请求时,它们在 FilterChain 中的排列先后顺序直接关系到业务正确性(例如“编码过滤器”必须排在任何读取请求参数的“认证过滤器”之前)。Servlet 规范从映射匹配维度与注册声明来源两个层级严格定义了过滤链的组装顺序。
映射维度优先级
Web 容器在组装 FilterChain 时,首先按照过滤器的映射绑定类型将匹配的过滤器划分为两个梯队:
第一梯队(URL 路径匹配):所有通过
url-pattern(如/*、/api/*、*.do)匹配成功的过滤器,全部排在过滤链的前半段。注意:不同 URL 模式之间不按路径长短或精确度排序(即/api/user/login不会因为比/*更精确而排在前面),而是完全取决于注册声明顺序。第二梯队(Servlet 名称匹配):所有通过
servlet-name直接绑定到目标Servlet逻辑名称的过滤器,全部排在所有 URL 路径匹配过滤器的后面。
注册源顺序规则
在同一映射梯队内部,过滤器的先后顺序由其注册方式决定:
web.xml声明顺序:在web.xml中注册的过滤器,严格按照<filter-mapping>标签在 XML 文件中出现的先后顺序排列(与<filter>定义标签的顺序无关)。@WebFilter扫描顺序:Servlet 规范并未规定@WebFilter注解过滤器的执行顺序。在 Tomcat 等主流容器中,注解过滤器的顺序取决于类路径下字节码文件的扫描顺序或过滤器全限定类名的字典序(ASCII 码顺序)。由于依赖类名排序极易在重构重命名时破坏业务逻辑,当多个过滤器存在强顺序依赖时,应改用web.xml或编程式动态注册。FilterRegistration动态插队顺序:通过ServletContext.addFilter动态注册过滤器并在调用映射绑定方法时,由布尔参数isMatchAfter控制排队位置:isMatchAfter = false:将当前过滤器插入到web.xml已声明映射规则的最前面(按动态调用顺序依次前置)。isMatchAfter = true:将当前过滤器追加到web.xml已声明映射规则的末尾(按动态调用顺序依次后置)。
| 排序层级 | 排序维度 / 注册来源 | 排序决定依据 | 相对执行顺位 |
|---|---|---|---|
| 一级划分 | url-pattern 映射 | 命中请求 URL 路径规则 | 最先执行(位于链前半段) |
| 一级划分 | servlet-name 映射 | 命中目标 Servlet 名称 | 随后执行(位于链后半段) |
| 二级排序 | FilterRegistration (isMatchAfter=false) | 动态注册 API 的调用先后顺序 | 同梯队内排在 web.xml 之前 |
| 二级排序 | web.xml 配置 | <filter-mapping> 标签在文件中的书写顺序 | 同梯队内居中基准顺序 |
| 二级排序 | FilterRegistration (isMatchAfter=true) | 动态注册 API 的调用先后顺序 | 同梯队内排在 web.xml 之后 |
| 二级排序 | @WebFilter 注解 | 容器字节码扫描顺序(通常为类名 ASCII 字典序) | 追加在显式配置之后(不可控) |
ApplicationFilterChain
在 Tomcat 容器内部,FilterChain 接口的标准实现类是 org.apache.catalina.core.ApplicationFilterChain。理解该类的内部结构有助于看清过滤链是如何在不借助复杂链表指针的情况下完成递归派发的。

请求级动态组装
与 Filter 实例在容器启动时创建并全局单例复用不同,ApplicationFilterChain 是请求级(Per-Request)的临时对象:
每当客户端请求进入 Tomcat 的
StandardWrapperValve(基础阀门)时,容器会调用工厂类ApplicationFilterFactory.createFilterChain(request, wrapper, servlet)。工厂方法首先创建一个全新的
ApplicationFilterChain实例,并将本次请求最终要访问的目标Servlet引用注入到该过滤链对象的servlet属性中。随后,工厂方法遍历当前
StandardContext中注册的所有FilterMap;凡是派发类型(DispatcherType)与路径规则匹配当前请求的过滤器,都会被依次追加到ApplicationFilterChain内部的数组中。
游标递归派发源码
ApplicationFilterChain 底层并非采用节点链表结构,而是通过一个 ApplicationFilterConfig[] 数组 配合整型游标 pos 实现链式推进。其核心派发逻辑提炼如下:
package org.apache.catalina.core;
import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.Servlet;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import java.io.IOException;
// 1. Tomcat 过滤链核心实现类,每个请求独立创建一个实例
public final class ApplicationFilterChain implements FilterChain {
// 2. 存储当前请求匹配到的所有过滤器配置数组
private ApplicationFilterConfig[] filters = new ApplicationFilterConfig[0];
// 3. 维护当前执行到的数组游标位置(pos)与实际过滤器总数(n)
private int pos = 0;
private int n = 0;
// 4. 维护过滤链末端待调用的目标 Servlet 实例
private Servlet servlet = null;
// 5. 推进游标并递归派发下一个过滤器,到达链尾时触发目标 Servlet
@Override
public void doFilter(ServletRequest request, ServletResponse response)
throws IOException, ServletException {
// 6. 游标尚未到达末尾:取出当前过滤器并将游标自增,传入 this 实现链式递归
if (pos < n) {
ApplicationFilterConfig filterConfig = filters[pos++];
Filter filter = filterConfig.getFilter();
filter.doFilter(request, response, this);
return;
}
// 7. 游标已到达末尾(pos == n):所有过滤器前置放行完毕,正式调用目标 Servlet
servlet.service(request, response);
}
}从上述核心源码可以清晰看到过滤链推进的两个关键节点:
- 游标自增与
this传递:每当某个Filter内部调用chain.doFilter(request, response)时,实际上就是再次调用同一个ApplicationFilterChain实例的doFilter方法。此时游标pos++向后移动一位,取出下一个Filter并再次将this(当前过滤链自身)传入。 - 末端触发目标资源:当最后一个
Filter调用chain.doFilter(request, response)时,此时游标pos已经等于过滤器总数n,不再进入if (pos < n)分支,而是直接执行servlet.service(request, response),从而完成从过滤链到业务Servlet的平滑交接。
放行与短路边界陷阱
在编写 Filter 操作 FilterChain 时,若对方法调用栈与响应提交流程理解不透彻,极易引发运行时异常或权限绕过漏洞。
短路拦截遗漏返回
当过滤器在前置校验中发现请求不合法(如未登录或参数非法),通常会调用 response.sendRedirect()、response.sendError() 或执行请求转发以中断流程。
常见误区:部分开发者误以为调用 sendRedirect() 会像 throw 关键字一样自动终止当前方法的执行,从而漏写了 return; 语句。实际上,sendRedirect() 只是一个普通的 Java 方法调用(负责设置 302 状态码与 Location 响应头并提交响应缓冲区);若其后未显式编写 return;,代码会继续向下执行 chain.doFilter(request, response):
安全绕过风险:未授权的请求依然穿透了过滤器,触发了下游
Servlet的敏感数据库修改操作。响应已提交异常:当下游
Servlet尝试再次重定向、转发或向已关闭的响应流写入数据时,容器会直接抛出IllegalStateException: Cannot call sendRedirect() after the response has been committed。
以下示例展示了短路拦截时正确的返回控制规范:
package com.example.filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpSession;
import java.io.IOException;
// 1. 登录态校验过滤器:演示短路拦截时的正确返回规范
public class SessionAuthFilter extends HttpFilter {
// 2. 校验当前会话是否包含已登录用户信息
@Override
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
HttpSession session = request.getSession(false);
// 3. 未登录时发送重定向响应,并立即通过 return 终止当前方法栈
if (session == null || session.getAttribute("currentUser") == null) {
response.sendRedirect(request.getContextPath() + "/login.jsp");
return;
}
// 4. 仅当校验通过未触发 return 时,才继续向后放行请求
chain.doFilter(request, response);
}
}重复触发链式放行
在单次 doFilter 方法执行周期内,若因条件分支编写不当(例如在 if 分支内调用了一次 chain.doFilter,在 if 块外部又调用了一次 chain.doFilter),会导致下游过滤器与目标 Servlet 被重复调用:
- 第一次
chain.doFilter执行时,游标pos已经递增至链尾n并执行完servlet.service(request, response)。 - 当退回当前过滤器并触发第二次
chain.doFilter时,由于游标pos依然满足pos == n,会直接越过所有下游过滤器,**再次触发servlet.service(request, response)**,导致业务接口被重复执行两次。
跨请求共享过滤链实例
FilterChain 实例内部维护着强状态的游标 pos、当前请求匹配的过滤器数组以及目标 Servlet 引用,且在请求结束回收时 Tomcat 会调用 release() 方法清空内部数组引用。因此,严禁将 FilterChain 赋值给 Filter 的实例成员变量,或将其传递至异步子线程中延迟调用,必须在当前请求线程的 doFilter 栈帧内同步完成放行调用。
API: FilterChain
过滤链推进
voiddoFilter():(ServletRequest request, ServletResponse response),过滤链向下游推进。由当前过滤器调用以唤醒过滤链中的下一个过滤器;若当前过滤器已是链中的最后一个节点,则由容器触发链尾的目标 Servlet 或静态资源处理请求。
注意事项:
- 在单次
Filter.doFilter()执行过程中,切勿重复调用chain.doFilter(request, response),否则会导致下游过滤器与目标 Servlet 被重复执行,并极易因响应流已提交(Committed)而抛出IllegalStateException。- 容器提供的
FilterChain实现类(如 Tomcat 的ApplicationFilterChain)内部通过游标索引维护当前请求的执行位置,属于请求级有状态对象且非线程安全;严禁将其缓存至过滤器成员变量,或在未开启异步处理(ServletRequest.startAsync())的情况下直接交由自定义后台线程异步调用。- 调用
chain.doFilter(request, response)时,可传入自定义的ServletRequestWrapper或ServletResponseWrapper包装对象,从而替换后续所有过滤器及目标 Servlet 接收到的请求或响应实例。
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
// 1. 实现 FilterChain 接口,通过游标索引模拟容器过滤链的顺序推进与回栈过程
public class FilterChainAdvanceDemo implements FilterChain {
private final List<Filter> filters = new ArrayList<>();
private int cursor = 0;
public void addFilter(Filter filter) {
this.filters.add(filter);
}
// 2. 重写 doFilter 方法,按游标依次唤醒下游 Filter,链尾则触发目标资源逻辑
@Override
public void doFilter(ServletRequest request, ServletResponse response)
throws IOException, ServletException {
if (this.cursor < this.filters.size()) {
Filter currentFilter = this.filters.get(this.cursor++);
// 3. 将当前 FilterChain 自身传入下游过滤器,由其决定是否继续调用 doFilter 放行
currentFilter.doFilter(request, response, this);
} else {
System.out.println(" -> [目标Servlet] 所有前置过滤已完成,正在执行核心业务");
}
}
public static void main(String[] args) throws IOException, ServletException {
// 4. 构建过滤链实例并注册两个过滤器,调用 doFilter 启动整条责任链调用
FilterChainAdvanceDemo chain = new FilterChainAdvanceDemo();
chain.addFilter((req, res, fc) -> {
System.out.println("[LogFilter] 前置:记录请求到达日志");
fc.doFilter(req, res);
System.out.println("[LogFilter] 后置:记录响应完成日志");
});
chain.addFilter((req, res, fc) -> {
System.out.println(" [AuthFilter] 前置:校验访问令牌通过");
fc.doFilter(req, res);
System.out.println(" [AuthFilter] 后置:清理安全上下文");
});
chain.doFilter(null, null);
}
}DispatcherType 派发拦截
容器内部派发与过滤链重建
在探讨 FilterChain 组装机制时,有一个极易被忽视的底层事实:单次客户端 HTTP 请求在 Web 容器内部并不一定只生成一条过滤链。
当客户端请求首次进入 Tomcat 容器时,连接器(Connector)将其交给基础阀门 StandardWrapperValve,此时容器会根据请求 URL 组装第一条 ApplicationFilterChain 并依次执行匹配的过滤器。然而,当请求穿过这条初始过滤链到达目标 Servlet 后,服务端可能会触发多种容器内部二次派发(Internal Dispatch)行为:
- 调用
RequestDispatcher.forward()将请求在服务端内部转发给另一个Servlet或 JSP 视图。 - 调用
RequestDispatcher.include()将另一个动态资源的输出合并到当前响应流中。 - 目标
Servlet抛出未捕获异常或调用response.sendError(),触发容器根据<error-page>配置自动跳转至错误处理器。 - 在异步处理模式下,后台线程调用
AsyncContext.dispatch()将请求重新派发回容器工作线程。
每发生一次上述内部派发,容器都会针对新的目标路径重新调用 ApplicationFilterFactory.createFilterChain() 构建一条全新的过滤链。为了精确控制某个 Filter 究竟应该在“初始外部请求”阶段生效,还是在“内部二次派发”阶段生效,Servlet 2.4 引入了 jakarta.servlet.DispatcherType 枚举。
在 Tomcat 的 ApplicationFilterFactory 源码中,一个 Filter 能否进入当前构建的 ApplicationFilterChain,必须同时通过以下两道校验:
派发类型校验(
matchDispatcher):检查当前过滤器注册的DispatcherType集合是否包含当前触发动作的派发类型。路径或组件名校验(
matchFiltersURL/matchFiltersServlet):检查当前过滤器的 URL 模式或Servlet名称是否匹配本次派发的目标资源。

DispatcherType
jakarta.servlet.DispatcherType 是一个包含五个常量的枚举类,完整覆盖了 Web 容器中所有可能触发资源调用的入口场景。
REQUEST
代表直接来自客户端(浏览器、移动端或 HTTP 客户端工具)的原始网络请求。
- 默认拦截策略:无论使用
web.xml、@WebFilter还是FilterRegistration注册过滤器,只要开发者未显式声明派发类型,**容器默认仅绑定DispatcherType.REQUEST**。 - 重定向触发归属:当服务端调用
response.sendRedirect("/target")时,容器向客户端返回302状态码与Location响应头,随后由浏览器主动发起针对/target的第二次网络请求。因此,重定向产生的第二次请求依然属于REQUEST类型,必定会触发目标路径上的默认过滤器。
FORWARD
代表服务端通过 RequestDispatcher.forward(request, response) 发起的内部请求转发。
- 默认跳过行为:在经典的 MVC 架构中,控制器
Servlet(如/order/detail)处理完业务逻辑后,通常会通过forward内部转发至视图页面(如/WEB-INF/views/detail.jsp)。由于过滤器默认仅拦截REQUEST,当容器为detail.jsp组装第二条过滤链时,所有默认过滤器均会因派发类型不匹配(当前为FORWARD)而被跳过,直接渲染 JSP。 - 新路径匹配基准:若某个过滤器显式开启了
FORWARD拦截,容器在组装转发过滤链时,将以转发后的目标路径(即/WEB-INF/views/detail.jsp)而非原始请求路径(/order/detail)来比对过滤器的url-pattern。
INCLUDE
代表服务端通过 RequestDispatcher.include(request, response) 发起的动态资源包含调用(或 JSP 中的 <jsp:include> 标签)。
- 当主请求资源通过
include引入局部组件(如页头/common/header.jsp)时,若存在配置了DispatcherType.INCLUDE且路径匹配/common/*的过滤器,容器会在执行被包含资源前先运行该过滤器链。
ERROR
代表当请求处理期间发生未捕获异常,或显式调用了 response.sendError() 状态码,Web 容器根据 web.xml 中配置的 <error-page> 规则将控制权内部转发给错误处理页面或错误处理 Servlet 的派发过程。
- 错误页派发是容器在捕获异常后在内部自动发起的二次跳转,其派发类型被标记为
ERROR。默认仅拦截REQUEST的过滤器不会在跳转到错误页时再次执行,从而避免因异常状态再次触发前置业务拦截。
ASYNC
代表在 Servlet 3.0+ 异步处理模型中,主请求线程调用 request.startAsync() 开启异步上下文后先行退出,随后由异步工作线程调用 AsyncContext.dispatch() 将请求重新派发回容器以生成响应的过程。
- 当异步任务完成并执行
dispatch回容器时,派发类型变为ASYNC。需要在异步回调阶段继续生效的过滤器(如请求上下文恢复过滤器、安全上下文绑定过滤器)必须显式声明支持ASYNC。
| 枚举常量 | 触发机制 | 默认是否启用 | 路径匹配基准 |
|---|---|---|---|
REQUEST | 客户端直接发起 HTTP 请求(含 sendRedirect 后的新请求) | 是(唯一默认值) | 客户端原始请求 URI |
FORWARD | 服务端调用 RequestDispatcher.forward() | 否 | 内部转发的目标资源路径 |
INCLUDE | 服务端调用 RequestDispatcher.include() | 否 | 被动态包含的目标资源路径 |
ERROR | 容器命中 <error-page> 自动跳转至错误处理器 | 否 | <location> 指定的错误处理路径 |
ASYNC | 异步线程调用 AsyncContext.dispatch() 重新派发 | 否 | 异步派发指定的目标路径 |
派发拦截配置与运行时判定
声明式与编程式配置
若业务需要过滤器在内部转发或错误页跳转时同样生效,必须在注册配置中显式声明目标派发类型(注意:一旦显式配置了派发类型,默认的 REQUEST 会被覆盖;若仍需拦截直接请求,必须将 REQUEST 一并写入)。
在 web.xml 的 <filter-mapping> 标签中,可通过添加多个 <dispatcher> 子标签开启多类型拦截:
<!-- 1. 绑定过滤器的拦截路径,并显式声明需要拦截的派发类型 -->
<filter-mapping>
<filter-name>securityFilter</filter-name>
<url-pattern>/admin/*</url-pattern>
<!-- 2. 同时拦截客户端直接请求与服务器内部转发,防止转发绕过权限校验 -->
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>在编程式动态注册中,则通过 EnumSet.of(DispatcherType.REQUEST, DispatcherType.FORWARD) 作为第一个参数传入 addMappingForUrlPatterns 方法。
运行时派发类型判定
当一个过滤器同时绑定了多种 DispatcherType 时,在 doFilter 方法内部可以通过调用 request.getDispatcherType() 动态获取当前触发过滤链的具体派发枚举值,从而针对不同阶段执行差异化逻辑。
以下示例展示了同时监听 REQUEST、FORWARD 与 ERROR 的审计过滤器如何区分不同派发阶段:
package com.example.filter;
import jakarta.servlet.DispatcherType;
import jakarta.servlet.FilterChain;
import jakarta.servlet.RequestDispatcher;
import jakarta.servlet.ServletException;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
// 1. 声明过滤器同时拦截直接请求、内部转发与异常错误页派发
@WebFilter(
urlPatterns = "/*",
dispatcherTypes = {
DispatcherType.REQUEST,
DispatcherType.FORWARD,
DispatcherType.ERROR
}
)
public class AuditDispatchFilter extends HttpFilter {
// 2. 根据当前请求的实际派发类型执行差异化审计逻辑
@Override
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
// 3. 获取当前触发过滤链的派发类型枚举值
DispatcherType currentType = request.getDispatcherType();
// 4. 针对容器错误页派发,提取原始异常状态码与出错 URI
if (currentType == DispatcherType.ERROR) {
Integer statusCode = (Integer) request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
String errorUri = (String) request.getAttribute(RequestDispatcher.ERROR_REQUEST_URI);
System.out.println("异常派发拦截: URI=" + errorUri + ", 状态码=" + statusCode);
}
// 5. 放行请求至下游过滤链节点或目标资源
chain.doFilter(request, response);
}
}派发拦截边界陷阱
对 DispatcherType 理解不当是导致 Web 应用出现权限绕过漏洞、栈溢出死循环以及性能损耗的高频原因。
内部转发绕过权限校验
假设系统配置了一个保护后台资源的权限过滤器 AdminAuthFilter,其拦截路径为 /admin/*,并保留了默认的 DispatcherType.REQUEST 配置。
- 当攻击者直接在浏览器访问
/admin/deleteUser时,派发类型为REQUEST,AdminAuthFilter正常触发并拦截未授权访问。 - 但如果系统中存在一个公开免登录的通用跳转接口(例如
/public/router?page=/admin/deleteUser),该接口内部通过request.getRequestDispatcher(page).forward(req, res)将请求转发至/admin/deleteUser:
首次请求访问
/public/router时,路径不匹配/admin/*,AdminAuthFilter不执行。内部转发至
/admin/deleteUser时,路径虽然匹配/admin/*,但此时的派发类型已变为FORWARD。由于
AdminAuthFilter仅拦截REQUEST,容器在组装转发过滤链时会直接跳过AdminAuthFilter,导致后台敏感接口被完全绕过!
防范准则:凡是基于路径前缀(如 /admin/*、/pay/*)保护敏感资源的权限校验过滤器,应当同时配置 DispatcherType.REQUEST 与 DispatcherType.FORWARD。
转发与错误页递归死循环
当过滤器开启了 FORWARD(或 ERROR)拦截,且自身的拦截路径范围较广(例如 /*)时,如果在过滤器内部因为校验失败而直接执行 forward(或 sendError),极易引发无限递归死循环:
客户端访问
/order/list,命中/*过滤器(REQUEST阶段)。过滤器发现用户未登录,执行
request.getRequestDispatcher("/login.jsp").forward(req, res)。容器发起针对
/login.jsp的FORWARD派发;由于/login.jsp同样命中/*,且过滤器开启了FORWARD拦截,容器再次调用该过滤器的doFilter方法。过滤器再次判定未登录,再次执行
forward("/login.jsp"),如此无限压栈递归,最终直接耗尽线程栈内存并抛出java.lang.StackOverflowError。
防范准则:在开启了 FORWARD 或 ERROR 拦截的过滤器中,必须将内部转发的目标路径(如 /login.jsp)或错误页路径(如 /error/500.jsp)纳入前置白名单直接放行:
package com.example.filter;
import jakarta.servlet.DispatcherType;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
// 1. 开启 REQUEST 与 FORWARD 双重拦截,防范内部转发绕过权限控制
@WebFilter(
urlPatterns = "/*",
dispatcherTypes = {DispatcherType.REQUEST, DispatcherType.FORWARD}
)
public class ForwardAuthFilter extends HttpFilter {
// 2. 拦截直接请求与内部转发,必须放行登录转发目标页以避免递归死循环
@Override
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
// 3. 白名单放行:若当前请求或内部转发的目标正是登录页,直接放行
String path = request.getServletPath();
if ("/login.jsp".equals(path) || "/login".equals(path)) {
chain.doFilter(request, response);
return;
}
// 4. 未登录时内部转发至 /login.jsp(此操作会触发新一轮 FORWARD 类型的过滤链)
if (request.getSession(false) == null) {
request.getRequestDispatcher("/login.jsp").forward(request, response);
return;
}
// 5. 已登录请求正常放行
chain.doFilter(request, response);
}
}全局过滤器重复执行
对于绑定在 /* 上的全局基础设施过滤器(如统一请求耗时统计过滤器、统一数据库连接事务过滤器或请求体流包装过滤器),如果盲目配置了 REQUEST 与 FORWARD 双重拦截:
- 每当业务
Servlet处理完请求并forward到 JSP 视图时,该全局过滤器都会在单次 HTTP 请求周期内被完整执行两次(一次包裹Servlet+JSP,内部嵌套另一次单独包裹JSP),导致接口访问日志重复打印、监控计时翻倍或包装器重复嵌套。 - 在后续学习 Spring 框架时会看到,Spring 专门提供了
OncePerRequestFilter基类(通过在request属性域中打标记),正是为了确保过滤器在跨多次内部派发(REQUEST->FORWARD->ERROR)时,在单次物理请求内严格只执行一次。
Wrapper 请求响应包装
装饰器模式与包装体系
在前面的章节中,Filter 对请求与响应的操作均局限于调用原生 HttpServletRequest 与 HttpServletResponse 已经暴露的写方法(如 request.setCharacterEncoding()、request.setAttribute() 或 response.setHeader())。然而在实际工程中,原生请求与响应对象存在诸多不可变限制与流读取瓶颈:
- 请求参数只读限制:
ServletRequest仅提供了getParameter()等参数读取方法,并未提供setParameter()或removeParameter()方法。当过滤器需要对请求参数执行首尾空格裁剪、敏感词过滤或 XSS 脚本转义时,无法直接修改容器底层的参数哈希表。 - 请求体流单次消费限制:客户端通过 POST/PUT 提交的 JSON 或 XML 请求体承载在网络底层
ServletInputStream中。该网络流基于游标单向读取且不支持重置;一旦过滤器为了记录审计日志或校验接口签名而提前读取了request.getInputStream(),下游的目标Servlet(或 Spring MVC 的@RequestBody)再次读取时只会得到空流或触发流已关闭异常。 - 响应流直接刷写限制:当目标
Servlet调用response.getWriter().write()时,数据会直接写入 Web 容器的底层网络输出缓冲区(如 Tomcat 的OutputBuffer)。当控制权回溯到过滤器的后置代码时,过滤器既无法从response中读出已经写入的业务报文,也无法在报文发送前对其进行统一加密、水印追加或 GZIP 压缩。
为了在不破坏容器底层实现类(如 Tomcat 的 RequestFacade 与 ResponseFacade)的前提下突破上述限制,Servlet 规范基于装饰器设计模式(Decorator Pattern)提供了四个标准包装基类:
协议无关包装基类:
jakarta.servlet.ServletRequestWrapper与jakarta.servlet.ServletResponseWrapper,分别实现ServletRequest与ServletResponse接口,内部持有一个被包装的原始请求或响应对象引用,并将所有接口方法默认原样委托(Delegate)给底层被包装对象执行。HTTP 协议包装基类:
jakarta.servlet.http.HttpServletRequestWrapper与jakarta.servlet.http.HttpServletResponseWrapper,分别继承自上述两个通用包装基类并实现HttpServletRequest与HttpServletResponse接口。
开发者只需编写自定义类继承 HttpServletRequestWrapper 或 HttpServletResponseWrapper,按需重写需要增强的个别方法,然后在 Filter 中使用自定义包装器实例替换原始对象传入 chain.doFilter(wrappedRequest, wrappedResponse)。此时,下游所有的 Filter 以及最终的目标 Servlet 拿到的实际上都是经过“偷梁换柱”的包装器对象。


HttpServletRequestWrapper
继承 HttpServletRequestWrapper 可以透明地拦截下游组件对请求头、请求参数及请求体输入流的读取行为。
请求参数增强与清洗
当需要对全站请求参数执行统一清洗(如防范跨站脚本攻击 XSS 或过滤非法字符)时,无需在业务 Servlet 中逐一处理每个字段。通过继承 HttpServletRequestWrapper 并重写参数读取方法,可以在下游组件调用 request.getParameter() 的瞬间完成实时转义:
package com.example.wrapper;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequestWrapper;
// 1. 继承 HttpServletRequestWrapper,仅重写需要增强的参数获取方法
public class XssRequestWrapper extends HttpServletRequestWrapper {
// 2. 调用父类构造器保存底层原始 HttpServletRequest 引用
public XssRequestWrapper(HttpServletRequest request) {
super(request);
}
// 3. 重写单值参数读取方法,对原始参数值执行转义清洗
@Override
public String getParameter(String name) {
String rawValue = super.getParameter(name);
return sanitize(rawValue);
}
// 4. 将尖括号等特殊字符替换为 HTML 实体,阻断恶意脚本注入
private String sanitize(String input) {
if (input == null || input.isEmpty()) {
return input;
}
return input.replace("<", "<").replace(">", ">");
}
}请求体流缓存与重复读取
针对 request.getInputStream() 与 request.getReader() 只能读取一次的痛点,核心解决思路是将一次性网络输入流转化为可重复读取的内存字节数组:
在构造自定义
HttpServletRequestWrapper时,立即从原始request中读取完整的输入流字节,并将其保存在包装器内部的byte[]成员变量中。重写
getInputStream()与getReader()方法,每次被调用时不再访问底层已耗尽的网络流,而是基于内部的byte[]数组重新构造一个新的ByteArrayInputStream包装流返回。javapackage com.example.wrapper; import jakarta.servlet.ReadListener; import jakarta.servlet.ServletInputStream; import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletRequestWrapper; import java.io.BufferedReader; import java.io.ByteArrayInputStream; import java.io.IOException; import java.io.InputStreamReader; // 1. 包装请求对象,将一次性网络输入流提前转存为内存字节数组 public class CachedBodyRequestWrapper extends HttpServletRequestWrapper { // 2. 缓存完整请求体字节数据,支持下游多次读取 private final byte[] cachedBody; // 3. 在构造阶段一次性读取原始输入流并持久化至字节数组中 public CachedBodyRequestWrapper(HttpServletRequest request) throws IOException { super(request); this.cachedBody = request.getInputStream().readAllBytes(); } // 4. 每次调用均基于内存字节数组创建全新的流实例,打破单次读取限制 @Override public ServletInputStream getInputStream() { ByteArrayInputStream byteStream = new ByteArrayInputStream(this.cachedBody); return new ServletInputStream() { @Override public int read() { return byteStream.read(); } @Override public boolean isFinished() { return byteStream.available() == 0; } @Override public boolean isReady() { return true; } @Override public void setReadListener(ReadListener listener) { } }; } // 5. 重写字符流获取方法,使其同样桥接至可重复读取的内存字节流 @Override public BufferedReader getReader() { return new BufferedReader(new InputStreamReader(this.getInputStream())); } }
HttpServletResponseWrapper
与请求包装器在前置阶段拦截数据读取不同,HttpServletResponseWrapper 的核心作用是劫持响应输出流(Response Buffer Hijacking),阻止目标 Servlet 将响应数据直接刷写至客户端,从而允许过滤器在后置阶段对响应报文进行捕获与二次加工。
内存缓冲流劫持原理
使用 HttpServletResponseWrapper 篡改响应体遵循标准的四步闭环流程:
替换输出通道:在自定义
HttpServletResponseWrapper内部维护一个内存缓冲区(字符数据使用CharArrayWriter,二进制字节数据使用ByteArrayOutputStream),并重写getWriter()或getOutputStream()方法,使其返回指向该内存缓冲区的流对象。诱导下游写入:过滤器在前置阶段调用
chain.doFilter(request, responseWrapper)。目标Servlet在毫不知情的情况下调用response.getWriter().write(),所有产出的数据全部被截留保存在包装器的内存缓冲区中,容器真实的底层网络流此时分毫无损。提取与加工:当
chain.doFilter返回至过滤器的后置阶段时,从responseWrapper的内存缓冲区中提取出目标Servlet写入的完整内容,执行替换、追加、加密或 GZIP 压缩。重置长度并真实写出:根据加工后的最新字节大小,调用原始
response.setContentLength()更新响应头,最后将加工后的数据写入原始response的真实输出流中。
响应截留与改写实现
以下首先定义基于 CharArrayWriter 的字符响应包装器 CharResponseWrapper:
package com.example.wrapper;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponseWrapper;
import java.io.CharArrayWriter;
import java.io.PrintWriter;
// 1. 继承 HttpServletResponseWrapper,拦截并缓存下游写入的字符响应流
public class CharResponseWrapper extends HttpServletResponseWrapper {
// 2. 声明内存字符缓冲流,替代底层真实的网络 Socket 输出流
private final CharArrayWriter charWriter = new CharArrayWriter();
private final PrintWriter printWriter = new PrintWriter(charWriter);
// 3. 绑定原始响应对象引用
public CharResponseWrapper(HttpServletResponse response) {
super(response);
}
// 4. 重写获取字符流方法,诱导目标 Servlet 将响应内容写入内存缓冲区
@Override
public PrintWriter getWriter() {
return this.printWriter;
}
// 5. 刷新打印流并提取内存缓冲区中暂存的完整响应字符串
public String getBufferedContent() {
this.printWriter.flush();
return this.charWriter.toString();
}
}随后在过滤器 ResponseWatermarkFilter 中结合该包装器,在后置阶段提取响应正文并统一追加版权注释后写回客户端:
package com.example.filter;
import com.example.wrapper.CharResponseWrapper;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
// 1. 结合响应包装器,在后置阶段统一篡改并输出最终响应报文
@WebFilter("/article/*")
public class ResponseWatermarkFilter extends HttpFilter {
// 2. 传入包装器放行请求,待下游执行完毕后二次加工响应体
@Override
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
// 3. 创建自定义响应包装器,并将包装器传入过滤链向下游传递
CharResponseWrapper responseWrapper = new CharResponseWrapper(response);
chain.doFilter(request, responseWrapper);
// 4. 提取目标 Servlet 写入内存缓冲区的原始响应内容并追加版权声明
String rawContent = responseWrapper.getBufferedContent();
String modifiedContent = rawContent + "\n<!-- Powered by Servlet Filter -->";
// 5. 重新计算字节长度并写入原始 response 的真实输出流
byte[] outputBytes = modifiedContent.getBytes(StandardCharsets.UTF_8);
response.setContentLength(outputBytes.length);
response.getWriter().write(modifiedContent);
}
}包装器使用边界陷阱
在自定义与传递请求响应包装器时,存在四个极易引发数据丢失或协议异常的边界问题:
放行参数传参错位
在 Filter 中实例化 requestWrapper 或 responseWrapper 后,调用 chain.doFilter() 时必须传入包装后的对象引用。若因疏忽仍写作 chain.doFilter(request, response),下游 Servlet 将继续直接操作容器原始请求与响应对象:不仅重写的 getParameter() 逻辑完全失效,响应包装器中的内存缓冲区也会始终为空,导致后置阶段写出空响应。
响应内容长度失配与截断
当通过 HttpServletResponseWrapper 对响应正文进行了增删修改或 GZIP 压缩后,响应体的实际字节长度已经发生改变。
- 若目标
Servlet或框架在执行期间预先设置了Content-Length响应头,且过滤器在修改内容后未重新调用response.setContentLength(newByteLength): - 修改后变长:客户端浏览器按旧的较小
Content-Length读取字节后会立即停止接收,导致末尾新增的响应内容被硬性截断。 - 修改后变短(如压缩):客户端会一直阻塞等待剩余字节到达,直到触发连接读取超时(Read Timeout)。
表单参数解析与流读取冲突
在使用 CachedBodyRequestWrapper 提前调用 request.getInputStream().readAllBytes() 缓存请求体时,必须检查当前请求的 Content-Type:
- 对于
application/json、application/xml或text/plain类型的请求,容器本身不会解析请求体,直接读取输入流是完全安全的。 - 但对于
application/x-www-form-urlencoded类型的普通表单 POST 请求,Servlet 规范约定:当首次调用request.getParameter()时,由容器内部自动读取InputStream并解析填充至参数 Map 中。若过滤器在构造包装器时提前把底层InputStream读空,会导致容器后续调用getParameter()时无法从底层流中解析出任何表单键值对(除非包装器自行解析表单字节并重写getParameterMap())。因此,流缓存包装器应仅针对非表单类型的 JSON/XML 请求启用。
大文件流内存溢出风险
无论是 CachedBodyRequestWrapper 将请求体存入 byte[],还是 CharResponseWrapper 将响应体存入内存缓冲区,本质上都是以 JVM 堆内存空间换取可重复读写能力。
因此,严禁对文件上传接口(multipart/form-data)或大文件下载接口(application/octet-stream、视频流、导出大型报表)启用内存缓存包装器;否则单个数百兆的文件流即可瞬间撑爆 JVM 年老代,直接引发 java.lang.OutOfMemoryError: Java heap space。