摘要：作为互联网大厂的开发人员，在搭建项目架构时，Spring Boot3 的网关配置想必是大家经常接触的工作。而其中的过滤器配置，更是一个让人又爱又恨的环节。你是不是也遇到过这样的情况：精心配置好的过滤器，却没有按照预期工作；或者在过滤器链的顺序设置上，总是导致请
作为互联网大厂的开发人员，在搭建项目架构时，Spring Boot3 的网关配置想必是大家经常接触的工作。而其中的过滤器配置，更是一个让人又爱又恨的环节。你是不是也遇到过这样的情况：精心配置好的过滤器，却没有按照预期工作；或者在过滤器链的顺序设置上，总是导致请求处理出现异常？甚至有时候，连基本的参数配置都能让系统抛出莫名其妙的错误，让人抓耳挠腮，不知从何下手。别着急，接下来就为你抽丝剥茧，详细讲解 Spring Boot3 网关过滤器配置的方方面面。
Spring Boot3 的网关过滤器，是整个 API 网关的核心组件之一。它就像是一道智能关卡，能在请求进入微服务之前或响应返回客户端之前，对请求和响应进行处理。比如，它可以用来进行权限验证，确保只有合法的请求才能访问对应的服务；也能对请求进行限流，防止大量请求瞬间涌入导致服务崩溃；还能实现日志记录，方便后续对系统运行情况进行监控和排查。不过，由于 Spring Boot3 在过滤器的实现和配置方式上，相较于之前的版本有了一些变化和优化，这也使得很多开发人员在初次接触时，容易陷入各种配置的 “坑” 里。
在 Spring Boot 项目的pom.xml文件中，你需要添加 Spring Cloud Gateway 依赖，只有这样，项目才能具备网关及过滤器相关的功能。示例代码如下：
org.springframework.cloudspring-cloud-starter-gateway值得注意的是，在添加依赖时，要留意 Spring Cloud 和 Spring Boot 版本的兼容性。如果版本不匹配，很可能在后续项目运行时出现各种依赖冲突的问题。比如，Spring Cloud 的某些新特性在较低版本的 Spring Boot 中可能无法正常运行，反之亦然。可以通过官方文档提供的版本对应表，来选择合适的版本组合。
你可以选择通过 YAML 文件或者 java 配置类来进行配置。以 YAML 文件为例，假设你要将/api/**路径的请求转发到名为service - instance的服务实例上，并添加一个StripPrefix过滤器来去除第一个路径，配置如下：
spring:cloud:gateway:routes:- id: example_routeuri: lb://service - instancepredicates:- Path=/api/**filters:- StripPrefix=1这里只是一个简单示例，实际项目中，你可以根据需求添加多种过滤器。比如，使用AddrequestHeader过滤器为请求添加自定义头部信息：
Filters:- AddRequestHeader=X - Custom - Header, custom - value除了上述两种常见过滤器，还有AddRequestParameter过滤器，能在请求中添加参数。例如，在进行一些统计或者标识请求来源时，就可以使用它添加特定参数：
filters:- AddRequestParameter=source, webRetry过滤器也是非常实用的，当请求失败时，它可以自动进行重试。配置示例如下：
filters:- name: Retryargs:retries: 3statuses: BAD_GATEWAY,BAD_REQUEST上述配置表示当请求返回BAD_GATEWAY或BAD_REQUEST状态码时，会自动重试 3 次。
在过滤器组合使用时，需要特别注意过滤器之间的协同工作。比如，先使用AddRequestHeader添加认证相关头部信息，再使用权限验证过滤器，这样才能确保权限验证的准确性。如果顺序颠倒，可能会导致权限验证失败。
在过滤器的顺序方面，Spring Cloud Gateway 会按照配置文件中过滤器的定义顺序依次执行。因此，你需要根据业务逻辑，合理安排过滤器的先后顺序。比如，权限验证的过滤器应该放在靠前的位置，确保非法请求尽早被拦截；而日志记录的过滤器可以放在靠后的位置，保证对整个请求处理过程都能进行完整记录。
举个实际例子，在一个电商项目中，有商品查询、订单提交等接口。对于订单提交接口，需要先进行用户登录状态验证（使用权限验证过滤器），然后对请求参数进行合法性检查（使用自定义参数校验过滤器），最后再进行订单数据的持久化操作。如果将日志记录过滤器放在最前面，就无法准确记录到权限验证失败或者参数校验失败时的关键信息。
此外，当多个过滤器对同一个请求属性进行修改时，顺序不同也会导致不同的结果。例如，一个过滤器将请求头中的Content-Type修改为application/json，另一个过滤器又将其修改为application/xml，那么最终请求发送到后端服务时，Content-Type的值取决于后执行的过滤器。所以，在规划过滤器顺序时，一定要充分考虑业务逻辑和过滤器之间的相互影响。
另外，Spring Cloud Gateway 还提供了全局过滤器。全局过滤器会对所有经过网关的请求进行处理。你可以通过实现GlobalFilter接口，并将其注册为 Spring Bean 来创建自定义的全局过滤器。示例代码如下：
import org.springframework.cloud.gateway.filter.GatewayFilterChain;import org.springframework.cloud.gateway.filter.GlobalFilter;import org.springframework.core.Ordered;import org.springframework.http.HttpStatus;import org.springframework.stereotype.Component;import org.springframework.web.server.ServerWebExchange;import reactor.core.publisher.Mono;@Componentpublic class CustomGlobalFilter implements GlobalFilter, Ordered {@Overridepublic Mono filter(ServerWebExchange exchange, GatewayFilterChain chain) {// 在这里编写自定义的过滤逻辑，比如检查请求头中的tokenif (!exchange.getRequest.getHeaders.containsKey("Authorization")) {exchange.getResponse.setStatusCode(HttpStatus.UNAUTHORIZED);return exchange.getResponse.setComplete;}return chain.filter(exchange);}@Overridepublic int getOrder {return 0;}}在实际应用中，全局过滤器可以用于实现一些通用的功能，如统一的请求日志记录、流量监控等。比如，要实现一个全局的请求耗时统计功能，可以这样编写代码：
import org.springframework.cloud.gateway.filter.GatewayFilterChain;import org.springframework.cloud.gateway.filter.GlobalFilter;import org.springframework.core.Ordered;import org.springframework.stereotype.Component;import org.springframework.web.server.ServerWebExchange;import reactor.core.publisher.Mono;import java.util.Date;@Componentpublic class RequestTIMEFilter implements GlobalFilter, Ordered {private static final String REQUEST_TIME_BEGIN = "requestTimeBegin";@Overridepublic Mono filter(ServerWebExchange exchange, GatewayFilterChain chain) {exchange.getAttributes.put(REQUEST_TIME_BEGIN, new Date.getTime);return chain.filter(exchange).then(Mono.fromRunnable( -> {Long startTime = exchange.getAttribute(REQUEST_TIME_BEGIN);if (startTime != null) {Long executeTime = new Date.getTime - startTime;// 这里可以将请求耗时记录到日志文件或者发送到监控系统System.out.println(exchange.getRequest.getURI.getPath + ": " + executeTime + "ms");}}));}@Overridepublic int getOrder {return 1;}}上述代码在请求进入网关时记录开始时间，在请求处理完成后计算并输出请求耗时。
在配置和使用过滤器的过程中，还有一些常见问题需要注意。比如，当多个过滤器对同一个请求属性进行修改时，可能会出现冲突。这时候，你就需要仔细检查过滤器的逻辑和顺序，必要时可以通过添加中间变量等方式来避免冲突。
有时候，过滤器配置完成后，发现并没有生效。这可能是由于多种原因导致的。首先，检查依赖是否正确添加且版本兼容；其次，确认过滤器的配置语法是否正确，YAML 文件中的缩进等格式是否符合规范；再者，查看是否存在其他过滤器或者全局配置对当前过滤器产生了覆盖或者干扰。可以通过在过滤器代码中添加日志输出语句，来追踪过滤器是否被执行以及执行过程中的数据情况，从而快速定位问题。
通过以上对 Spring Boot3 网关过滤器配置的详细讲解，相信大家已经对如何正确配置有了清晰的认识。如果你在实际操作中还有其他问题，欢迎在评论区留言交流，也别忘了将这篇文章分享给身边同样在互联网开发道路上奋斗的小伙伴们，让我们一起攻克技术难题，打造更稳定、高效的系统！
来源：从程序员到架构师一点号