JAVA Spring Cloud Gateway 路由失败？详细排查断言与过滤器配置问题

Spring Cloud Gateway 路由失败？断言与过滤器配置深度剖析

大家好，今天我们来深入探讨 Spring Cloud Gateway 路由失败的问题，重点剖析断言（Predicate）和过滤器（Filter）的配置，帮助大家诊断和解决实际开发中遇到的各种路由难题。

Spring Cloud Gateway 作为微服务架构中的流量入口，负责将外部请求路由到后端的各个服务。路由规则的核心在于断言和过滤器。断言决定请求是否匹配该路由，而过滤器则负责对请求进行修改、转发或执行其他操作。当路由失败时，往往是断言配置不正确，或者过滤器配置导致请求无法正确到达目标服务。

一、路由配置基础：理解断言与过滤器

在开始深入分析之前，我们先回顾一下 Spring Cloud Gateway 的路由配置结构，并明确断言和过滤器的作用。一个典型的路由配置如下：

spring:
  cloud:
    gateway:
      routes:
        - id: my_route
          uri: lb://my-service
          predicates:
            - Path=/my-service/**
            - Method=GET,POST
          filters:
            - AddRequestHeader=X-Request-Id, ${random.uuid}
            - StripPrefix=1

• id: 路由的唯一标识符，用于管理和监控路由。
• uri: 请求转发的目标地址。lb://my-service 表示使用 LoadBalancerClient 从服务发现中心（例如 Eureka 或 Consul）获取 my-service 服务的实例地址。
• predicates: 断言列表，用于匹配请求。只有当所有断言都为 true 时，该路由才会被选中。
• filters: 过滤器列表，用于在请求转发前后对请求进行修改或执行其他操作。

1.1 断言 (Predicate) 详解

断言是路由匹配的关键。Spring Cloud Gateway 提供了多种内置的断言工厂，可以根据不同的请求属性进行匹配，例如：

断言工厂	描述
Path	匹配请求路径。可以使用 Ant 风格的路径模式。
Method	匹配 HTTP 方法（GET、POST、PUT、DELETE 等）。
Query	匹配请求参数。可以指定参数名和参数值（支持正则表达式）。
Header	匹配请求头。可以指定头名称和头值（支持正则表达式）。
Cookie	匹配 Cookie。可以指定 Cookie 名称和 Cookie 值（支持正则表达式）。
Host	匹配 Host 请求头。可以使用 Ant 风格的模式。
RemoteAddr	匹配客户端 IP 地址。支持 CIDR 表示法。
Weight	基于权重进行路由。用于实现灰度发布或流量切分。
After	匹配指定日期时间之后的请求。
Before	匹配指定日期时间之前的请求。
Between	匹配指定日期时间范围内的请求。
ReadBodyPredicateFactory	匹配请求体。 需要配置 spring.cloud.gateway.globalfilter.cached-body.enabled: true 并且引入 spring-cloud-starter-loadbalancer依赖. (在没有引入loadbalancer依赖时，会报错找不到类org.springframework.cloud.loadbalancer.support.LoadBalancerClientFactory)

1.2 过滤器 (Filter) 详解

过滤器用于在请求转发前后对请求进行修改或执行其他操作。Spring Cloud Gateway 提供了两种类型的过滤器：

• GatewayFilter: 应用于单个路由。
• GlobalFilter: 应用于所有路由。

常见的过滤器工厂包括：

过滤器工厂	描述
AddRequestHeader	添加请求头。
AddResponseHeader	添加响应头。
StripPrefix	从请求路径中移除指定数量的前缀。
RewritePath	使用正则表达式重写请求路径。
RequestRateLimiter	限制请求速率。
Retry	重试失败的请求。
Hystrix	使用 Hystrix 实现熔断和降级。
ModifyRequestBody	修改请求体。需要配置 spring.cloud.gateway.globalfilter.cached-body.enabled: true 并且引入 spring-cloud-starter-loadbalancer依赖. (在没有引入loadbalancer依赖时，会报错找不到类org.springframework.cloud.loadbalancer.support.LoadBalancerClientFactory)
ModifyResponseBody	修改响应体。
PrefixPath	为请求路径添加前缀.

二、常见的路由失败原因分析与排查

理解了断言和过滤器的作用后，我们就可以开始分析常见的路由失败原因，并提供相应的排查方法。

2.1 断言配置错误

这是最常见的路由失败原因。以下是一些具体的例子：

• 路径匹配错误：

  predicates:
    - Path=/api/v1/users

  如果请求路径是 /api/v1/users/123，则该路由不会被匹配，因为路径断言要求完全匹配。正确的配置应该使用 Ant 风格的路径模式：

  predicates:
    - Path=/api/v1/users/**

• HTTP 方法匹配错误：

  predicates:
    - Method=GET

  如果请求方法是 POST，则该路由不会被匹配。如果需要匹配多个方法，可以使用逗号分隔：

  predicates:
    - Method=GET,POST

• 请求头匹配错误：

  predicates:
    - Header=Content-Type, application/json

  如果请求头中没有 Content-Type 或者 Content-Type 的值不是 application/json，则该路由不会被匹配。请注意，请求头的值是区分大小写的。可以使用正则表达式进行更灵活的匹配：

  predicates:
    - Header=Content-Type, .*json.*

• 多个断言组合错误：

  predicates:
    - Path=/api/v1/users/**
    - Method=POST

  只有当请求路径以 /api/v1/users/ 开头并且请求方法是 POST 时，该路由才会被匹配。如果实际请求是 GET 方法，则路由失败。

排查方法：

1. 仔细检查断言配置： 确保断言的条件与实际请求的属性相匹配。
2. 使用 Gateway 的 Actuator 端点： Gateway 提供了 Actuator 端点，可以查看当前配置的路由信息。可以使用 curl 或其他 HTTP 客户端访问 /actuator/gateway/routes 端点，查看路由配置是否正确。

3. 开启 DEBUG 日志： 将 org.springframework.cloud.gateway 的日志级别设置为 DEBUG，可以查看 Gateway 的路由匹配过程。通过分析日志，可以确定哪些断言匹配失败，从而找到问题所在。

   logging:
     level:
       org.springframework.cloud.gateway: DEBUG

2.2 过滤器配置错误

过滤器配置错误也可能导致路由失败。以下是一些常见的例子：

• StripPrefix 配置错误：

  filters:
    - StripPrefix=1

  如果请求路径是 /api/v1/users/123，经过 StripPrefix=1 过滤器处理后，请求路径会变为 /v1/users/123。如果后端的服务期望接收的路径是 /api/v1/users/123，则会导致请求失败。

• RewritePath 配置错误：

  filters:
    - RewritePath=/api/(?<segment>.*), /${segment}

  这个例子会将请求路径 /api/v1/users/123 重写为 /v1/users/123。RewritePath 使用正则表达式进行匹配和替换，如果正则表达式写错，可能会导致请求路径被错误地修改。

• RequestRateLimiter 配置错误：

  filters:
    - RequestRateLimiter=redis-rate-limiter, 10, 10

  如果配置了请求速率限制，并且请求超过了限制，Gateway 会返回 429 错误（Too Many Requests）。

• 自定义过滤器错误：

  如果使用了自定义的 GatewayFilter 或 GlobalFilter，需要确保过滤器的逻辑正确，并且没有抛出异常。

排查方法：

1. 仔细检查过滤器配置： 确保过滤器的参数配置正确，并且过滤器的逻辑符合预期。
2. 禁用过滤器： 逐个禁用过滤器，观察请求是否能够成功路由。通过这种方式，可以找到导致路由失败的过滤器。
3. 查看过滤器日志： 如果使用了自定义的过滤器，可以在过滤器中添加日志，以便观察过滤器的执行过程。
4. 检查目标服务日志: 检查后端服务是否收到请求，如果收到，检查服务的处理逻辑。

2.3 服务发现与负载均衡问题

如果 Gateway 无法从服务发现中心获取目标服务的实例地址，或者负载均衡策略配置错误，也会导致路由失败。

• 服务未注册： 确保目标服务已经成功注册到服务发现中心（例如 Eureka 或 Consul）。
• 服务实例不可用： 确保目标服务至少有一个实例是可用的。
• 负载均衡策略错误： 如果使用了自定义的负载均衡策略，需要确保策略的逻辑正确。
• 防火墙问题: 确保Gateway 可以访问服务发现中心, 并且服务发现中心可以访问后端服务。

排查方法：

1. 检查服务发现中心： 登录到服务发现中心的控制台，查看目标服务是否已经注册，以及是否有可用的实例。
2. 检查服务实例健康状态： 确保目标服务的健康检查端点（例如 /actuator/health）返回的状态是 UP。
3. 检查 Gateway 日志： 查看 Gateway 的日志，确认是否能够从服务发现中心获取目标服务的实例地址。
4. 测试服务实例： 直接访问目标服务的实例，确认服务是否能够正常提供服务。
5. 检查防火墙配置: 确保Gateway 和 服务发现中心，以及后端服务之间的网络是通的。

2.4 其他常见问题

• 配置优先级问题： 如果定义了多个路由，并且这些路由的断言有重叠，需要注意路由的优先级。可以使用 order 属性指定路由的优先级，order 值越小，优先级越高。

  spring:
    cloud:
      gateway:
        routes:
          - id: route1
            uri: lb://my-service
            predicates:
              - Path=/api/**
            order: 1
          - id: route2
            uri: lb://my-service
            predicates:
              - Path=/api/v1/users/**
            order: 0

  在这个例子中，route2 的优先级高于 route1。当请求路径是 /api/v1/users/123 时，route2 会被优先匹配。

• 配置缓存问题： 有时候，Gateway 的配置可能没有及时更新。可以尝试重启 Gateway 服务，或者清除 Gateway 的配置缓存。

• 依赖冲突问题： 检查项目的依赖是否存在冲突，特别是在使用自定义过滤器时，可能会引入不兼容的依赖。

• 请求体过大导致路由失败: 如果没有开启 spring.cloud.gateway.globalfilter.cached-body.enabled: true 时，如果请求体过大，可能会导致路由失败.

三、实战案例：解决一个复杂的路由问题

假设我们遇到这样一个问题：需要将所有以 /api/v1/products/ 开头的 GET 请求路由到 product-service，并且需要在请求头中添加一个 X-Version 属性，值为 1.0。同时，需要对所有 POST 请求进行限流，限制每个 IP 地址每分钟只能发送 10 个请求。

错误配置：

spring:
  cloud:
    gateway:
      routes:
        - id: product_route
          uri: lb://product-service
          predicates:
            - Path=/api/v1/products/**
          filters:
            - AddRequestHeader=X-Version, 1.0
        - id: rate_limit_route
          uri: lb://product-service
          predicates:
            - Method=POST
          filters:
            - RequestRateLimiter=redis-rate-limiter, 10, 60

这个配置存在以下问题：

1. product_route 没有限制请求方法，会导致所有请求（包括 POST 请求）都被路由到 product-service。
2. rate_limit_route 没有限制请求路径，会导致所有 POST 请求都被限流，而不是仅仅针对 /api/v1/products/ 开头的 POST 请求。
3. product_route 只添加了请求头，没有限制请求方法为GET。

正确配置：

spring:
  cloud:
    gateway:
      routes:
        - id: product_route
          uri: lb://product-service
          predicates:
            - Path=/api/v1/products/**
            - Method=GET
          filters:
            - AddRequestHeader=X-Version, 1.0
        - id: rate_limit_route
          uri: lb://product-service
          predicates:
            - Path=/api/v1/products/**
            - Method=POST
          filters:
            - RequestRateLimiter=redis-rate-limiter, 10, 60

这个配置解决了上述问题：

1. product_route 增加了 Method=GET 断言，只匹配 GET 请求。
2. rate_limit_route 增加了 Path=/api/v1/products/** 断言，只匹配 /api/v1/products/ 开头的 POST 请求。

四、高级技巧：自定义断言和过滤器

除了使用 Spring Cloud Gateway 提供的内置断言和过滤器之外，还可以自定义断言和过滤器，以满足更复杂的需求。

4.1 自定义断言

自定义断言需要实现 org.springframework.cloud.gateway.handler.predicate.RoutePredicateFactory 接口。以下是一个简单的例子，用于匹配请求头中包含指定值的断言：

@Component
public class CustomHeaderRoutePredicateFactory extends AbstractRoutePredicateFactory<CustomHeaderRoutePredicateFactory.Config> {

    public CustomHeaderRoutePredicateFactory() {
        super(Config.class);
    }

    @Override
    public Predicate<ServerWebExchange> apply(Config config) {
        return exchange -> {
            String headerValue = exchange.getRequest().getHeaders().getFirst(config.getHeaderName());
            return headerValue != null && headerValue.contains(config.getHeaderValue());
        };
    }

    @Override
    public List<String> shortcutFieldOrder() {
        return Arrays.asList("headerName", "headerValue");
    }

    public static class Config {
        private String headerName;
        private String headerValue;

        public String getHeaderName() {
            return headerName;
        }

        public void setHeaderName(String headerName) {
            this.headerName = headerName;
        }

        public String getHeaderValue() {
            return headerValue;
        }

        public void setHeaderValue(String headerValue) {
            this.headerValue = headerValue;
        }
    }
}

在配置文件中使用自定义断言：

spring:
  cloud:
    gateway:
      routes:
        - id: custom_header_route
          uri: lb://my-service
          predicates:
            - CustomHeader=X-Custom-Header, my-value

4.2 自定义过滤器

自定义过滤器需要实现 org.springframework.cloud.gateway.filter.GatewayFilter 接口或 org.springframework.cloud.gateway.filter.GlobalFilter 接口。以下是一个简单的例子，用于在请求头中添加时间戳的过滤器：

@Component
public class TimestampGatewayFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        exchange.getRequest().mutate()
                .header("X-Timestamp", String.valueOf(System.currentTimeMillis()))
                .build();
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return 0; // 设置过滤器的优先级，值越小优先级越高
    }
}

五、调试技巧：利用 Spring Cloud Gateway 的 Actuator 端点

Spring Cloud Gateway 提供了丰富的 Actuator 端点，可以帮助我们调试路由问题。

• /actuator/gateway/routes: 查看当前配置的路由信息。
• /actuator/gateway/routefilters: 查看当前配置的过滤器信息。
• /actuator/gateway/globalfilters: 查看当前配置的全局过滤器信息。
• /actuator/gateway/metrics: 查看 Gateway 的指标信息，例如请求数量、响应时间等。
• /actuator/health: 查看 Gateway 的健康状态。

通过这些 Actuator 端点，我们可以更全面地了解 Gateway 的运行状态，从而更好地诊断和解决路由问题。

总结

Spring Cloud Gateway 的路由失败问题可能由多种原因引起，包括断言配置错误、过滤器配置错误、服务发现与负载均衡问题等。通过仔细检查配置、开启 DEBUG 日志、使用 Actuator 端点以及逐步排查，可以有效地诊断和解决这些问题。掌握自定义断言和过滤器的技巧，可以更好地满足复杂的路由需求。

希望今天的分享能够帮助大家更好地理解和使用 Spring Cloud Gateway，避免踩坑，构建更健壮的微服务架构。

总结

路由配置是关键，理解断言和过滤器，灵活运用，就能解决大部分路由问题。
同时，利用Actuator端点和调试技巧，可以更高效地排查问题。
自定义断言和过滤器，满足更复杂的需求，让你的网关更强大。