WebFlux场景下WebFilter与ExchangeFilterFunction的区别及适用场景

这两个组件都是WebFlux生态里的过滤器，但定位和使用场景完全不同，核心差异如下：

一、作用层级与范围 #

• WebFilter：服务端全局过滤器，负责拦截所有进入服务器的HTTP请求——不管是控制器接口、静态资源，还是其他路由规则匹配的请求，只要请求抵达服务器，它就能介入处理。属于WebFlux服务器端的基础组件，相当于响应式环境下的Servlet Filter。
• ExchangeFilterFunction：WebClient专属的客户端过滤器，仅作用于当前WebClient实例发起的请求和收到的响应。它是为WebClient调用外部服务时做拦截处理的，和服务器端的请求链路完全无关。

二、处理的核心对象 #

• WebFilter：操作ServerWebExchange对象，包含服务端的ServerHttpRequest（请求）和ServerHttpResponse（响应）上下文，可修改服务端收到的请求参数、响应头，甚至调整响应体内容。
• ExchangeFilterFunction：操作ClientRequest（客户端发出的请求）和ClientResponse（客户端收到的响应）对象，比如给请求添加认证头、统一解析外部服务的响应结果或处理异常。

三、注册生效方式 #

• WebFilter：只需实现WebFilter接口，将类注册为Spring Bean（比如添加@Component注解），就会自动全局生效，无需额外绑定到特定控制器或路由。
  示例代码：

  @Component
  public class GlobalAuthFilter implements WebFilter {
      @Override
      public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
          // 全局校验请求头中的token
          String token = exchange.getRequest().getHeaders().getFirst("Authorization");
          if (token == null || !tokenValid(token)) {
              exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
              return exchange.getResponse().setComplete();
          }
          return chain.filter(exchange);
      }
  }
  

• ExchangeFilterFunction：必须绑定到WebClient实例上，可通过WebClient.Builder的filter()方法为单个实例添加，也可注册为全局WebClient过滤器（但依然仅作用于WebClient请求）。
  示例代码：

  // 给特定WebClient实例绑定过滤器
  WebClient apiClient = WebClient.builder()
          .baseUrl("https://api.example.com")
          .filter((request, next) -> {
              // 为该实例的所有请求添加认证头
              ClientRequest authRequest = ClientRequest.from(request)
                      .header("Authorization", "Bearer " + getToken())
                      .build();
              return next.exchange(authRequest);
          })
          .build();
  

适用场景 #

WebFilter适合的场景 #

• 服务端全局统一操作：比如全局请求日志记录、全量请求的CORS配置、全局权限校验、统一为响应添加公共头（如X-App-Version）。
• 服务端侧的请求/响应预处理：比如对所有入参做脱敏处理，对所有响应内容进行加密。

ExchangeFilterFunction适合的场景 #

• WebClient客户端的统一处理：比如给所有WebClient请求添加认证信息、记录客户端请求日志、实现请求重试逻辑、统一处理外部服务返回的错误响应。
• 特定业务的WebClient定制：比如某个业务模块调用外部API需要单独添加特定请求头，就给该模块的WebClient实例绑定对应的过滤器。

内容的提问来源于stack exchange，提问作者sunny-java-dev