Java过滤器实现与配置详解

本文深入剖析了Java Web开发中Filter的核心实现要点与常见陷阱：从强制实现doFilter方法并正确调用chain.doFilter放行或手动响应阻断，到url-pattern仅支持前缀（如/api/*）和扩展名（如*.html）匹配、不支持Spring风格的/**通配；详解@WebFilter在Spring Boot中需配合@ServletComponentScan才生效，而更推荐@Bean方式注册以精准控制顺序；特别强调Filter中读取request body易导致流耗尽问题，必须借助HttpServletRequestWrapper或Spring内置的ContentCachingRequestWrapper进行缓存。这些实战细节直击开发者高频踩坑点，是构建健壮、可维护Web过滤逻辑的必备指南。

Filter 接口必须实现 doFilter 方法

Java Servlet 规范中，自定义过滤器必须实现 javax.servlet.Filter 接口，而 doFilter 是唯一强制重写的核心方法。不实现它会导致部署失败，常见错误信息为：java.lang.AbstractMethodError: com.example.MyFilter.doFilter。

注意：不能只写空方法体；必须在适当位置调用 chain.doFilter(request, response)，否则请求会被拦截终止，后续 Filter 和 Servlet 都不会执行。

• 若想放行请求，需在逻辑处理后调用 chain.doFilter(request, response)
• 若想阻断（如鉴权失败），则不调用 chain.doFilter，并手动写响应，例如 response.sendError(HttpServletResponse.SC_UNAUTHORIZED)
• 不要在 doFilter 中直接 return；return 只是退出当前方法，不等于阻断请求流

public class AuthFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        HttpServletRequest req = (HttpServletRequest) request;
        String token = req.getHeader("Authorization");
        if (token == null || !token.startsWith("Bearer ")) {
            HttpServletResponse resp = (HttpServletResponse) response;
            resp.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Missing token");
            return; // 此处 return 是安全的，因为已发响应
        }
        chain.doFilter(request, response); // 放行
    }
}

web.xml 中 filter-mapping 的 url-pattern 匹配规则

url-pattern 决定 Filter 是否生效，不是正则表达式，而是 Servlet 容器定义的三类匹配模式：

• /api/*：匹配所有以 /api/ 开头的路径，如 /api/users、/api/orders/123
• *.html：匹配所有以 .html 结尾的请求，注意开头不能有 /
• /：匹配默认 servlet（静态资源），但不匹配带后缀的请求（如 /index.jsp）
• 精确匹配如 /login 在多数容器中不被支持；只支持前缀或扩展名匹配

常见陷阱：/api/** 是 Spring MVC 的 Ant 风格，在原生 web.xml 中无效，会直接导致 404 或 Filter 不触发。

@WebFilter 注解在 Spring Boot 中可能失效

Spring Boot 默认使用嵌入式 Tomcat，并启用 Servlet 容器自动注册机制。但 @WebFilter 要生效，必须满足两个条件：

• 类上标注 @WebFilter(urlPatterns = "/api/*")
• 启动类或配置类上添加 @ServletComponentScan，否则 Filter 不会被扫描注册
• 如果项目同时用了 Spring Security，它的 FilterChainProxy 会包裹所有请求，自定义 Filter 可能被绕过或顺序错乱

更稳妥的做法是改用 Spring 的 @Bean 方式注册：

@Configuration
public class FilterConfig {
    @Bean
    public FilterRegistrationBean loggingFilter() {
        FilterRegistrationBean registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new AuthFilter());
        registrationBean.addUrlPatterns("/api/*");
        registrationBean.setOrder(1); // 控制执行顺序
        return registrationBean;
    }
}

Filter 中读取 request body 会触发流耗尽问题

HTTP 请求体（如 JSON）在 Servlet 容器中以 InputStream 形式暴露，且只能读一次。在 Filter 中直接调用 request.getInputStream().read(...) 后，后续的 Controller 将读到空内容，抛出类似 Required request body is missing 的异常。

解决办法是使用包装类缓存 body：

• 继承 HttpServletRequestWrapper，重写 getInputStream() 和 getReader()
• 在构造时一次性读取并缓存原始 body 字节
• 后续每次调用都返回新构建的 ByteArrayInputStream
• 注意：该方案增加内存开销，不适用于超大文件上传场景

实际项目中，优先考虑用 Spring 的 ContentCachingRequestWrapper（需确保 DispatcherServlet 配置了 enableLoggingRequestDetails=true）。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Java过滤器实现与配置详解》文章吧，也可关注golang学习网公众号了解相关技术文章。