自定义Filter必须实现doFilter方法，需调用chain.doFilter放行或手动响应阻断；url-pattern仅支持前缀、扩展名和默认匹配；@WebFilter需配合@ServletComponentScan；读取request body需用包装类缓存。
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 不触发。
立即学习“Java免费学习笔记（深入）”；
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
@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<AuthFilter> loggingFilter() {
FilterRegistrationBean<AuthFilter> 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）。
