跳到主要内容

CircuitBreaker 过滤器

DeepSeek V3 中英对照 CircuitBreaker Filter CircuitBreaker Filter

Spring Cloud CircuitBreaker GatewayFilter 工厂使用 Spring Cloud CircuitBreaker API 将网关路由包装在断路器内。Spring Cloud CircuitBreaker 支持多种可以与 Spring Cloud Gateway 一起使用的库。Spring Cloud 默认支持 Resilience4J。

要启用 Spring Cloud CircuitBreaker 过滤器，你需要在类路径上添加 spring-cloud-starter-circuitbreaker-reactor-resilience4j。以下示例配置了一个 Spring Cloud CircuitBreaker 过滤器：

spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: circuitbreaker_route
          uri: https://example.org
          filters:
          - CircuitBreaker=myCircuitBreaker
yaml
import static org.springframework.cloud.gateway.server.mvc.filter.CircuitBreakerFilterFunctions.circuitBreaker;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsCircuitBreakerNoFallback() {
        return route("circuitbreakernofallback")
                .route(path("/anything/circuitbreakernofallback"), http("https://example.org"))
                .filter(circuitBreaker("mycb3"))
                .build();
    }
}
java

要配置熔断器，请参阅您正在使用的基础熔断器实现的配置。

Spring Cloud CircuitBreaker 过滤器还可以接受一个可选的 fallbackUri 参数。目前，仅支持 forward: 方案的 URI。如果调用了回退，请求将被转发到由 URI 匹配的控制器。以下示例配置了这样的回退：

spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: circuitbreaker_route
          uri: https://example.org
          predicates:
          - Path=/consumingServiceEndpoint
          filters:
          - name: CircuitBreaker
            args:
              name: myCircuitBreaker
              fallbackUri: forward:/inCaseOfFailureUseThis
yaml

以下清单在 Java 中实现了相同的功能：

import java.net.URI;
import static org.springframework.cloud.gateway.server.mvc.filter.CircuitBreakerFilterFunctions.circuitBreaker;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsCircuitBreakerFallback() {
        return route("circuitbreaker_route")
                .route(path("/consumingServiceEndpoint"), http("https://example.org"))
                .filter(circuitBreaker("myCircuitBreaker", URI.create("forward:/inCaseOfFailureUseThis")))
                .build();
    }
}
java

此示例在调用断路器回退时，将转发到 /inCaseofFailureUseThis URI。

CircuitBreaker 也支持在 fallbackUri 中使用 URI 变量。这使得可以实现更复杂的路由选项，例如使用 PathPattern 表达式 转发原始主机或 URL 路径的部分内容。

在下面的示例中，调用 consumingServiceEndpoint/users/1 将被重定向到 inCaseOfFailureUseThis/users/1。

import java.net.URI;
import static org.springframework.cloud.gateway.server.mvc.filter.CircuitBreakerFilterFunctions.circuitBreaker;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsCircuitBreakerFallback() {
        return route("circuitbreaker_route")
                .route(path("/consumingServiceEndpoint/{*segments}"), http("https://example.org"))
                .filter(circuitBreaker("myCircuitBreaker", URI.create("forward:/inCaseOfFailureUseThis/{segments}")))
                .build();
    }
}
java

主要场景是使用 fallbackUri 在网关应用程序内部定义一个控制器或处理程序。然而，你也可以将请求重定向到外部应用程序中的控制器或处理程序，如下所示：

import static org.springframework.cloud.gateway.server.mvc.filter.CircuitBreakerFilterFunctions.circuitBreaker;
import static org.springframework.cloud.gateway.server.mvc.filter.LoadBalancerFilterFunctions.lb;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsCircuitBreakerFallbackToGatewayRoute() {
        return route("ingredients")
                .route(path("/ingredients/**"), http())
                .filter(lb("ingredients"))
                .filter(circuitBreaker("fetchIngredients", URI.create("forward:/fallback")))
                .build()
            .and(route("ingredients-fallback")
                .route(path("/fallback"), http("http://localhost:9994"))
                .build());
    }
}
java

在这个示例中，网关应用程序中没有 fallback 端点或处理程序。然而，在另一个应用程序中存在一个 fallback 处理程序，它在 [localhost:9994](http://localhost:9994) 下注册。

在请求被转发到后备处理的情况下，Spring Cloud CircuitBreaker Gateway 过滤器还会提供导致此情况的 Throwable。它被添加到 ServerRequest 中，作为 MvcUtils.CIRCUITBREAKER_EXECUTION_EXCEPTION_ATTR 属性，可以在网关应用程序内处理后备时使用。

对于外部控制器/处理程序场景，可以在异常详细信息中添加标头。你可以在FallbackHeaders Filters 部分找到更多相关信息。

基于状态码触发熔断​

在某些情况下，您可能希望根据路由返回的状态码来触发熔断器。熔断器配置对象接受一个状态码列表，如果返回的状态码在列表中，熔断器将被触发。在设置触发熔断器的状态码时，您可以使用状态码值的整数形式，也可以使用 HttpStatus 枚举的字符串表示形式。

spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: circuitbreaker_route
          uri: lb://backing-service:8088
          predicates:
          - Path=/consumingServiceEndpoint
          filters:
          - name: CircuitBreaker
            args:
              name: myCircuitBreaker
              fallbackUri: forward:/inCaseOfFailureUseThis
              statusCodes:
                - 500
                - "NOT_FOUND"
yaml
import java.net.URI;
import static org.springframework.cloud.gateway.server.mvc.filter.CircuitBreakerFilterFunctions.circuitBreaker;
import static org.springframework.cloud.gateway.server.mvc.filter.LoadBalancerFilterFunctions.lb;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsCircuitBreakerFallback() {
        return route("circuitbreaker_route")
                .route(path("/consumingServiceEndpoint"), http())
                .filter(lb("backing-service"))
				.filter(circuitBreaker(config -> config.setId("myCircuitBreaker").setFallbackUri("forward:/inCaseOfFailureUseThis").setStatusCodes("500", "NOT_FOUND")))
                .build();
    }
}
java