6. GatewayFilter 工厂 (6. GatewayFilter Factories) _ Spring Cloud Gateway3.0.8中文文档(官方文档中文翻译)|Spring 教程 —

6. `GatewayFilter` 工厂

路由筛选器允许以某种方式修改传入的 HTTP 请求或传出的 HTTP 响应。路由过滤器的范围限定为特定路由。 Spring Cloud 网关包括许多内置的 GatewayFilter 工厂。spring-doc.cn

有关如何使用以下任何筛选器的更详细示例，请查看单元测试。

`6.1.AddRequestHeaderGatewayFilter`工厂

工厂采用 and 参数。以下示例配置了一个：AddRequestHeaderGatewayFilternamevalueAddRequestHeaderGatewayFilterspring-doc.cn

例 13.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: add_request_header_route
        uri: https://example.org
        filters:
        - AddRequestHeader=X-Request-red, blue

此清单将 header 添加到所有匹配请求的下游请求的 headers 中。X-Request-red:bluespring-doc.cn

AddRequestHeader知道用于匹配路径或主机的 URI 变量。 URI 变量可以在值中使用，并在运行时扩展。以下示例配置了使用变量的 an：AddRequestHeaderGatewayFilterspring-doc.cn

例 14.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: add_request_header_route
        uri: https://example.org
        predicates:
        - Path=/red/{segment}
        filters:
        - AddRequestHeader=X-Request-Red, Blue-{segment}

6.2. `AddRequestParameter` `GatewayFilter` 工厂

Factory 采用 and 参数。以下示例配置了一个：AddRequestParameterGatewayFilternamevalueAddRequestParameterGatewayFilterspring-doc.cn

例 15.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: add_request_parameter_route
        uri: https://example.org
        filters:
        - AddRequestParameter=red, blue

这将添加到所有匹配请求的下游请求的查询字符串中。red=bluespring-doc.cn

AddRequestParameter知道用于匹配路径或主机的 URI 变量。 URI 变量可以在值中使用，并在运行时扩展。以下示例配置了使用变量的 an：AddRequestParameterGatewayFilterspring-doc.cn

例 16.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: add_request_parameter_route
        uri: https://example.org
        predicates:
        - Host: {segment}.myhost.org
        filters:
        - AddRequestParameter=foo, bar-{segment}

6.3. `AddResponseHeader` `GatewayFilter` 工厂

Factory 采用 and 参数。以下示例配置了一个：AddResponseHeaderGatewayFilternamevalueAddResponseHeaderGatewayFilterspring-doc.cn

例 17.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: add_response_header_route
        uri: https://example.org
        filters:
        - AddResponseHeader=X-Response-Red, Blue

这会将 header 添加到所有匹配请求的下游响应的 header 中。X-Response-Foo:Barspring-doc.cn

AddResponseHeader知道用于匹配路径或主机的 URI 变量。 URI 变量可以在值中使用，并在运行时扩展。以下示例配置了使用变量的 an：AddResponseHeaderGatewayFilterspring-doc.cn

例 18.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: add_response_header_route
        uri: https://example.org
        predicates:
        - Host: {segment}.myhost.org
        filters:
        - AddResponseHeader=foo, bar-{segment}

6.4. `DedupeResponseHeader` `GatewayFilter` 工厂

DedupeResponseHeader GatewayFilter 工厂采用一个参数和一个可选参数。可以包含以空格分隔的 Headers 名称列表。以下示例配置了一个：namestrategynameDedupeResponseHeaderGatewayFilterspring-doc.cn

例 19.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: dedupe_response_header_route
        uri: https://example.org
        filters:
        - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin

这将在网关 CORS 逻辑和下游逻辑都添加和 response 标头的重复值时删除它们。Access-Control-Allow-CredentialsAccess-Control-Allow-Originspring-doc.cn

filter 还接受一个可选参数。接受的值为（default）、和。DedupeResponseHeaderstrategyRETAIN_FIRSTRETAIN_LASTRETAIN_UNIQUEspring-doc.cn

6.5. Spring Cloud CircuitBreaker GatewayFilter 工厂

Spring Cloud CircuitBreaker GatewayFilter工厂使用 Spring Cloud CircuitBreaker API 将网关路由包装在断路器。Spring Cloud CircuitBreaker 支持多个可与 Spring Cloud Gateway 一起使用的库。Spring Cloud 支持开箱即用的 Resilience4J。spring-doc.cn

要启用 Spring Cloud CircuitBreaker 过滤器，你需要放在 Classpath 上。以下示例配置Spring Cloud CircuitBreaker：spring-cloud-starter-circuitbreaker-reactor-resilience4jGatewayFilterspring-doc.cn

