我行我素123341. 项目概述：OncePerRequestFilter 在 Spring 中的核心价值
在基于 Spring 框架开发 Web 应用时，过滤器（Filter）是处理 HTTP 请求的重要组件。而 OncePerRequestFilter 作为 Spring 提供的过滤器基类，其独特之处在于确保每个请求只被过滤一次。这个特性看似简单，但在复杂的过滤器链场景中至关重要——它能有效避免因过滤器多次执行导致的重复鉴权、日志重复记录等典型问题。
我曾在电商平台的支付模块中，遇到过因过滤器重复执行导致订单重复提交的严重故障。当时使用的自定义过滤器没有继承 OncePerRequestFilter，在请求转发（forward）时被重复触发。这个教训让我深刻认识到正确选择过滤器基类的重要性。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心原理与工作机制解析
2.1 OncePerRequestFilter 的防重机制实现
OncePerRequestFilter 的核心逻辑体现在其 doFilterInternal 方法中。通过查看源码可以发现，它在处理请求时会先在 request 属性中设置标记：
java复制protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response, FilterChain filterChain)
throws ServletException, IOException {
String alreadyFilteredAttributeName = getAlreadyFilteredAttributeName();
if (request.getAttribute(alreadyFilteredAttributeName) != null) {
filterChain.doFilter(request, response);
} else {
request.setAttribute(alreadyFilteredAttributeName, Boolean.TRUE);
try {
doFilterNestedWrites(request, response, filterChain);
} finally {
request.removeAttribute(alreadyFilteredAttributeName);
}
}
}
这个实现保证了：
- 对同一请求的多次过滤调用会被自动跳过
- 即使发生请求转发（forward）或包含（include）也不会重复执行
- 线程安全地处理并发请求
2.2 与传统 Filter 的对比分析
| 特性 | 普通 Filter | OncePerRequestFilter |
|---|---|---|
| 重复执行防护 | 无 | 有 |
| 请求转发处理 | 可能重复执行 | 确保单次执行 |
| 异常处理 | 需自行实现 | 内置完善异常处理机制 |
| 与 Spring 集成度 | 低 | 高 |
| 适用场景 | 简单过滤逻辑 | 需要精确控制执行次数的场景 |
3. 实战应用场景与最佳实践
3.1 典型应用场景实现
场景一：JWT 鉴权过滤器
java复制public class JwtAuthenticationFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
String token = resolveToken(request);
if (StringUtils.hasText(token) && jwtProvider.validateToken(token)) {
Authentication auth = jwtProvider.getAuthentication(token);
SecurityContextHolder.getContext().setAuthentication(auth);
}
filterChain.doFilter(request, response);
}
private String resolveToken(HttpServletRequest request) {
String bearerToken = request.getHeader("Authorization");
if (StringUtils.hasText(bearerToken) && bearerToken.startsWith("Bearer ")) {
return bearerToken.substring(7);
}
return null;
}
}
场景二：请求日志记录过滤器
java复制public class RequestLoggingFilter extends OncePerRequestFilter {
private static final Logger logger = LoggerFactory.getLogger(RequestLoggingFilter.class);
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
long startTime = System.currentTimeMillis();
try {
filterChain.doFilter(request, response);
} finally {
long duration = System.currentTimeMillis() - startTime;
logger.info("{} {} - {}ms",
request.getMethod(),
request.getRequestURI(),
duration);
}
}
}
3.2 配置与注册方式
Java 配置方式（推荐）
java复制@Configuration
public class FilterConfig {
@Bean
public FilterRegistrationBean<JwtAuthenticationFilter> jwtFilter() {
FilterRegistrationBean<JwtAuthenticationFilter> registration =
new FilterRegistrationBean<>();
registration.setFilter(new JwtAuthenticationFilter());
registration.addUrlPatterns("/api/*");
registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
return registration;
}
}
XML 配置方式
xml复制<filter>
<filter-name>requestLoggingFilter</filter-name>
<filter-class>com.example.RequestLoggingFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>requestLoggingFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
4. 高级特性与性能优化
4.1 异步请求支持
在 Spring 5+ 环境中，OncePerRequestFilter 对异步请求提供了完善支持：
java复制@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response, FilterChain filterChain)
throws ServletException, IOException {
if (AsyncDispatchDetector.isAsyncDispatch(request)) {
filterChain.doFilter(request, response);
} else {
// 正常同步请求处理逻辑
}
}
4.2 过滤器执行顺序控制
过滤器的执行顺序至关重要，特别是在安全相关的场景。Spring 提供了两种控制方式：
-
通过 @Order 注解
java复制@Order(Ordered.HIGHEST_PRECEDENCE) public class SecurityFilter extends OncePerRequestFilter { // ... } -
通过 FilterRegistrationBean 设置
java复制registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 1);
重要提示：安全相关的过滤器（如认证、CSRF防护）应该设置最高优先级，日志记录等辅助性过滤器应该设置较低优先级。
5. 常见问题排查与解决方案
5.1 典型问题速查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 过滤器未执行 | URL 模式配置错误 | 检查 FilterRegistrationBean 的 URL 模式 |
| 重复执行过滤逻辑 | 未继承 OncePerRequestFilter | 改用 OncePerRequestFilter 基类 |
| 获取不到 Spring Bean | 过滤器未由 Spring 管理 | 通过 FilterRegistrationBean 注册 |
| 异步请求处理异常 | 未正确处理异步分发 | 检查 isAsyncDispatch 条件分支 |
| 性能瓶颈 | 过滤器链过长 | 优化过滤器数量和执行顺序 |
5.2 真实案例：跨域过滤器冲突
在一次微服务项目中，我们遇到了跨域过滤器（CorsFilter）与认证过滤器执行顺序冲突的问题。症状是预检请求（OPTIONS）被认证过滤器拦截，导致跨域失败。
解决方案是明确指定过滤器顺序：
java复制@Bean
@Order(Ordered.HIGHEST_PRECEDENCE)
public CorsFilter corsFilter() {
// 跨域配置
}
@Bean
@Order(Ordered.HIGHEST_PRECEDENCE + 1)
public JwtAuthenticationFilter jwtFilter() {
// 认证逻辑
}
6. 性能监控与调优建议
6.1 过滤器性能指标采集
建议在关键过滤器中添加性能监控代码：
java复制protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response, FilterChain filterChain)
throws ServletException, IOException {
long startTime = System.nanoTime();
try {
filterChain.doFilter(request, response);
} finally {
long duration = System.nanoTime() - startTime;
Metrics.recordFilterTime(getClass().getSimpleName(), duration);
}
}
6.2 优化建议
- 避免在过滤器中执行耗时操作：如远程服务调用、复杂计算等
- 合理设置过滤器顺序：高频路径的过滤器尽量靠前
- 使用条件过滤：通过 shouldNotFilter 方法跳过不需要的请求
java复制@Override protected boolean shouldNotFilter(HttpServletRequest request) { return !request.getRequestURI().startsWith("/api/"); }
在实际项目中，我曾通过优化过滤器顺序和添加条件过滤，将平均请求处理时间降低了23%。特别是在高并发场景下，过滤器的性能影响会被放大，这些优化措施效果更为明显。