首页 > 软件编程 > java > OncePerRequestFilter和GenericFilterBean的区别

OncePerRequestFilter和GenericFilterBean的区别及说明

2025-11-06 15:23:34 作者：@zcc@

文章对比了Spring中的GenericFilterBean和OncePerRequestFilter过滤器,指出OncePerRequestFilter提供了更严格的单次执行保证,适用于认证、鉴权等场景

OncePerRequestFilter和GenericFilterBean过滤器的区别

1. 继承关系与核心功能

GenericFilterBean

是 Spring 对 javax.servlet.Filter 接口的实现，提供基础功能（如初始化、销毁方法的默认实现）。
需要开发者手动控制过滤逻辑的执行次数，无法自动确保每个请求只执行一次。
适用于需要灵活控制执行次数的场景（如多次记录日志或动态处理请求）。

OncePerRequestFilter

继承自 GenericFilterBean，核心功能是确保每个 HTTP 请求的过滤逻辑仅执行一次。
内部通过检查请求属性（如 javax.servlet._FILTERED）或 ThreadLocal 来跟踪请求是否已处理过。
适用于需要严格保证单次执行的场景（如认证、鉴权、流量控制等）。

2. 执行逻辑的区别

特性	GenericFilterBean	OncePerRequestFilter
执行次数控制	需手动确保逻辑不重复执行（如请求转发时可能多次触发）。	自动确保每个请求仅执行一次，即使请求被转发或异步处理。
适用场景	需要多次执行的逻辑（如日志记录、动态参数处理）。	需要单次执行的逻辑（如认证、安全校验）。
需重写的方法	doFilter	doFilterInternal
依赖Servlet API	直接使用Servlet原生方法。	内部封装了Servlet逻辑，简化重复执行的检查。

3. 使用场景对比

选择 GenericFilterBean 的场景

需要对请求进行多次拦截（如每个转发点都需要记录日志）。
需要细粒度控制过滤逻辑的执行时机（如根据请求路径动态处理）。
示例：请求头的动态修改、跨域预检（OPTIONS 请求）的多次处理。

选择 OncePerRequestFilter 的场景

需要确保逻辑仅执行一次（如身份验证、设置请求上下文）。
避免资源重复消耗（如数据库连接、令牌生成）。
示例：JWT 认证、Trace ID 的一次设置。

如何使用？

1. GenericFilterBean 的使用

步骤：

继承 GenericFilterBean。
重写 doFilter 方法，实现自定义逻辑。
在 Spring 配置中注册过滤器（如 WebMvcConfigurer 或 @Bean）。

示例代码：记录每次请求的 URL 和耗时（可能多次触发）：

import org.springframework.web.filter.GenericFilterBean;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebFilter;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebFilter("/*") // 配置过滤路径
public class LoggingFilter extends GenericFilterBean {
    @Override
    public void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        //请求响应前
        long startTime = System.currentTimeMillis();
        System.out.println("Request Start: " + request.getRequestURI());
        
        chain.doFilter(request, response); // 继续处理
        //请求响应后
        long endTime = System.currentTimeMillis();
        System.out.println("Request End: " + request.getRequestURI() + ", Time: " + (endTime - startTime) + "ms");
    }
}

2. OncePerRequestFilter 的使用

步骤：

继承 OncePerRequestFilter。
重写 doFilterInternal 方法，实现单次执行的逻辑。
在 Spring 配置中注册过滤器。

示例代码：设置请求头（仅执行一次）：

import org.springframework.web.filter.OncePerRequestFilter;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class HeaderFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        //请求响应前
        long startTime = System.currentTimeMillis();
        System.out.println("Request Start: " + request.getRequestURI());
       
        // 设置请求头，仅执行一次
        response.setHeader("X-Custom-Header", "Spring-Once");
        
        // 必须调用 chain.doFilter()，否则请求无法继续
        chain.doFilter(request, response);
        //请求响应后
        long endTime = System.currentTimeMillis();
        System.out.println("Request End: " + request.getRequestURI() + ", Time: " + (endTime - startTime) + "ms");

    }
}

关键区别总结

场景	GenericFilterBean	OncePerRequestFilter
执行次数	可能多次（需手动控制）	严格一次（自动控制）
适用逻辑	日志记录、动态参数处理	认证、鉴权、Trace ID 设置
核心方法	doFilter	doFilterInternal
是否依赖请求属性	无自动跟踪	通过请求属性或 ThreadLocal 跟踪

举例说明

示例 1：日志记录（GenericFilterBean）

假设需要在每次请求的每个阶段（如转发前、转发后）记录日志，此时使用 GenericFilterBean：

@Component
@Order(2) // 可以定执行顺序，数字越小优先级越高
public class MultiLogFilter extends GenericFilterBean {
    @Override
    public void doFilter(HttpServletRequest req, HttpServletResponse res, FilterChain chain) {
        System.out.println("Log: " + req.getRequestURI() + " - Stage 1");
        chain.doFilter(req, res); // 继续处理，可能触发多次
        System.out.println("Log: " + req.getRequestURI() + " - Stage 2");
    }
}

结果：如果请求被转发多次，日志会重复记录。

示例 2：认证过滤器（OncePerRequestFilter）

确保身份验证逻辑仅执行一次：

@Component
@Order(2) // 可以定执行顺序，数字越小优先级越高
public class AuthFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain) {
        // 检查 Token，仅执行一次
        String token = req.getHeader("Authorization");
        if (token == null) {
            res.sendError(401, "Unauthorized");
            return;
        }
        chain.doFilter(req, res);
    }
}

结果：即使请求被转发，认证逻辑仅执行一次。

总结

选 GenericFilterBean：当需要灵活控制执行次数或允许重复操作时。
选 OncePerRequestFilter：当需要严格保证逻辑仅执行一次时。
关键方法：doFilter（Generic） vs doFilterInternal（OncePer）。
典型场景：日志（Generic） vs 认证（OncePer）。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。