Spring Cloud Gateway 中直接添加过滤器时的排序问题解析

问题背景

在Spring Cloud Gateway项目中，开发者有时需要动态构建路由规则。当直接使用Route.AsyncBuilder创建路由时，可能会遇到一个隐蔽但重要的问题：直接添加的Gateway过滤器会绕过正确的排序机制，导致过滤器链执行顺序不符合预期。

问题现象

假设我们创建了一个路由规则，意图将/dog-fact路径重写为/api/facts并转发到外部API。当直接通过Route.AsyncBuilder添加RewritePathGatewayFilter时，虽然过滤器确实被添加到了过滤器链中，但路径重写功能却未能生效。

根本原因分析

问题的核心在于过滤器执行顺序。Spring Cloud Gateway内部有多个关键过滤器：

1. RouteToRequestUrlFilter（顺序10000）：负责将请求URI转换为目标服务URI
2. NettyRoutingFilter（顺序Integer.MAX_VALUE）：实际执行网络请求的过滤器
3. 自定义的路径重写过滤器（默认无顺序）

当自定义过滤器没有明确指定顺序时，它会被放在过滤器链的最后，即在NettyRoutingFilter之后执行。此时网络请求已经发出，路径重写操作变得毫无意义。

解决方案对比

错误做法：直接添加过滤器

.filter(new RewritePathGatewayFilterFactory()
        .apply(config -> config.setRegexp("/dog-fact").setReplacement("/api/facts")))

正确做法：包装为有序过滤器

.filter(new OrderedGatewayFilter(
        new RewritePathGatewayFilterFactory()
                .apply(config -> config.setRegexp("/dog-fact").setReplacement("/api/facts")),
        9999))  // 介于RouteToRequestUrlFilter和NettyRoutingFilter之间

推荐做法：使用RouteLocatorBuilder

.filters(f -> f.rewritePath("/dog-fact", "/api/facts"))

RouteLocatorBuilder内部会自动为过滤器设置默认顺序（0），确保其在关键系统过滤器之前执行。

技术深度解析

Spring Cloud Gateway的过滤器执行机制基于责任链模式，每个过滤器都可以通过实现Ordered接口或包装在OrderedGatewayFilter中来指定执行顺序。系统关键过滤器的顺序定义如下：

• 前置处理过滤器：顺序小于10000
• 路由转换过滤器：顺序10000
• 网络请求过滤器：顺序Integer.MAX_VALUE

当开发者直接操作底层Route API时，必须自行确保过滤器的正确顺序，否则会出现微妙的执行顺序问题。

最佳实践建议

1. 优先使用高级API（RouteLocatorBuilder）配置路由
2. 必须直接使用Route API时，明确为每个过滤器指定顺序
3. 路径重写类过滤器顺序应设置在10000以下
4. 考虑创建类似Spring Security的过滤器顺序枚举，提高代码可读性

总结

Spring Cloud Gateway提供了灵活的路由配置方式，但不同抽象层次API的行为差异需要开发者特别注意。理解过滤器执行顺序机制对于构建可靠的网关应用至关重要，特别是在需要动态创建路由规则的场景下。