Filter-基础
[TOC]
概述
横切关注点与拦截定位
在标准 Servlet 开发模型中,每一个 Servlet 实例专注于处理特定 URL 的业务逻辑(如订单查询、用户注册)。然而在实际 Web 应用中,大量非业务性质的公共逻辑需要跨越多个甚至所有请求重复执行,这类逻辑被称为横切关注点(Cross-Cutting Concerns):
- 字符集编码统一:在读取请求参数前统一设置字符编码,避免中文乱码。
- 认证与权限校验:检查客户端是否携带合法的
Session或Token,拦截未授权访问。 - 访问日志与性能监控:记录每个请求的客户端 IP、目标 URI 以及接口执行耗时。
- 安全防御与数据转换:统一注入跨域响应头(CORS)、过滤 XSS 恶意脚本或对响应体执行 GZIP 压缩。
若将上述公共代码直接编写在每个 Servlet 的处理方法中,会导致严重的职责耦合与代码冗余;一旦公共规则变更,必须逐一修改所有 Servlet 类。
Filter(过滤器)正是 Servlet 规范为解决这一问题提供的容器级组件。它部署在 Web 容器(如 Tomcat)与目标资源(Servlet、JSP 或 HTML/CSS 等静态资源)之间,充当请求与响应双向通道上的拦截关卡,在不侵入业务 Servlet 代码的前提下实现公共逻辑的集中抽离与复用。
双向拦截机制
Filter 并非单向的前置检查器,而是围绕目标资源形成完整的双向环绕拦截模型。当客户端发起 HTTP 请求时,Web 容器不会直接调用目标 Servlet,而是先将请求交由匹配的 Filter 处理。