例 20.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: circuitbreaker_route
        uri: https://example.org
        filters:
        - CircuitBreaker=myCircuitBreaker

要配置断路器，请参阅您正在使用的底层断路器实现的配置。spring-doc.cn

Resilience4J 文档 spring-doc.cn

Spring Cloud CircuitBreaker 过滤器也可以接受可选参数。目前，仅支持方案化 URI。如果调用了回退，则请求将转发到与 URI 匹配的控制器。以下示例配置了此类回退：fallbackUriforward:spring-doc.cn

例 21.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: circuitbreaker_route
        uri: lb://backing-service:8088
        predicates:
        - Path=/consumingServiceEndpoint
        filters:
        - name: CircuitBreaker
          args:
            name: myCircuitBreaker
            fallbackUri: forward:/inCaseOfFailureUseThis
        - RewritePath=/consumingServiceEndpoint, /backingServiceEndpoint

下面的清单在 Java 中执行相同的操作：spring-doc.cn

例 22.Application.java

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("circuitbreaker_route", r -> r.path("/consumingServiceEndpoint")
            .filters(f -> f.circuitBreaker(c -> c.name("myCircuitBreaker").fallbackUri("forward:/inCaseOfFailureUseThis"))
                .rewritePath("/consumingServiceEndpoint", "/backingServiceEndpoint")).uri("lb://backing-service:8088")
        .build();
}

此示例在调用断路器回退时转发到 URI。请注意，此示例还演示了（可选）Spring Cloud LoadBalancer 负载平衡（由目标 URI 上的前缀定义）。/inCaseofFailureUseThislbspring-doc.cn

主要方案是使用来定义网关应用程序中的内部控制器或处理程序。但是，您也可以将请求重新路由到外部应用程序中的控制器或处理程序，如下所示：fallbackUrispring-doc.cn

例 23.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: ingredients
        uri: lb://ingredients
        predicates:
        - Path=//ingredients/**
        filters:
        - name: CircuitBreaker
          args:
            name: fetchIngredients
            fallbackUri: forward:/fallback
      - id: ingredients-fallback
        uri: http://localhost:9994
        predicates:
        - Path=/fallback

在此示例中，网关应用程序中没有终端节点或处理程序。但是，在另一个应用程序中有一个，在下注册。fallbacklocalhost:9994spring-doc.cn

如果请求被转发到 fallback，Spring Cloud CircuitBreaker Gateway 过滤器还会提供导致该请求的原因。它被添加到作为属性中，在网关应用程序中处理回退时可以使用该属性。ThrowableServerWebExchangeServerWebExchangeUtils.CIRCUITBREAKER_EXECUTION_EXCEPTION_ATTRspring-doc.cn

对于外部控制器/处理程序方案，可以添加包含异常详细信息的标头。你可以在FallbackHeaders GatewayFilter Factory部分找到有关执行此操作的更多信息。spring-doc.cn

6.5.1. 在状态代码上使断路器跳闸

在某些情况下，您可能希望根据状态代码触发断路器从它包装的路由返回。断路器配置对象采用状态代码，如果返回，将导致断路器跳闸。在设置状态代码您希望使断路器跳闸，您可以使用带有状态代码的整数 value 或枚举的 String 表示形式。HttpStatusspring-doc.cn

例 24.application.yml

spring:
  cloud:
    gateway:
      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"

例 25.Application.java

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("circuitbreaker_route", r -> r.path("/consumingServiceEndpoint")
            .filters(f -> f.circuitBreaker(c -> c.name("myCircuitBreaker").fallbackUri("forward:/inCaseOfFailureUseThis").addStatusCode("INTERNAL_SERVER_ERROR"))
                .rewritePath("/consumingServiceEndpoint", "/backingServiceEndpoint")).uri("lb://backing-service:8088")
        .build();
}

6.6. `FallbackHeaders` `GatewayFilter` 工厂

工厂允许您在转发到外部应用程序中的请求的 Headers 中添加 Spring Cloud CircuitBreaker 执行异常详细信息，如以下场景所示：FallbackHeadersfallbackUrispring-doc.cn

例 26.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: ingredients
        uri: lb://ingredients
        predicates:
        - Path=//ingredients/**
        filters:
        - name: CircuitBreaker
          args:
            name: fetchIngredients
            fallbackUri: forward:/fallback
      - id: ingredients-fallback
        uri: http://localhost:9994
        predicates:
        - Path=/fallback
        filters:
        - name: FallbackHeaders
          args:
            executionExceptionTypeHeaderName: Test-Header

