filter 由 servlet 容器在启动时扫描注册并按序调用 dofilter()，其生命周期由 init()、dofilter()、destroy() 三方法管控，且 request 流只能读一次，需用 httpservletrequestwrapper 包装实现重放。
Filter 是怎么被容器调用的？
Java Web 中的 Filter 不是靠你手动 new 或调用生效的，而是由 Servlet 容器（如 Tomcat）在启动时扫描、实例化，并按配置顺序插入请求处理链。它本质是一个“拦截器”，但和 Spring 的 HandlerInterceptor 不同——Filter 在 Servlet 生命周期之外，更底层，能拦请求头、请求体、响应体，甚至跳过目标 Servlet。
- 容器启动时读取
web.xml或注解（@WebFilter），注册 Filter 实例到内部过滤器链 - 每次 HTTP 请求进来，容器按声明顺序依次调用
doFilter()；只有显式调用chain.doFilter(request, response)，才会继续向后传递 - Filter 实例是单例的（每个类一个实例），但
doFilter()方法是多线程并发执行的，所以不能在 Filter 内部用非线程安全的成员变量存请求数据
init() / doFilter() / destroy() 什么时候触发？
Filter 的生命周期由容器完全管理，三个方法的触发时机非常明确，但容易误用：
-
init()：容器启动完成、Filter 实例化后立即调用一次，且仅一次。适合做一次性初始化（如加载配置、初始化连接池）。注意：FilterConfig可从中获取init-param，但无法拿到ServletContext的完整引用（需通过config.getServletContext()获取） -
doFilter()：每次匹配请求都会调用，参数是包装过的ServletRequest/ServletResponse（可能是HttpServletRequest/HttpServletResponse，但必须向下转型才可用 HTTP 特有方法） -
destroy()：容器关闭前调用一次，用于释放资源。但不要指望它一定被执行（比如 kill -9 进程就跳过）
为什么 request.getInputStream() 只能读一次？Filter 里怎么安全重放？
这是 Filter 最常踩的坑：HTTP 请求体（如 JSON）默认是流式读取，request.getInputStream() 或 request.getReader() 调用一次后流就关闭了，后续 Servlet 拿不到原始数据。
- 解决方案不是“缓存字节”，而是用装饰器模式包装请求对象，例如继承
HttpServletRequestWrapper - 关键点：在
doFilter()开头就把整个 body 读入内存（IOUtils.toString(request.getInputStream(), "UTF-8")），再构造一个可重复读的HttpServletRequestWrapper子类，重写getInputStream()和getReader()返回新缓存 - ⚠️ 注意：大文件上传场景下别这么干，会 OOM；生产环境建议只对特定路径（如
/api/**）或小 payload（Content-Length ）启用缓存
public class BodyCachingRequestWrapper extends HttpServletRequestWrapper {
private final byte[] cachedBody;
public BodyCachingRequestWrapper(HttpServletRequest request) throws IOException {
super(request);
this.cachedBody = IOUtils.toByteArray(request.getInputStream());
}
@Override
public ServletInputStream getInputStream() throws IOException {
return new CachedServletInputStream(cachedBody);
}
// ... 省略 getReader() 实现
}
@WebFilter 和 web.xml 配置哪个优先？
两者可以共存，但容器加载顺序有明确规定：web.xml 中定义的 Filter 总是先于 @WebFilter 注册。也就是说，如果你在 web.xml 里配了 A、B，在代码里用 @WebFilter 声明了 C，最终执行顺序是 A → B → C（前提是 URL 匹配规则一致）。
立即学习“Java免费学习笔记（深入）”；
-
@WebFilter(urlPatterns = "/api/*")和<url-pattern>/api/*</url-pattern>效果等价，但注解无法设置<dispatcher></dispatcher>类型（如 ERROR、FORWARD），除非用dispatcherTypes属性显式指定 - Tomcat 9+ 默认禁用
web.xml的自动扫描（如果用了metadata-complete="true"），此时@WebFilter是唯一方式 - Spring Boot 项目默认不加载
web.xml，所有 Filter 必须用@Bean方式注册或@WebFilter+@ServletComponentScan
