Java过滤器原理与工作机制解析

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 < 1MB）启用缓存

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 匹配规则一致）。

• @WebFilter(urlPatterns = "/api/*") 和 /api/* 效果等价，但注解无法设置 类型（如 ERROR、FORWARD），除非用 dispatcherTypes 属性显式指定
• Tomcat 9+ 默认禁用 web.xml 的自动扫描（如果用了 metadata-complete="true"），此时 @WebFilter 是唯一方式
• Spring Boot 项目默认不加载 web.xml，所有 Filter 必须用 @Bean 方式注册或 @WebFilter + @ServletComponentScan