一次完整的过滤周期包含以下三个阶段:
前置请求预处理
请求进入 Filter 后,首先执行放行语句之前的代码。开发者可在此阶段读取或校验 ServletRequest 中的请求头、参数与会话状态,或者修改请求编码、向请求域挂载公共属性。
过滤链放行与短路中断
前置逻辑执行完毕后,由 Filter 决定当前请求的流向:
放行请求:显式调用
FilterChain的放行方法,将控制权移交至过滤链中的下一个Filter;若当前已是最后一个Filter,则触发目标Servlet或静态资源的执行。短路中断:若前置校验未通过(例如用户未登录或权限不足),
Filter可以直接通过ServletResponse重定向至登录页或写出错误响应报文,不再调用放行方法。此时请求处理流程立即终止,后续Filter与目标Servlet均不会执行。
后置响应处理
当请求被放行且目标 Servlet 执行完毕后,调用栈会沿着原过滤链反向回溯,继续执行 Filter 中放行语句之后的代码。开发者可在此阶段统一追加响应头、统计业务执行耗时,或借助包装器(Wrapper)对响应数据进行二次加工,最终由容器将响应报文写回客户端。
标准开发流程
编写并启用一个标准的 Servlet Filter 通常包含两个核心步骤:实现 Filter 接口编写拦截逻辑,以及声明拦截路径将过滤器注册至 Web 容器。
以下示例通过实现 Filter 接口并配合 @WebFilter 注解,构建一个兼具统一编码设置与接口耗时统计功能的过滤器:
package com.example.filter;
import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
// 1. 声明过滤器拦截路径,匹配应用下所有请求
@WebFilter("/*")
public class AccessLogFilter implements Filter {
// 2. 实现核心拦截方法,封装请求预处理与响应后置逻辑
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
// 3. 前置处理:统一设置请求字符集并记录起始时间戳
request.setCharacterEncoding("UTF-8");
long startTime = System.currentTimeMillis();
// 4. 放行请求:将控制权移交过滤链中的下一个节点或目标 Servlet
chain.doFilter(request, response);
// 5. 后置处理:目标资源执行完毕后,计算并输出接口耗时
HttpServletRequest httpRequest = (HttpServletRequest) request;
long costTime = System.currentTimeMillis() - startTime;
System.out.println(httpRequest.getRequestURI() + " 耗时: " + costTime + " ms");
}
}Filter 与 Servlet 职责边界
尽管 Filter 与 Servlet 均由 Web 容器管理生命周期,且都能访问请求与响应对象,但二者在架构设计上遵循严格的职责分离:
| 对比维度 | Filter(过滤器) | Servlet(服务组件) |
|---|---|---|
| 核心定位 | 横切关注点拦截、请求预处理与响应后置增强 | 具体业务请求分发、核心业务逻辑调用与视图响应生成 |
| 与目标资源关系 | 依附于过滤链,可放行至下游节点或主动中断请求 | 作为请求链路终点,直接消费请求并产出最终业务响应 |
| 匹配粒度 | 通常绑定通配路径(如 /*、/api/*)批量拦截一类资源 | 通常绑定精确路径(如 /order/create)处理单一业务动作 |
| 执行数量 | 单次请求可依次穿过多个匹配的 Filter 节点 | 单次请求在每个派发周期内最终仅由一个目标 Servlet 处理 |
Filter 接口架构
接口继承体系
早期 Servlet 规范中只提供了顶层 Filter 接口,开发者在编写 HTTP 过滤器时不仅需要手动管理配置对象,还必须在每次拦截时将通用的请求与响应对象强制向下转型为 HTTP 协议类型。自 Servlet 4.0(对应 Jakarta Servlet 5.0/6.0)起,规范引入了与 Servlet 体系(Servlet -> GenericServlet -> HttpServlet)完全对称的三层过滤器继承架构。

Filter
jakarta.servlet.Filter 是所有过滤器的顶层根接口,定义了过滤器在 Web 容器中的生命周期契约与核心拦截入口。
- 协议无关性:该接口的方法签名接收
ServletRequest与ServletResponse参数,设计上不局限于 HTTP 协议,可用于拦截任何基于请求-响应模型的通信协议。 - 默认生命周期实现:在引入 Java 8 默认方法(
default)后,Filter接口已为初始化与销毁方法提供了空的默认实现。若自定义过滤器无需读取初始配置或释放外部资源,仅需实现核心的过滤方法即可。
GenericFilter
jakarta.servlet.GenericFilter 是直接实现 Filter 与 FilterConfig 接口的协议无关抽象基类,其核心职责是简化初始化配置的保存与读取:
- 托管配置引用:容器启动并调用过滤器的带参初始化方法时,
GenericFilter会自动将传入的FilterConfig实例保存在内部成员变量中,防止开发者因重写带参初始化方法而遗忘保存配置对象。 - 提供无参初始化钩子:
GenericFilter额外提供了一个无参的受保护初始化方法。子类只需重写该无参方法即可编写自定义初始化逻辑,并可直接通过this调用FilterConfig定义的配置读取方法。
HttpFilter
jakarta.servlet.http.HttpFilter 继承自 GenericFilter,是专门针对 HTTP 协议定制的抽象基类,也是日常 Web 开发中推荐优先继承的基类:
- 双重载派发机制:
HttpFilter内部实现了顶层Filter接口的通用拦截方法。当请求到达时,该方法会先校验传入的ServletRequest与ServletResponse是否属于HttpServletRequest与HttpServletResponse实例;若校验通过,则自动完成强制类型转换,并委派给重载的 HTTP 专属受保护拦截方法执行;若非 HTTP 协议请求,则直接抛出ServletException。 - 消除样板转型代码:子类继承
HttpFilter后,只需重写接收HttpServletRequest与HttpServletResponse的受保护方法,即可直接操作请求头、Cookie、Session 及 HTTP 状态码。
以下示例展示了继承 HttpFilter 实现请求头认证校验的标准写法:
package com.example.filter;
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. 继承 HttpFilter 抽象基类,省去请求与响应对象的强制类型转换
@WebFilter("/api/*")
public class TokenAuthFilter extends HttpFilter {
// 2. 重写接收 HTTP 协议参数的受保护方法,直接调用 HTTP 专属操作
@Override
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
// 3. 直接读取 HTTP 请求头中的认证凭证
String token = request.getHeader("Authorization");
// 4. 凭证缺失时直接返回未授权状态码并中断链路
if (token == null || token.isBlank()) {
response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Missing Authorization Token");
return;
}
// 5. 校验通过后放行至下游节点
chain.doFilter(request, response);
}
}容器生命周期
Filter 实例的创建、初始化、调用与销毁完全由 Web 容器(如 Tomcat)托管,开发者严禁在业务代码中手动通过 new 关键字调用过滤器生命周期方法。

启动预加载
与 Servlet 默认采用“首次请求到达时延迟实例化”的策略不同,Web 容器会在应用启动阶段(ServletContext 初始化完毕后、接收任何客户端请求之前)立即实例化所有已注册的 Filter 并执行其初始化方法:
容器通过反射调用
Filter实现类的无参构造方法完成对象实例化(因此自定义Filter必须保留公开的无参构造器)。容器为每个过滤器封装对应的
FilterConfig配置对象,并调用初始化方法(仅执行一次)。若初始化方法在执行期间抛出
ServletException或未捕获的运行时异常,容器会将该过滤器标记为不可用;在 Tomcat 默认配置下,过滤器启动失败会直接导致整个 Web 应用上下文(StandardContext)启动失败,以防止安全拦截规则失效后暴露后端资源。
并发拦截执行
应用启动就绪后,每当客户端请求匹配当前过滤器的拦截规则,容器工作线程便会调用过滤器的拦截方法。在整个应用运行期间,该方法会被并发调用无数次。
容器销毁卸载
当 Web 应用被卸载、重新部署或容器正常关闭时,容器会在回收 Filter 实例前调用其销毁方法(仅执行一次)。在销毁方法执行期间,容器保证所有正在穿过该过滤器的请求线程均已执行完毕或已超时退出,开发者可在此处安全释放线程池、本地缓存或外部连接。
以下表格对比了 Filter 与 Servlet 在容器生命周期管理上的核心差异:
| 生命周期维度 | Filter(过滤器) | Servlet(服务组件) |
|---|---|---|
| 默认实例化时机 | Web 应用启动时立即预加载(早于所有 Servlet) | 默认首次请求到达时延迟加载(需配置 load-on-startup 才预加载) |
| 初始化配置载体 | FilterConfig | ServletConfig |
| 初始化异常后果 | 直接阻断当前 Web 应用上下文启动 | 仅当前 Servlet 不可用(预加载异常取决于容器策略) |
| 销毁触发顺序 | 应用停止时,在所有 Servlet 销毁之后再销毁 Filter | 应用停止时,先于 Filter 执行销毁 |
单例并发与线程安全
在同一个 ServletContext(Web 应用上下文)中,针对每一项过滤器注册声明,Web 容器默认只创建一个 Filter 实例(单实例多线程模型)。
当高并发请求同时命中同一个 Filter 时,容器线程池中的多个工作线程会同时进入该唯一实例的拦截方法:
- 成员变量并发陷阱:若在
Filter类中定义了可读写的实例成员变量(例如用于记录请求开始时间、当前登录用户或请求流),多个线程并发读写该变量会导致严重的竞态条件(Race Condition)与数据串改。 - 栈封闭与请求域隔离:与单次请求相关的临时状态必须声明为拦截方法内部的局部变量(存储在线程私有的 JVM 虚拟机栈帧中);若状态需要跨多个
Filter或向目标Servlet传递,应将其绑定至当前请求私有的ServletRequest属性域(Attribute)或ThreadLocal上下文中。
以下示例演示了 Filter 单例模型下的线程安全边界与状态传递规范:
package com.example.filter;
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. 容器内仅维护单个 TraceFilter 实例,所有请求线程共享该对象
@WebFilter("/*")
public class TraceFilter extends HttpFilter {
// 2. 错误示范:可变的实例成员变量会被并发线程互相覆盖,引发线程安全问题
// private long unsafeStartTime;
// 3. 正确示范:只读常量或无状态线程安全组件可声明为成员变量
private static final String ATTR_START_TIME = "REQUEST_START_TIME";
// 4. 多线程并发进入 doFilter,每个线程拥有独立的虚拟机栈帧
@Override
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
// 5. 使用方法局部变量保存当前请求状态,栈封闭保证绝对线程安全
long safeStartTime = System.currentTimeMillis();
// 6. 需跨组件传递状态时,绑定至当前线程私有的 request 属性域
request.setAttribute(ATTR_START_TIME, safeStartTime);
// 7. 放行请求至下游链路
chain.doFilter(request, response);
}
}API: Filter
生命周期管理
voidinit():(FilterConfig filterConfig),过滤器初始化。由 Web 容器在实例化过滤器后调用一次,用于读取FilterConfig中的初始化参数并完成前置资源的加载准备,容器确保在调用该方法成功后再执行请求拦截。voiddestroy():(),过滤器销毁。由 Web 容器在卸载当前过滤器或关闭应用前调用一次,用于释放该过滤器持有的连接池、文件句柄或后台线程等底层资源。
注意事项:
- 自 Servlet 4.0 规范起,
init()与destroy()均被声明为包含空实现的default默认方法;实现类若无需加载初始化配置或释放底层资源,可直接省略这两个方法的重写。- Web 容器在应用启动或首次拦截时仅创建一个
Filter单例,且在init()执行期间若抛出ServletException或超时未返回,容器将终止该过滤器的上线并禁止其投入请求服务。
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletContext;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import java.util.Collections;
import java.util.Enumeration;
// 1. 实现 Filter 接口,演示过滤器初始化参数读取与销毁资源释放流程
public class FilterLifecycleDemo implements Filter {
private String encoding;
// 2. 重写 init 方法,在容器启动过滤器时提取 FilterConfig 中的字符集配置
@Override
public void init(FilterConfig filterConfig) throws ServletException {
this.encoding = filterConfig.getInitParameter("encoding");
System.out.println("[init] 过滤器初始化完成,加载编码参数: " + this.encoding);
}
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
System.out.println("[doFilter] 当前使用编码: " + this.encoding);
}
// 3. 重写 destroy 方法,在容器卸载过滤器前清空配置并释放持有的资源
@Override
public void destroy() {
this.encoding = null;
System.out.println("[destroy] 过滤器已销毁,底层资源释放完毕");
}
public static void main(String[] args) throws ServletException {
// 4. 实例化过滤器对象并模拟 Web 容器传入 FilterConfig 完成初始化与销毁调用
Filter filter = new FilterLifecycleDemo();
FilterConfig mockConfig = new FilterConfig() {
@Override
public String getFilterName() { return "LifecycleFilter"; }
@Override
public ServletContext getServletContext() { return null; }
@Override
public String getInitParameter(String name) { return "UTF-8"; }
@Override
public Enumeration<String> getInitParameterNames() { return Collections.emptyEnumeration(); }
};
filter.init(mockConfig);
filter.doFilter(null, null, null);
filter.destroy();
}
}请求过滤处理
voiddoFilter():(ServletRequest request, ServletResponse response, FilterChain chain),请求拦截处理。当客户端请求匹配当前过滤器的映射路径时由容器调用,可执行前置校验、请求响应包装、通过FilterChain.doFilter()放行至下一节点以及响应返回后的后置处理。
注意事项:
- 方法内部必须显式调用
chain.doFilter(request, response)才会将请求继续传递至过滤链的下一个过滤器或目标 Servlet;若未调用该方法,请求链路将在此处直接短路返回。Filter实例在容器中以单例多线程模式运行,doFilter()会被多个客户端请求线程并发调用,严禁在过滤器成员变量中保存与单次请求绑定的可变状态,以免引发线程安全问题。chain.doFilter()调用之前的逻辑在进入目标资源前执行(前置增强),调用之后的逻辑在目标资源执行完毕、响应流返回客户端前执行(后置增强)。
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import java.io.IOException;
// 1. 实现 Filter 接口,演示请求前置校验、链路放行与后置耗时统计
public class FilterInterceptDemo implements Filter {
private boolean allowAccess = true;
// 2. 重写 doFilter 方法,根据准入状态决定短路拦截或放行至下游过滤链
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
long startTime = System.nanoTime();
System.out.println("[前置处理] 接收到客户端请求,开始执行安全检查");
if (!this.allowAccess) {
System.out.println("[拦截短路] 权限校验未通过,拒绝放行");
return;
}
// 3. 调用 FilterChain.doFilter 将请求向下游目标资源传递
chain.doFilter(request, response);
long costMicros = (System.nanoTime() - startTime) / 1000;
System.out.println("[后置处理] 目标资源响应完毕,本次请求耗时(微秒): " + costMicros);
}
public static void main(String[] args) throws IOException, ServletException {
// 4. 创建过滤器与模拟过滤链,依次测试放行链路与短路拦截效果
FilterInterceptDemo filter = new FilterInterceptDemo();
FilterChain mockChain = (req, res) -> System.out.println(" -> [目标Servlet] 正在处理核心业务逻辑");
System.out.println("=== 场景 A:校验通过并放行 ===");
filter.doFilter(null, null, mockChain);
System.out.println("\n=== 场景 B:校验失败并短路 ===");
filter.allowAccess = false;
filter.doFilter(null, null, mockChain);
}
}API: HttpFilter
构造方法
HttpFilterHttpFilter():(),默认无参构造。由子类构造器隐式或显式调用的空实现构造方法,用于遵循 JavaBean 规范供 Web 容器通过反射机制完成过滤器实例化。
注意事项:
HttpFilter是自 Servlet 4.0 引入的抽象基类,无法直接通过new HttpFilter()实例化,必须由自定义过滤器子类继承使用。- 容器在调用构造方法创建
HttpFilter子类实例时,底层的FilterConfig尚未完成注入,切勿在构造方法内调用getInitParameter()或getServletContext(),相关初始化操作应置于重写的无参init()方法中。
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpFilter;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
// 1. 定义继承自 HttpFilter 的自定义过滤器子类,演示无参构造器的初始化调用链
public class HttpFilterConstructorDemo extends HttpFilter {
// 2. 显式声明子类无参构造器,内部默认通过 super() 调用父类 HttpFilter 无参构造器
public HttpFilterConstructorDemo() {
super();
System.out.println("[构造方法] HttpFilter 子类实例已通过无参构造器创建");
}
@Override
protected void doFilter(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
throws IOException, ServletException {
chain.doFilter(req, res);
}
public static void main(String[] args) {
// 3. 模拟 Web 容器通过无参构造器实例化 HttpFilter 子类对象
HttpFilter filter = new HttpFilterConstructorDemo();
System.out.println("当前过滤器运行时类型: " + filter.getClass().getSimpleName());
}
}请求过滤处理
- doFilter():HTTP 请求过滤派发。拦截客户端请求并将通用请求响应对象转换为 HTTP 协议专属的
HttpServletRequest、HttpServletResponse对象后执行过滤逻辑。void:(ServletRequest req, ServletResponse res, FilterChain chain),通用请求类型转换派发。实现自Filter接口的入口方法,负责校验并将通用ServletRequest、ServletResponse强制转换为HttpServletRequest、HttpServletResponse,随后委派给同名的protected重载方法执行;若传入的请求或响应不属于 HTTP 协议类型,则直接抛出ServletException。protected void:(HttpServletRequest req, HttpServletResponse res, FilterChain chain),HTTP 专属请求拦截处理。供自定义子类重写的核心过滤方法,默认实现仅调用chain.doFilter(req, res)将请求直接放行至过滤链下一节点;子类重写该方法即可直接调用 HTTP 专属 API(如读取 Header、Cookie、Session 或设置状态码),无需手动执行向下转型。
注意事项:
- 自定义子类继承
HttpFilter时,应重写受保护的protected void doFilter(HttpServletRequest req, HttpServletResponse res, FilterChain chain),切勿误重写公开的public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain),否则会覆盖基类内置的协议类型校验与自动强转派发逻辑。protected重载分支的默认实现内部已调用chain.doFilter(req, res);子类重写该方法并完成前置拦截逻辑后,既可直接调用chain.doFilter(req, res)放行,也可通过super.doFilter(req, res, chain)委托父类完成放行。
```java {11,14,19,38} /class HttpFilterDispatchDemo/ /void doFilter/ /new HttpFilterDispatchDemo/ /.doFilter/
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpFilter;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.lang.reflect.Proxy;
// 1. 继承 HttpFilter 抽象类,演示 HTTP 协议自动转型派发与专属方法拦截
public class HttpFilterDispatchDemo extends HttpFilter {
// 2. 重写受保护的 doFilter 方法,直接使用 HttpServletRequest 获取请求方式与 URI
@Override
protected void doFilter(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
throws IOException, ServletException {
System.out.println("[HTTP过滤] 拦截到 " + req.getMethod() + " 请求,路径: " + req.getRequestURI());
// 3. 调用父类或过滤链的 doFilter 方法,将 HTTP 请求放行至下游节点
super.doFilter(req, res, chain);
}
public static void main(String[] args) throws IOException, ServletException {
HttpFilter filter = new HttpFilterDispatchDemo();
FilterChain chain = (req, res) -> System.out.println(" -> [目标Servlet] 业务处理完成");
HttpServletRequest httpReq = (HttpServletRequest) Proxy.newProxyInstance(
HttpServletRequest.class.getClassLoader(),
new Class<?>[]{HttpServletRequest.class},
(proxy, method, methodArgs) -> "getMethod".equals(method.getName()) ? "POST" : "/api/pay"
);
HttpServletResponse httpRes = (HttpServletResponse) Proxy.newProxyInstance(
HttpServletResponse.class.getClassLoader(),
new Class<?>[]{HttpServletResponse.class},
(proxy, method, methodArgs) -> null
);
// 4. 调用公开的通用 doFilter 入口,触发内部 HTTP 转型并委派给受保护的 doFilter 方法
ServletRequest rawReq = httpReq;
ServletResponse rawRes = httpRes;
filter.doFilter(rawReq, rawRes, chain);
}
}
```
继承: GenericFilter
getFilterConfig, getFilterName, getInitParameter, getInitParameterNames, getServletContext, init, init
继承: Filter
destroy
Filter 注册配置
容器注册方式
编写完成的 Filter 类本身只是一个普通的 Java 类,必须通过显式注册将其纳入 Web 容器(如 Tomcat)的管理体系,并绑定对应的拦截规则后才能生效。在 Tomcat 底层,无论采用何种注册手段,容器最终都会将过滤器的定义解析为 FilterDef(封装过滤器名称、实现类或实例、初始化参数),并将映射规则解析为 FilterMap(封装关联的过滤器名称、URL 模式或目标 Servlet 名称),统一挂载至 StandardContext 容器上下文中。

Servlet 规范共提供了三种标准的过滤器注册方式,分别适用于不同的工程架构场景。
web.xml
在传统的 WEB-INF/web.xml 部署描述符中,通过 <filter> 与 <filter-mapping> 两个核心标签完成声明式注册,二者通过相同的 <filter-name> 建立关联:
<!-- 1. 注册过滤器元数据并配置初始化参数 -->
<filter>
<filter-name>encodingFilter</filter-name>
<filter-class>com.example.filter.EncodingFilter</filter-class>
<init-param>
<param-name>encoding</param-name>
<param-value>UTF-8</param-value>
</init-param>
</filter>
<!-- 2. 绑定过滤器的 URL 拦截路径规则 -->
<filter-mapping>
<filter-name>encodingFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>- 集中式编排优势:
web.xml将所有过滤器的拦截规则集中在一处管理,无需修改并重新编译 Java 源码即可调整拦截范围与参数;同时,<filter-mapping>在 XML 文件中的书写先后顺序直接决定了过滤链的执行顺序。 - 多路径映射支持:同一个
<filter-mapping>标签内可以包含多个<url-pattern>或<servlet-name>子标签(Servlet 2.5+),无需重复声明多个<filter-mapping>块。
@WebFilter
自 Servlet 3.0 起,规范引入了 @ jakarta.servlet.annotation.WebFilter 注解,允许开发者直接在过滤器类定义上方完成声明式配置,容器在启动阶段会通过字节码扫描机制自动发现并完成注册:
package com.example.filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.annotation.WebInitParam;
import jakarta.servlet.http.HttpFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
// 1. 通过注解声明过滤器名称、多路径拦截规则与初始化参数数组
@WebFilter(
filterName = "encodingFilter",
urlPatterns = {"/api/*", "/admin/*"},
initParams = {
@WebInitParam(name = "encoding", value = "UTF-8"),
@WebInitParam(name = "forceEncoding", value = "true")
}
)
public class EncodingFilter extends HttpFilter {
// 2. 重写 HTTP 过滤方法,读取初始化参数并设置请求编码
@Override
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
String encoding = this.getInitParameter("encoding");
request.setCharacterEncoding(encoding);
chain.doFilter(request, response);
}
}- 属性等价缩写:注解中的
value属性与urlPatterns属性互为别名,用于指定拦截路径数组;但规范强制要求二者不能同时显式赋值(即使赋相同的值,容器在启动解析时也会直接抛出IllegalArgumentException)。仅声明拦截路径且不配置其他属性时,可简写为@WebFilter("/*")。 - 排序能力缺失:
@WebFilter注解本身没有提供类似order或priority的排序属性,存在多个注解过滤器时无法通过注解控制拦截先后顺序。
FilterRegistration
当过滤器的创建依赖外部运行环境、第三方依赖注入容器(如 Spring IoC)或需要根据配置文件动态决定是否启用时,静态的 XML 与注解均无法满足需求。Servlet 3.0 提供了编程式动态注册接口 FilterRegistration.Dynamic。
动态注册必须在 Web 容器启动阶段、且 ServletContext 尚未完成初始化之前 执行(通常在 ServletContextListener 的启动回调或 ServletContainerInitializer 的引导回调中调用);若在应用运行期的普通请求线程中调用动态注册方法,容器会直接抛出 IllegalStateException:
package com.example.listener;
import com.example.filter.AccessLogFilter;
import jakarta.servlet.DispatcherType;
import jakarta.servlet.FilterRegistration;
import jakarta.servlet.ServletContext;
import jakarta.servlet.ServletContextEvent;
import jakarta.servlet.ServletContextListener;
import jakarta.servlet.annotation.WebListener;
import java.util.EnumSet;
// 1. 监听 Web 应用上下文启动事件,在容器接收请求前完成动态注册
@WebListener
public class DynamicFilterRegistrar implements ServletContextListener {
// 2. 在上下文初始化阶段获取 ServletContext 并动态挂载过滤器
@Override
public void contextInitialized(ServletContextEvent sce) {
ServletContext context = sce.getServletContext();
// 3. 向容器传入自定义创建的 Filter 实例,返回动态注册配置句柄
FilterRegistration.Dynamic registration =
context.addFilter("accessLogFilter", new AccessLogFilter());
// 4. 编程式设置初始化参数、派发类型、排队位置与 URL 映射路径
registration.setInitParameter("env", "production");
registration.addMappingForUrlPatterns(
EnumSet.of(DispatcherType.REQUEST), true, "/api/*");
}
}- 外部实例注入:不同于
web.xml和@WebFilter只能由容器通过无参构造器反射创建实例,动态注册支持直接传入外部预先构造好的Filter对象引用,从而允许过滤器内部通过有参构造器注入业务组件。 - 编程式顺序编排:在调用映射绑定方法时,可通过布尔参数
isMatchAfter精确指定当前映射规则是追加在web.xml已声明映射规则的末尾(true)还是插入到最前(false)。
混合注册合并与覆盖规则
在实际项目中,上述三种注册方式可能会同时存在。Web 容器在启动合并配置元数据时遵循以下优先级规则:
全局注解开关:若
web.xml根标签<web-app>显式设置了metadata-complete="true",容器将完全忽略类路径下所有的@WebFilter和@WebListener注解,仅加载web.xml及编程式动态注册的组件。同名过滤器覆盖:若
@WebFilter声明的filterName与web.xml中的<filter-name>完全同名,容器会将二者视为同一个过滤器注册项。此时web.xml具有更高优先级:若web.xml为该过滤器配置了<filter-mapping>,则@WebFilter中的urlPatterns会被完全忽略,以 XML 中的映射为准(开发者常利用这一机制在不删除@WebFilter的情况下通过web.xml接管过滤器的执行顺序)。
| 对比维度 | web.xml | @WebFilter | FilterRegistration |
|---|---|---|---|
| 配置载体 | XML 外部部署描述符 | Java 类级别源码注解 | 启动期 Java 编程式代码 |
| 实例创建方 | 容器反射调用无参构造器 | 容器反射调用无参构造器 | 容器反射或开发者手动传入实例 |
| 顺序控制能力 | 强(严格按标签声明顺序) | 弱(依赖类名排序,不可控) | 强(支持按调用顺序及前后插队控制) |
| 动态条件开关 | 不支持(静态写死) | 不支持(编译期固定) | 支持(可根据运行环境分支动态注册) |
拦截映射规则
容器在判断某个请求是否需要经过特定 Filter 时,支持基于 URL 路径模式 和 目标组件名称 两种映射维度。
路径匹配模式
URL 路径模式(url-pattern / urlPatterns)遵循 Servlet 规范定义的四种标准语法格式:
精确路径匹配:以
/开头且不含通配符的完整路径,如/user/login、/order/pay。仅当请求的上下文相对路径与配置字符串完全相等时才触发拦截。路径前缀匹配:以
/开头并以/*结尾,如/api/*、/admin/v1/*以及覆盖全站的/*。只要请求路径命中指定目录前缀即触发拦截。扩展名匹配:以
*.开头后接文件后缀名,如*.jsp、*.do、*.html。非法混合语法陷阱:规范严禁将“路径前缀匹配”与“扩展名匹配”混合书写。例如配置为
/api/*.do或/*.jsp均属于非法格式,容器在启动解析阶段会直接抛出IllegalArgumentException: Invalid <url-pattern>导致应用启动失败。
全路径与根路径边界
在配置全局拦截时,开发者极易混淆 /* 与 / 两种配置在 Filter 与 Servlet 中的行为差异:
/*(全路径通配):屬於路径前缀匹配的最高层级,能够拦截进入当前 Web 应用的所有请求,涵盖动态Servlet接口、JSP 页面以及 HTML/JS/CSS 等静态资源。编写全局过滤器(如字符集编码、全局访问日志)时,必须使用/*。/(缺省 Servlet 映射 / 根路径):在Servlet映射中,/代表容器的缺省 Servlet(DefaultServlet),用于兜底处理所有未被其他Servlet匹配的请求(如静态资源)。但在Filter映射中,并不存在“缺省过滤器”的概念;若将Filter的路径配置为/,它仅会拦截直接访问应用根目录(如http://localhost:8080/app/)或最终回退给DefaultServlet的请求,而所有命中具体业务Servlet(如/user/list)的请求都会绕过该过滤器。
组件名称映射
除了匹配 URL 字符串,Filter 还可以通过 servlet-name(XML)或 servletNames(注解)直接绑定到一个或多个已注册的 Servlet 逻辑名称上:
- 解耦路径变更:只要请求最终路由到指定名称的目标
Servlet(无论该Servlet绑定了多少个 URL 路径,或是后续修改了 URL 路径),关联的Filter都会自动生效。 - 组合映射顺序:当同一个应用内既有按 URL 路径匹配的
Filter,又有按Servlet名称匹配的Filter时,容器在组装过滤链时遵循固定铁律:所有按 URL 路径匹配的过滤器,永远排在按Servlet名称匹配的过滤器之前执行。
FilterConfig
jakarta.servlet.FilterConfig 是容器在启动初始化阶段传递给过滤器的专属配置载体,每个过滤器注册项对应一个独立的 FilterConfig 实例。
启动期配置解析
容器在调用过滤器的带参初始化方法时会将 FilterConfig 传入。由于拦截方法本身并不接收 FilterConfig 参数,若按原始方式直接实现顶层 Filter 接口,开发者应在初始化阶段读取并解析配置参数,将其转换为只读的实例成员变量供后续请求并发读取:
package com.example.filter;
import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.FilterConfig;
import jakarta.servlet.ServletContext;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import java.io.IOException;
import java.util.Set;
// 1. 实现顶层 Filter 接口,在启动阶段解析并缓存初始化配置
public class IpBlacklistFilter implements Filter {
// 2. 声明只读配置属性,在 init 阶段完成一次性赋值后供并发线程安全读取
private Set<String> blockedIps;
private ServletContext servletContext;
// 3. 容器启动时调用一次,通过 FilterConfig 提取参数并初始化不可变集合
@Override
public void init(FilterConfig filterConfig) throws ServletException {
this.servletContext = filterConfig.getServletContext();
String rawIps = filterConfig.getInitParameter("blockedIps");
this.blockedIps = (rawIps != null) ? Set.of(rawIps.split(",")) : Set.of();
}
// 4. 拦截请求并比对客户端 IP 是否命中黑名单集合
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
if (blockedIps.contains(request.getRemoteAddr())) {
servletContext.log("Blocked access from IP: " + request.getRemoteAddr());
return;
}
chain.doFilter(request, response);
}
}基类配置委托机制
在 Filter 接口体系中,GenericFilter(及其子类 HttpFilter)本身直接实现了 FilterConfig 接口。其底层采用了委托模式(Delegation Pattern):
GenericFilter内部持有一个private volatile FilterConfig filterConfig成员变量。当容器调用
init(FilterConfig config)时,GenericFilter会将传入的config引用赋值给内部成员变量,随后调用自身的无参钩子方法init()。当子类在
doFilter或无参init()中直接调用this.getInitParameter(name)或this.getServletContext()时,GenericFilter内部会自动将调用转发给所持有的filterConfig实例。重写陷阱:继承
GenericFilter或HttpFilter后,若需要编写自定义初始化逻辑,应重写无参的public void init()方法;若不慎重写了带参的init(FilterConfig config)且未在第一行调用super.init(config),会导致父类内部的filterConfig引用保持为null,后续调用任何配置读取方法均会触发NullPointerException。
API: FilterConfig
容器环境获取
StringgetFilterName():(),过滤器名称获取。返回当前过滤器在部署描述符(web.xml)或@WebFilter注解中定义的注册名称;若未显式指定名称,部分容器默认返回过滤器实现类的全限定类名。ServletContextgetServletContext():(),应用上下文获取。返回当前过滤器所属 Web 应用的全局ServletContext对象引用,用于读取全局上下文参数、访问应用域共享属性、转换服务器真实文件路径或记录应用日志。
注意事项:
FilterConfig实例由 Web 容器在初始化过滤器时创建,并仅作为方法参数传入Filter.init(FilterConfig);若自定义的Filter实现类需要在doFilter()阶段使用FilterConfig或ServletContext,必须在init()方法中将其保存至类的成员变量(或直接继承已封装该逻辑的GenericFilter、HttpFilter)。- 通过
@WebFilter注解声明过滤器且未显式指定filterName属性时,不同 Servlet 容器对getFilterName()的默认命名策略可能存在差异(例如 Tomcat 默认以过滤器类的全限定类名作为注册名)。
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletContext;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import java.lang.reflect.Proxy;
import java.util.Collections;
import java.util.Enumeration;
// 1. 实现 Filter 接口并在初始化阶段通过 FilterConfig 提取容器环境元数据
public class FilterConfigEnvDemo implements Filter {
private String filterName;
private ServletContext servletContext;
// 2. 调用 getFilterName 与 getServletContext 获取过滤器名称及全局应用上下文
@Override
public void init(FilterConfig filterConfig) {
this.filterName = filterConfig.getFilterName();
this.servletContext = filterConfig.getServletContext();
System.out.println("过滤器注册名称: " + this.filterName);
System.out.println("所属应用上下文路径: " + this.servletContext.getContextPath());
}
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
}
public static void main(String[] args) {
// 3. 构造模拟的 ServletContext 与 FilterConfig 实例并执行初始化验证
ServletContext mockContext = (ServletContext) Proxy.newProxyInstance(
ServletContext.class.getClassLoader(),
new Class<?>[]{ServletContext.class},
(proxy, method, methodArgs) -> "/mall-web"
);
FilterConfig config = new FilterConfig() {
@Override
public String getFilterName() { return "AuthSecurityFilter"; }
@Override
public ServletContext getServletContext() { return mockContext; }
@Override
public String getInitParameter(String name) { return null; }
@Override
public Enumeration<String> getInitParameterNames() { return Collections.emptyEnumeration(); }
};
FilterConfigEnvDemo filter = new FilterConfigEnvDemo();
filter.init(config);
}
}初始化参数读取
StringgetInitParameter():(String name),指定初始化参数读取。根据参数名返回当前过滤器配置的String类型初始化参数值;若指定的参数名不存在,则返回null。Enumeration<String>getInitParameterNames():(),初始化参数名枚举。以Enumeration<String>形式返回当前过滤器配置的所有初始化参数名称集合;若该过滤器未配置任何初始化参数,则返回一个空的Enumeration对象而非null。
注意事项:
getInitParameter()仅能读取当前过滤器专属的局部初始化参数(即web.xml中当前filter节点下的init-param或@WebFilter的initParams属性),无法直接读取全局context-param参数;若需读取全局配置,应通过getServletContext().getInitParameter(name)获取。- 初始化参数的名称严格区分大小写,且返回值固定为
String类型;若配置项代表数值阈值、布尔开关或多路径列表,需由开发者自行处理空值判断、字符串拆分与类型转换。
import javax.servlet.FilterConfig;
import javax.servlet.ServletContext;
import java.util.Collections;
import java.util.Enumeration;
import java.util.LinkedHashMap;
import java.util.Map;
// 1. 定义配置解析演示类,演示 FilterConfig 初始化参数的按名读取与枚举遍历
public class FilterConfigParamDemo {
public static void parseConfig(FilterConfig filterConfig) {
// 2. 调用 getInitParameter 按指定参数名精准读取单个初始化参数值
String encoding = filterConfig.getInitParameter("encoding");
System.out.println("精准读取 [encoding] 参数: " + encoding);
// 3. 调用 getInitParameterNames 获取全部参数名枚举并逐一遍历输出
System.out.println("--- 遍历全部初始化参数 ---");
Enumeration<String> paramNames = filterConfig.getInitParameterNames();
while (paramNames.hasMoreElements()) {
String name = paramNames.nextElement();
String value = filterConfig.getInitParameter(name);
System.out.println(name + " = " + value);
}
}
public static void main(String[] args) {
Map<String, String> initParams = new LinkedHashMap<>();
initParams.put("encoding", "UTF-8");
initParams.put("excludePaths", "/login,/static");
initParams.put("enableLog", "true");
// 4. 构建基于 Map 存储的 FilterConfig 实现并调用参数解析逻辑
FilterConfig config = new FilterConfig() {
@Override
public String getFilterName() { return "EncodingAndAuthFilter"; }
@Override
public ServletContext getServletContext() { return null; }
@Override
public String getInitParameter(String name) { return initParams.get(name); }
@Override
public Enumeration<String> getInitParameterNames() {
return Collections.enumeration(initParams.keySet());
}
};
parseConfig(config);
}
}API: FilterRegistration
路径映射配置
voidaddMappingForUrlPatterns():(EnumSet<DispatcherType> dispatcherTypes, boolean isMatchAfter, String... urlPatterns),URL 路径映射添加。为当前过滤器添加基于 URL 路径模式的拦截映射规则,可指定拦截的派发类型集合、映射匹配顺序以及一个或多个目标 URL 路径模式。Collection<String>getUrlPatternMappings():(),URL 路径映射获取。返回当前过滤器已注册的所有 URL 路径映射模式集合;若尚未配置任何 URL 映射,则返回一个空的只读集合。
注意事项:
- 若传入的
dispatcherTypes参数为null,容器将默认采用EnumSet.of(DispatcherType.REQUEST),即仅拦截客户端直接发起的原始请求。- 参数
isMatchAfter用于控制动态映射与部署描述符(web.xml)中静态声明映射的相对优先级:设为true时排在已声明映射之后匹配执行,设为false时插入到已声明映射之前优先匹配执行。- 若传入的
urlPatterns为null或空数组,将直接抛出IllegalArgumentException;若当前所属的ServletContext已完成初始化,调用该方法将抛出IllegalStateException。
import javax.servlet.DispatcherType;
import javax.servlet.FilterRegistration;
import java.util.Collection;
import java.util.Collections;
import java.util.EnumSet;
import java.util.LinkedList;
import java.util.Map;
import java.util.Set;
// 1. 实现 FilterRegistration 接口,模拟容器对过滤器 URL 路径映射的动态注册与查询
public class FilterUrlMappingDemo implements FilterRegistration {
private final LinkedList<String> urlMappings = new LinkedList<>();
// 2. 重写 addMappingForUrlPatterns 方法,按 isMatchAfter 顺序插入或追加 URL 模式
@Override
public void addMappingForUrlPatterns(EnumSet<DispatcherType> dispatcherTypes,
boolean isMatchAfter, String... urlPatterns) {
EnumSet<DispatcherType> types = (dispatcherTypes == null)
? EnumSet.of(DispatcherType.REQUEST) : dispatcherTypes;
for (String pattern : urlPatterns) {
if (isMatchAfter) {
this.urlMappings.addLast(pattern);
} else {
this.urlMappings.addFirst(pattern);
}
}
System.out.println("[注册URL映射] 派发类型: " + types + ", 追加末尾: " + isMatchAfter);
}
// 3. 重写 getUrlPatternMappings 方法,返回当前已注册的全部 URL 匹配模式集合
@Override
public Collection<String> getUrlPatternMappings() {
return Collections.unmodifiableCollection(this.urlMappings);
}
@Override
public void addMappingForServletNames(EnumSet<DispatcherType> dispatcherTypes,
boolean isMatchAfter, String... servletNames) {}
@Override
public Collection<String> getServletNameMappings() { return Collections.emptyList(); }
@Override
public String getName() { return "UrlFilter"; }
@Override
public String getClassName() { return FilterUrlMappingDemo.class.getName(); }
@Override
public boolean setInitParameter(String name, String value) { return false; }
@Override
public String getInitParameter(String name) { return null; }
@Override
public Set<String> setInitParameters(Map<String, String> initParameters) { return Collections.emptySet(); }
@Override
public Map<String, String> getInitParameters() { return Collections.emptyMap(); }
public static void main(String[] args) {
// 4. 创建注册器实例,依次追加与前置插入 URL 路径映射并查询最终生效顺序
FilterRegistration registration = new FilterUrlMappingDemo();
registration.addMappingForUrlPatterns(null, true, "/api/*", "/order/*");
registration.addMappingForUrlPatterns(EnumSet.of(DispatcherType.REQUEST, DispatcherType.FORWARD), false, "/auth/*");
Collection<String> patterns = registration.getUrlPatternMappings();
System.out.println("当前生效的 URL 映射列表: " + patterns);
}
}组件映射配置
voidaddMappingForServletNames():(EnumSet<DispatcherType> dispatcherTypes, boolean isMatchAfter, String... servletNames),Servlet 名称映射添加。为当前过滤器添加基于目标 Servlet 名称的拦截映射规则,可指定拦截的派发类型集合、映射匹配顺序以及一个或多个目标 Servlet 注册名称。Collection<String>getServletNameMappings():(),Servlet 名称映射获取。返回当前过滤器已注册的所有目标 Servlet 名称映射集合;若尚未配置任何 Servlet 名称映射,则返回一个空的只读集合。
注意事项:
servletNames参数支持传入通配符"*",用于将当前过滤器绑定至应用内所有静态声明或动态注册的 Servlet 组件。getServletNameMappings()与getUrlPatternMappings()返回的集合均为容器内部状态的只读视图或独立副本,直接修改该返回集合不会影响容器底层的过滤器映射配置。
import javax.servlet.DispatcherType;
import javax.servlet.FilterRegistration;
import java.util.Collection;
import java.util.Collections;
import java.util.EnumSet;
import java.util.LinkedList;
import java.util.Map;
import java.util.Set;
// 1. 实现 FilterRegistration 接口,演示基于目标 Servlet 名称的拦截映射注册与读取
public class FilterServletMappingDemo implements FilterRegistration {
private final LinkedList<String> servletMappings = new LinkedList<>();
// 2. 重写 addMappingForServletNames 方法,按指定优先级注册目标 Servlet 名称
@Override
public void addMappingForServletNames(EnumSet<DispatcherType> dispatcherTypes,
boolean isMatchAfter, String... servletNames) {
for (String name : servletNames) {
if (isMatchAfter) {
this.servletMappings.addLast(name);
} else {
this.servletMappings.addFirst(name);
}
}
System.out.println("[注册组件映射] 绑定目标 Servlet 数量: " + servletNames.length);
}
// 3. 重写 getServletNameMappings 方法,返回当前过滤器绑定的全部 Servlet 名称
@Override
public Collection<String> getServletNameMappings() {
return Collections.unmodifiableCollection(this.servletMappings);
}
@Override
public void addMappingForUrlPatterns(EnumSet<DispatcherType> dispatcherTypes,
boolean isMatchAfter, String... urlPatterns) {}
@Override
public Collection<String> getUrlPatternMappings() { return Collections.emptyList(); }
@Override
public String getName() { return "ServletBoundFilter"; }
@Override
public String getClassName() { return FilterServletMappingDemo.class.getName(); }
@Override
public boolean setInitParameter(String name, String value) { return false; }
@Override
public String getInitParameter(String name) { return null; }
@Override
public Set<String> setInitParameters(Map<String, String> initParameters) { return Collections.emptySet(); }
@Override
public Map<String, String> getInitParameters() { return Collections.emptyMap(); }
public static void main(String[] args) {
// 4. 实例化注册器,绑定多个目标 Servlet 并查询最终生效的组件名称集合
FilterRegistration registration = new FilterServletMappingDemo();
registration.addMappingForServletNames(EnumSet.of(DispatcherType.REQUEST), true, "OrderServlet", "PayServlet");
registration.addMappingForServletNames(EnumSet.of(DispatcherType.FORWARD), false, "DispatcherServlet");
Collection<String> servletNames = registration.getServletNameMappings();
System.out.println("当前绑定的目标 Servlet 列表: " + servletNames);
}
}继承: Registration
getClassName, getInitParameter, getInitParameters, getName, setInitParameter, setInitParameters