在此示例中，在运行断路器时发生执行异常后，请求将转发到上运行的应用程序中的端点或处理程序。筛选器会将具有异常类型、消息和（如果可用）根本原因异常类型和消息的标头添加到该请求中。fallbacklocalhost:9994FallbackHeadersspring-doc.cn

您可以通过设置以下参数的值（以默认值显示）来覆盖配置中标头的名称：spring-doc.cn

executionExceptionTypeHeaderName ("Execution-Exception-Type")spring-doc.cn
executionExceptionMessageHeaderName ("Execution-Exception-Message")spring-doc.cn
rootCauseExceptionTypeHeaderName ("Root-Cause-Exception-Type")spring-doc.cn
rootCauseExceptionMessageHeaderName ("Root-Cause-Exception-Message")spring-doc.cn

有关断路器和网关的更多信息，请参阅 Spring Cloud CircuitBreaker Factory 部分。spring-doc.cn

`6.7.MapRequestHeader` `GatewayFilter` 工厂

工厂 take 和 parameters. 它会创建一个新的命名标头（），并从传入的 http 请求中从现有的命名标头（）中提取该值。如果 input 标头不存在，则筛选器不会产生任何影响。如果新的命名标头已存在，则其值将使用新值进行扩充。以下示例配置了一个：MapRequestHeaderGatewayFilterfromHeadertoHeadertoHeaderfromHeaderMapRequestHeaderspring-doc.cn

例 27.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: map_request_header_route
        uri: https://example.org
        filters:
        - MapRequestHeader=Blue, X-Request-Red

这会使用传入 HTTP 请求标头中的更新值向下游请求添加标头。X-Request-Red:<values>Bluespring-doc.cn

6.8. `PrefixPath` `GatewayFilter` 工厂

工厂采用单个参数。以下示例配置了一个：PrefixPathGatewayFilterprefixPrefixPathGatewayFilterspring-doc.cn

例 28.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: prefixpath_route
        uri: https://example.org
        filters:
        - PrefixPath=/mypath

这将作为所有匹配请求的路径的前缀。因此，请求将发送到。/mypath/hello/mypath/hellospring-doc.cn

6.9. `PreserveHostHeader` `GatewayFilter` 工厂

工厂没有参数。此筛选器设置路由筛选器检查的请求属性，以确定是否应发送原始主机标头，而不是由 HTTP 客户端确定的主机标头。以下示例配置了一个：PreserveHostHeaderGatewayFilterPreserveHostHeaderGatewayFilterspring-doc.cn

例 29.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: preserve_host_route
        uri: https://example.org
        filters:
        - PreserveHostHeader

`6.10.RequestRateLimiter` `GatewayFilter` 工厂

工厂使用 implementation 来确定是否允许当前请求继续进行。如果不是，则返回状态（默认情况下）。RequestRateLimiterGatewayFilterRateLimiterHTTP 429 - Too Many Requestsspring-doc.cn

此筛选条件采用可选参数和特定于速率限制器的参数（本节稍后将介绍）。keyResolverspring-doc.cn

keyResolver是实现接口的 Bean。在配置中，使用 SPEL 按名称引用 bean。是一个 SpEL 表达式，它引用名为 . 下面的清单显示了该接口：KeyResolver#{@myKeyResolver}myKeyResolverKeyResolverspring-doc.cn

例 30.KeyResolver.java

public interface KeyResolver {
    Mono<String> resolve(ServerWebExchange exchange);
}

该接口允许可插拔策略派生用于限制请求的密钥。在未来的里程碑版本中，将有一些实施。KeyResolverKeyResolverspring-doc.cn

的默认实现是，它从和调用中检索。KeyResolverPrincipalNameKeyResolverPrincipalServerWebExchangePrincipal.getName()spring-doc.cn

默认情况下，如果找不到 key，则拒绝请求。您可以通过设置（）或）和属性来调整此行为。KeyResolverspring.cloud.gateway.filter.request-rate-limiter.deny-empty-keytruefalsespring.cloud.gateway.filter.request-rate-limiter.empty-key-status-codespring-doc.cn

不能使用 “shortcut” 表示法进行配置。以下示例无效：RequestRateLimiterspring-doc.cn

例 31.application.properties

# INVALID SHORTCUT CONFIGURATION
spring.cloud.gateway.routes[0].filters[0]=RequestRateLimiter=2, 2, #{@userkeyresolver}

6.10.1. Redis `RateLimiter`

Redis 实现基于 Stripe 所做的工作。它需要使用 Spring Boot Starters。spring-boot-starter-data-redis-reactivespring-doc.cn

使用的算法是 Token Bucket Algorithm。spring-doc.cn

该属性是您希望允许用户每秒执行的请求数，而不会丢弃任何请求。这是填充令牌桶的速率。redis-rate-limiter.replenishRatespring-doc.cn

该属性是允许用户在一秒钟内执行的最大请求数。这是令牌桶可以容纳的令牌数量。将此值设置为 0 会阻止所有请求。redis-rate-limiter.burstCapacityspring-doc.cn

该属性是请求花费的令牌数。这是每个请求从存储桶中获取的令牌数，默认为。redis-rate-limiter.requestedTokens1spring-doc.cn

通过在和中设置相同的值来实现稳定的速率。可以通过设置高于 . 在这种情况下，需要在突发之间允许速率限制器一段时间（根据），因为两个连续的突发将导致请求丢弃（）。下面的清单配置了一个：replenishRateburstCapacityburstCapacityreplenishRatereplenishRateHTTP 429 - Too Many Requestsredis-rate-limiterspring-doc.cn

以下速率限制是通过设置为所需的请求数、时间跨度（以秒为单位）以及和的乘积（例如设置）来实现的，并且将导致限制。1 request/sreplenishRaterequestedTokensburstCapacityreplenishRaterequestedTokensreplenishRate=1requestedTokens=60burstCapacity=601 request/minspring-doc.cn

例 32.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: requestratelimiter_route
        uri: https://example.org
        filters:
        - name: RequestRateLimiter
          args:
            redis-rate-limiter.replenishRate: 10
            redis-rate-limiter.burstCapacity: 20
            redis-rate-limiter.requestedTokens: 1

以下示例在 Java 中配置 KeyResolver：spring-doc.cn

例 33.Config.java

@Bean
KeyResolver userKeyResolver() {
    return exchange -> Mono.just(exchange.getRequest().getQueryParams().getFirst("user"));
}

这将每个用户的请求速率限制为 10。允许突增 20 个，但在下一秒，只有 10 个请求可用。这是一个获取 request 参数的简单参数（请注意，不建议将其用于 production）。KeyResolveruserspring-doc.cn

您还可以将速率限制器定义为实现该接口的 Bean。在配置中，您可以使用 SpEL 按名称引用 Bean。是一个 SpEL 表达式，它引用名为的 bean 。下面的清单定义了一个速率限制器，它使用上一个清单中定义的速率限制器：RateLimiter#{@myRateLimiter}myRateLimiterKeyResolverspring-doc.cn

例 34.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: requestratelimiter_route
        uri: https://example.org
        filters:
        - name: RequestRateLimiter
          args:
            rate-limiter: "#{@myRateLimiter}"
            key-resolver: "#{@userKeyResolver}"

6.11. `RedirectTo` `GatewayFilter` 工厂

工厂采用两个参数，和 . 该参数应为 300 系列重定向 HTTP 代码，例如 301。该参数应为有效的 URL。这是标头的值。对于相对重定向，您应该用作路由定义的 URI。下面的清单配置了一个：RedirectToGatewayFilterstatusurlstatusurlLocationuri: no://opRedirectToGatewayFilterspring-doc.cn

例 35.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: prefixpath_route
        uri: https://example.org
        filters:
        - RedirectTo=302, https://acme.org

这将发送一个状态 302 和一个 Headers 来执行重定向。Location:https://acme.orgspring-doc.cn

6.12. `RemoveRequestHeader` GatewayFilter 工厂

工厂采用一个参数。它是要删除的标头的名称。下面的清单配置了一个：RemoveRequestHeaderGatewayFilternameRemoveRequestHeaderGatewayFilterspring-doc.cn

例 36.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: removerequestheader_route
        uri: https://example.org
        filters:
        - RemoveRequestHeader=X-Request-Foo

这会在将标头发送到下游之前将其删除。X-Request-Foospring-doc.cn

6.13. `RemoveResponseHeader` `GatewayFilter` 工厂

工厂采用一个参数。它是要删除的标头的名称。下面的清单配置了一个：RemoveResponseHeaderGatewayFilternameRemoveResponseHeaderGatewayFilterspring-doc.cn

例 37.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: removeresponseheader_route
        uri: https://example.org
        filters:
        - RemoveResponseHeader=X-Response-Foo

这将在响应返回到网关客户端之前从响应中删除标头。X-Response-Foospring-doc.cn

要删除任何类型的敏感报头，您应该为可能需要的任何路由配置此过滤器。此外，您还可以使用此过滤器配置一次，然后将其应用于所有路由。spring.cloud.gateway.default-filtersspring-doc.cn

6.14. `RemoveRequestParameter` `GatewayFilter` 工厂

工厂采用一个参数。它是要删除的查询参数的名称。以下示例配置了一个：RemoveRequestParameterGatewayFilternameRemoveRequestParameterGatewayFilterspring-doc.cn

例 38.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: removerequestparameter_route
        uri: https://example.org
        filters:
        - RemoveRequestParameter=red

这将在参数被发送到下游之前将其删除。redspring-doc.cn

6.15. `RewritePath` `GatewayFilter` 工厂

工厂采用 path 参数和 parameter。它使用 Java 正则表达式来灵活地重写请求路径。下面的清单配置了一个：RewritePathGatewayFilterregexpreplacementRewritePathGatewayFilterspring-doc.cn

例 39.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: rewritepath_route
        uri: https://example.org
        predicates:
        - Path=/red/**
        filters:
        - RewritePath=/red/?(?<segment>.*), /$\{segment}

对于请求路径，这会将路径设置为发出下游请求之前。请注意，由于 YAML 规范，应将其替换为 the。/red/blue/blue$$\spring-doc.cn

6.16. `RewriteLocationResponseHeader` `GatewayFilter` 工厂

工厂修改响应头的值，通常是为了摆脱特定于后端的细节。它需要、、和参数。下面的清单配置了一个：RewriteLocationResponseHeaderGatewayFilterLocationstripVersionModelocationHeaderNamehostValueprotocolsRegexRewriteLocationResponseHeaderGatewayFilterspring-doc.cn

例 40.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: rewritelocationresponseheader_route
        uri: http://example.org
        filters:
        - RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,

例如，对于请求，响应标头值的将重写为。POST api.example.com/some/object/nameLocationobject-service.prod.example.net/v2/some/object/idapi.example.com/some/object/idspring-doc.cn

该参数具有以下可能的值：、（default）和 .stripVersionModeNEVER_STRIPAS_IN_REQUESTALWAYS_STRIPspring-doc.cn

NEVER_STRIP：即使原始请求路径不包含版本，也不会剥离版本。spring-doc.cn
AS_IN_REQUEST仅当原始请求路径不包含版本时，才会剥离版本。spring-doc.cn
ALWAYS_STRIP版本始终被剥离，即使原始请求路径包含 version。spring-doc.cn

该参数（如果提供）用于替换响应标头的部分。如果未提供，则使用 request 标头的值。hostValuehost:portLocationHostspring-doc.cn

该参数必须是与协议名称匹配的有效 regex 。如果不匹配，则筛选器不执行任何操作。默认值为 .protocolsRegexStringhttp|https|ftp|ftpsspring-doc.cn

6.17. `RewriteResponseHeader` `GatewayFilter` 工厂

工厂采用、和参数。它使用 Java 正则表达式来灵活地重写响应标头值。以下示例配置了一个：RewriteResponseHeaderGatewayFilternameregexpreplacementRewriteResponseHeaderGatewayFilterspring-doc.cn

例 41.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: rewriteresponseheader_route
        uri: https://example.org
        filters:
        - RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=***

对于标头值，它设置为在发出下游请求之后。由于 YAML 规范，您必须使用 to mean。/42?user=ford&password=omg!what&flag=true/42?user=ford&password=***&flag=true$\$spring-doc.cn

6.18. `SaveSession` `GatewayFilter` 工厂

工厂在将调用转发到下游之前强制执行操作。当使用带有惰性数据存储的 Spring Session 之类的东西时，这特别有用，你需要确保在进行转发调用之前已经保存了会话状态。以下示例配置了一个：SaveSessionGatewayFilterWebSession::saveSaveSessionGatewayFilterspring-doc.cn

例 42.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: save_session
        uri: https://example.org
        predicates:
        - Path=/foo/**
        filters:
        - SaveSession

如果您将 Spring Security 与 Spring Session 集成，并希望确保已将安全详细信息转发到远程进程，那么这一点至关重要。spring-doc.cn

6.19. `SecureHeaders` `GatewayFilter` 工厂

工厂根据此博客文章中的建议向响应添加许多标头。SecureHeadersGatewayFilterspring-doc.cn

添加了以下标头（以其默认值显示）：spring-doc.cn

X-Xss-Protection:1 (mode=block)spring-doc.cn
Strict-Transport-Security (max-age=631138519)spring-doc.cn
X-Frame-Options (DENY)spring-doc.cn
X-Content-Type-Options (nosniff)spring-doc.cn
Referrer-Policy (no-referrer)spring-doc.cn
Content-Security-Policy (default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline)'spring-doc.cn
X-Download-Options (noopen)spring-doc.cn
X-Permitted-Cross-Domain-Policies (none)spring-doc.cn

要更改默认值，请在命名空间中设置相应的属性。以下属性可用：spring.cloud.gateway.filter.secure-headersspring-doc.cn

xss-protection-headerspring-doc.cn
strict-transport-securityspring-doc.cn
x-frame-optionsspring-doc.cn
x-content-type-optionsspring-doc.cn
referrer-policyspring-doc.cn
content-security-policyspring-doc.cn
x-download-optionsspring-doc.cn
x-permitted-cross-domain-policiesspring-doc.cn

要禁用默认值，请使用逗号分隔值设置该属性。以下示例显示了如何执行此操作：spring.cloud.gateway.filter.secure-headers.disablespring-doc.cn

spring.cloud.gateway.filter.secure-headers.disable=x-frame-options,strict-transport-security

需要使用安全标头的小写全名来禁用它..

6.20. `SetPath` `GatewayFilter` 工厂

工厂采用 path 参数。它提供了一种简单的方法来操作请求路径，方法是允许路径的模板化段。这使用了 Spring Framework 中的 URI 模板。允许多个匹配的区段。以下示例配置了一个：SetPathGatewayFiltertemplateSetPathGatewayFilterspring-doc.cn

例 43.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: setpath_route
        uri: https://example.org
        predicates:
        - Path=/red/{segment}
        filters:
        - SetPath=/{segment}

对于请求路径，这会将路径设置为发出下游请求之前。/red/blue/bluespring-doc.cn

6.21. `SetRequestHeader` `GatewayFilter` 工厂

工厂 take 和 parameters. 下面的清单配置了一个：SetRequestHeaderGatewayFilternamevalueSetRequestHeaderGatewayFilterspring-doc.cn

例 44.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: setrequestheader_route
        uri: https://example.org
        filters:
        - SetRequestHeader=X-Request-Red, Blue

这会用给定的名称替换（而不是添加）所有标头。因此，如果下游服务器以，这将替换为，这是下游服务将接收到的内容。GatewayFilterX-Request-Red:1234X-Request-Red:Bluespring-doc.cn

SetRequestHeader知道用于匹配路径或主机的 URI 变量。 URI 变量可以在值中使用，并在运行时扩展。以下示例配置了使用变量的 an：SetRequestHeaderGatewayFilterspring-doc.cn

例 45.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: setrequestheader_route
        uri: https://example.org
        predicates:
        - Host: {segment}.myhost.org
        filters:
        - SetRequestHeader=foo, bar-{segment}

6.22. `SetResponseHeader` `GatewayFilter` 工厂

工厂 take 和 parameters. 下面的清单配置了一个：SetResponseHeaderGatewayFilternamevalueSetResponseHeaderGatewayFilterspring-doc.cn

例 46.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: setresponseheader_route
        uri: https://example.org
        filters:
        - SetResponseHeader=X-Response-Red, Blue

这个GatewayFilter用给定的名称替换（而不是添加）所有 headers。因此，如果下游服务器以响应，则将其替换为，这是网关客户端将接收到的内容。X-Response-Red:1234X-Response-Red:Bluespring-doc.cn

SetResponseHeader知道用于匹配路径或主机的 URI 变量。 URI 变量可以在值中使用，并将在运行时扩展。以下示例配置了使用变量的 an：SetResponseHeaderGatewayFilterspring-doc.cn

例 47.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: setresponseheader_route
        uri: https://example.org
        predicates:
        - Host: {segment}.myhost.org
        filters:
        - SetResponseHeader=foo, bar-{segment}

6.23. `SetStatus` `GatewayFilter`工厂

工厂采用单个参数 . 它必须是有效的 Spring 。它可以是整数值或枚举的字符串表示形式： . 下面的清单配置了一个：SetStatusGatewayFilterstatusHttpStatus404NOT_FOUNDSetStatusGatewayFilterspring-doc.cn

例 48.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: setstatusstring_route
        uri: https://example.org
        filters:
        - SetStatus=BAD_REQUEST
      - id: setstatusint_route
        uri: https://example.org
        filters:
        - SetStatus=401

在任一情况下，响应的 HTTP 状态都设置为 401。spring-doc.cn

您可以将配置为在响应的标头中从代理请求返回原始 HTTP 状态代码。如果配置了以下属性，则会将标头添加到响应中：SetStatusGatewayFilterspring-doc.cn

例 49.application.yml

spring:
  cloud:
    gateway:
      set-status:
        original-status-header-name: original-http-status

6.24. `StripPrefix` `GatewayFilter` 工厂

工厂采用一个参数 . 该参数指示在将请求发送到下游之前要从请求中删除的路径中的部分数。下面的清单配置了一个：StripPrefixGatewayFilterpartspartsStripPrefixGatewayFilterspring-doc.cn

例 50.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: nameRoot
        uri: https://nameservice
        predicates:
        - Path=/name/**
        filters:
        - StripPrefix=2

当通过网关发出请求时，向发出的请求类似于。/name/blue/rednameservicenameservice/redspring-doc.cn

6.25. 重试 `GatewayFilter` 工厂

工厂支持以下参数：RetryGatewayFilterspring-doc.cn

retries：应尝试的重试次数。spring-doc.cn
statuses：应重试的 HTTP 状态代码，用 .org.springframework.http.HttpStatusspring-doc.cn
methods：应重试的 HTTP 方法，用 .org.springframework.http.HttpMethodspring-doc.cn
series：要重试的一系列状态代码，用表示。org.springframework.http.HttpStatus.Seriesspring-doc.cn
exceptions：应重试的引发异常的列表。spring-doc.cn
backoff：为重试配置的指数回退。重试在的回退间隔后执行，其中是迭代。如果已配置，则应用的最大回退限制为。如果为 true，则使用计算回退。firstBackoff * (factor ^ n)nmaxBackoffmaxBackoffbasedOnPreviousValueprevBackoff * factorspring-doc.cn

如果启用，则为 filter 配置以下默认值：Retryspring-doc.cn

retries：三次spring-doc.cn
series： 5XX 系列spring-doc.cn
methods：GET 方法spring-doc.cn
exceptions：和IOExceptionTimeoutExceptionspring-doc.cn
backoff：禁用spring-doc.cn

以下清单配置了 Retry ：GatewayFilterspring-doc.cn

例 51.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: retry_test
        uri: http://localhost:8080/flakey
        predicates:
        - Host=*.retry.com
        filters:
        - name: Retry
          args:
            retries: 3
            statuses: BAD_GATEWAY
            methods: GET,POST
            backoff:
              firstBackoff: 10ms
              maxBackoff: 50ms
              factor: 2
              basedOnPreviousValue: false

将重试筛选条件与带前缀的 URL 一起使用时，应仔细编写目标终端节点，以便在出现错误时，它不会执行任何可能导致将响应发送到客户端并提交的操作。例如，如果目标终端节点是带 Comments 的控制器，则目标控制器方法不应返回错误状态代码。相反，它应该引发错误（或发出错误信号，例如，通过返回值），重试筛选条件可以通过重试来处理该错误。forward:ResponseEntityExceptionMono.error(ex)

当将重试过滤器与任何带有正文的 HTTP 方法一起使用时，正文将被缓存，网关将受到内存限制。正文缓存在由定义的请求属性中。对象的类型是 .ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTRorg.springframework.core.io.buffer.DataBuffer

可以使用单个和添加简化的“快捷方式”表示法。statusmethodspring-doc.cn

以下两个示例是等效的：spring-doc.cn

例 52.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: retry_route
        uri: https://example.org
        filters:
        - name: Retry
          args:
            retries: 3
            statuses: INTERNAL_SERVER_ERROR
            methods: GET
            backoff:
              firstBackoff: 10ms
              maxBackoff: 50ms
              factor: 2
              basedOnPreviousValue: false

      - id: retryshortcut_route
        uri: https://example.org
        filters:
        - Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false

6.26. `RequestSize` `GatewayFilter` 工厂

当请求大小大于允许的限制时，工厂可以限制请求到达下游服务。过滤器采用一个参数。类型，因此值可以定义为一个数字，后跟一个可选后缀，如“KB”或“MB”。字节的默认值为 'B'。它是以字节为单位定义的请求的允许大小限制。下面的清单配置了一个：RequestSizeGatewayFiltermaxSizemaxSize is a `DataSizeDataUnitRequestSizeGatewayFilterspring-doc.cn

例 53.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: request_size_route
        uri: http://localhost:8080/upload
        predicates:
        - Path=/upload
        filters:
        - name: RequestSize
          args:
            maxSize: 5000000

当请求因大小而被拒绝时，工厂会将响应状态设置为带有附加标头。以下示例显示了这样的：RequestSizeGatewayFilter413 Payload Too LargeerrorMessageerrorMessagespring-doc.cn

errorMessage` : `Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB

如果未在路由定义中作为 filter 参数提供，则默认请求大小设置为 5 MB。

6.27. `SetRequestHostHeader` `GatewayFilter` 工厂

在某些情况下，可能需要覆盖主机标头。在这种情况下，工厂可以用指定的 vaue 替换现有的 host 头。过滤器采用一个参数。下面的清单配置了一个：SetRequestHostHeaderGatewayFilterhostSetRequestHostHeaderGatewayFilterspring-doc.cn

例 54.application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: set_request_host_header_route
        uri: http://localhost:8080/headers
        predicates:
        - Path=/headers
        filters:
        - name: SetRequestHostHeader
          args:
            host: example.org

工厂将主机标头的值替换为 .SetRequestHostHeaderGatewayFilterexample.orgspring-doc.cn

6.28. 修改请求体 `GatewayFilter` 工厂

您可以使用筛选条件筛选条件在网关向下游发送请求之前修改请求正文。ModifyRequestBodyspring-doc.cn

此过滤器只能使用 Java DSL 进行配置。

以下清单显示了如何修改 request body ：GatewayFilterspring-doc.cn

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("rewrite_request_obj", r -> r.host("*.rewriterequestobj.org")
            .filters(f -> f.prefixPath("/httpbin")
                .modifyRequestBody(String.class, Hello.class, MediaType.APPLICATION_JSON_VALUE,
                    (exchange, s) -> return Mono.just(new Hello(s.toUpperCase())))).uri(uri))
        .build();
}

static class Hello {
    String message;

    public Hello() { }

    public Hello(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

如果请求没有正文，则将 . 应返回以在请求中分配缺少的正文。RewriteFilternullMono.empty()

6.29. 修改响应体 `GatewayFilter` 工厂

在将响应发送回客户端之前，您可以使用筛选器修改响应正文。ModifyResponseBodyspring-doc.cn

此过滤器只能使用 Java DSL 进行配置。

以下清单显示了如何修改响应正文：GatewayFilterspring-doc.cn

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("rewrite_response_upper", r -> r.host("*.rewriteresponseupper.org")
            .filters(f -> f.prefixPath("/httpbin")
                .modifyResponseBody(String.class, String.class,
                    (exchange, s) -> Mono.just(s.toUpperCase()))).uri(uri))
        .build();
}

如果响应没有正文，则将 . 应返回以在响应中分配缺少的正文。RewriteFilternullMono.empty()

6.30. 令牌中继 `GatewayFilter` 工厂

令牌中继是 OAuth2 使用者充当客户端的地方，而将传入令牌转发到传出资源请求。这 consumer 可以是纯 Client（如 SSO 应用程序）或 Resource 服务器。spring-doc.cn

Spring Cloud 网关可以将 OAuth2 访问令牌下游转发到服务它是代理。要将此功能添加到 gateway，您需要添加如下内容：TokenRelayGatewayFilterFactoryspring-doc.cn

App.java

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
            .route("resource", r -> r.path("/resource")
                    .filters(f -> f.tokenRelay())
                    .uri("http://localhost:9000"))
            .build();
}

或者这个spring-doc.cn

应用程序.yaml

spring:
  cloud:
    gateway:
      routes:
      - id: resource
        uri: http://localhost:9000
        predicates:
        - Path=/resource
        filters:
        - TokenRelay=

它会（除了登录用户和获取令牌之外）将身份验证令牌下游传递给服务（在本例中）。/resourcespring-doc.cn

要为 Spring Cloud 网关启用此功能，请添加以下依赖项spring-doc.cn

org.springframework.boot:spring-boot-starter-oauth2-clientspring-doc.cn

它是如何工作的？这 {githubmaster}/src/main/java/org/springframework/cloud/gateway/security/TokenRelayGatewayFilterFactory.java[过滤器] 从当前经过身份验证的用户中提取访问令牌，并将其放入下游请求的请求标头中。spring-doc.cn

有关完整的工作示例，请参阅此项目。spring-doc.cn

只有在设置了适当的属性时，才会创建 Bean，这将触发 Bean 的创建。TokenRelayGatewayFilterFactoryspring.security.oauth2.client.*ReactiveClientRegistrationRepository

的默认实现 used by 使用内存中数据存储。如果您需要更强大的解决方案，则需要提供自己的实现。ReactiveOAuth2AuthorizedClientServiceTokenRelayGatewayFilterFactoryReactiveOAuth2AuthorizedClientService

6.31. 默认过滤器

要添加筛选条件并将其应用于所有路由，您可以使用 . 此属性采用筛选器列表。下面的清单定义了一组默认过滤器：spring.cloud.gateway.default-filtersspring-doc.cn

例 55.application.yml

spring:
  cloud:
    gateway:
      default-filters:
      - AddResponseHeader=X-Response-Default-Red, Default-Blue
      - PrefixPath=/httpbin