gateway的基础应用

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

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

spring:
  cloud:
    gateway:
      routes:
      - id: add_request_headers_route
        uri: https://example.org
        filters:
        - AddRequestHeadersIfNotPresent=X-Request-Color-1:blue,X-Request-Color-2:green

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

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

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

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

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

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 # 可选路径重写

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("cache_request_body_route", r -> r.path("/downstream/**")
            .filters(f -> f.prefixPath("/httpbin")
                .cacheRequestBody(String.class).uri(uri))
        .build();
}

spring:
  cloud:
    gateway:
      routes:
      - id: cache_request_body_route
        uri: lb://downstream
        predicates:
        - Path=/downstream/**
        filters:
        - name: CacheRequestBody
          args:
            bodyClass: java.lang.String # 请求体转换的目标类

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

RETAIN_FIRST：保留第一个值（默认）

RETAIN_LAST：保留最后一个值

RETAIN_UNIQUE：保留所有唯一值（按首次出现的顺序）

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 # 自定义头名称 (可选)

executionExceptionTypeHeaderName ("Execution-Exception-Type")

executionExceptionMessageHeaderName ("Execution-Exception-Message")

rootCauseExceptionTypeHeaderName ("Root-Cause-Exception-Type")

rootCauseExceptionMessageHeaderName ("Root-Cause-Exception-Message")

protoDescriptor: Proto 描述符文件 (.pb 文件)。

protoFile: Proto 定义文件 (.proto 文件)。

service: 处理请求的服务的简称。

method: 服务中处理请求的方法名。

不支持流式传输 (streaming is not supported)。

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
            .route("json-grpc", r -> r.path("/json/hello").filters(f -> {
                String protoDescriptor = "file:src/main/proto/hello.pb";
                String protoFile = "file:src/main/proto/hello.proto";
                String service = "HelloService";
                String method = "hello";
                return f.jsonToGRPC(protoDescriptor, protoFile, service, method);
            }).uri(uri))

spring:
  cloud:
    gateway:
      routes:
        - id: json-grpc
          uri: https://localhost:6565/testhello
          predicates:
            - Path=/json/**
          filters:
            - name: JsonToGrpc
              args:
                protoDescriptor: file:proto/hello.pb
                protoFile: file:proto/hello.proto
                service: HelloService
                method: hello

只能缓存无请求体 (bodiless) 的 GET 请求。

仅缓存以下状态码之一的响应：HTTP 200 (OK)、HTTP 206 (Partial Content) 或 HTTP 301 (Moved Permanently)

如果 Cache-Control 头部不允许缓存（请求中存在 no-store 或响应中存在 no-store 或 private），则不会缓存响应数据。

如果响应已被缓存，并且使用 Cache-Control 头部值为 no-cache 的新请求执行，它将返回一个无响应体的 304 (Not Modified) 响应。

仅在 spring.cloud.gateway.filter.local-response-cache.enabled 属性启用时才可用

第一个参数来覆盖缓存条目的过期时间（以 s 表示秒，m 表示分钟，h 表示小时）

第二个参数设置此路由缓存的最大大小（KB、MB 或 GB）

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("rewrite_response_upper", r -> r.host("*.rewriteresponseupper.org")
            .filters(f -> f.prefixPath("/httpbin")
                .localResponseCache(Duration.ofMinutes(30), "500MB") // 缓存30分钟，最大500MB
            ).uri(uri))
        .build();
}

spring:
  cloud:
    gateway:
      routes:
      - id: resource
        uri: http://localhost:9000
        predicates:
        - Path=/resource
        filters:
        - LocalResponseCache=30m,500MB # 缓存30分钟，最大500MB

如果输入头部不存在，则此过滤器不起作用。如果新的命名头部已存在，则其值将用新值进行扩充

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

@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) -> 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;
    }
}

@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();
}

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

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

status 参数：应该是一个 300 系列的重定向 HTTP 状态码，例如 301。

url 参数：应该是一个有效的 URL。这将作为 Location 响应头的值。

includeRequestParams 参数（可选）：指示是否应将原始请求的查询参数包含在重定向的 url 中。如果未设置此参数，则默认为 false。

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

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

该列表中的最后一个参数可以是可选的布尔值，
用于指定是仅删除根级别的属性（这是参数配置末尾
不提供此选项时的默认值 false），
还是递归删除所有级别的属性（true）

spring:
  cloud:
    gateway:
      routes:
      - id: removejsonattributes_route
        uri: https://example.org
        filters:
        - RemoveJsonAttributesResponseBody=id,color

spring:
  cloud:
    gateway:
      routes:
      - id: removejsonattributes_recursively_route
        uri: https://example.org
        predicates:
        - Path=/red/{segment}
        filters:
        - RemoveJsonAttributesResponseBody=id,color,true # 注意结尾的 ",true" 参数

spring:
  cloud:
    gateway:
      routes:
      - id: removerequestheader_route # 路由ID
        uri: https://example.org      # 目标URI
        filters:
        - RemoveRequestHeader=X-Request-Foo # 过滤器：移除指定请求头

spring:
  cloud:
    gateway:
      routes:
      - id: removerequestparameter_route # 路由ID
        uri: https://example.org        # 目标URI
        filters:
        - RemoveRequestParameter=red    # 过滤器：移除指定查询参数

spring:
  cloud:
    gateway:
      routes:
      - id: removeresponseheader_route # 路由ID
        uri: https://example.org       # 目标URI (下游服务)
        filters:
        - RemoveResponseHeader=X-Response-Foo # 过滤器：移除指定响应头

为任何可能需要此操作的路由配置此过滤器。

此外，您还可以使用 spring.cloud.gateway.default-filters 一次性配置此过滤器，使其应用于所有路由。

maxSize 参数：请求头（包括键名和键值）所允许的最大数据大小。

errorHeaderName 参数（可选）：设置响应头中包含错误消息的头名称。默认值为 "errorMessage"。

spring:
  cloud:
    gateway:
      routes:
      - id: requestheadersize_route # 路由ID
        uri: https://example.org     # 目标URI (下游服务)
        filters:
        - RequestHeaderSize=1000B    # 过滤器：设置最大请求头大小为1000字节

超过速率的话：返回 HTTP 429 - Too Many Requests (请求过多) 状态码

keyResolver

基于 Stripe 完成的工作。它需要使用
spring-boot-starter-data-redis-reactive

令牌桶算法
Token Bucket Algorithm

示例
此配置定义了每个用户 10 个请求/秒的速率限制。允许突发 20 个请求，但在下一秒，只有 10 个请求可用。上面示例中的 KeyResolver 是一个简单的解析器，它获取 user 请求参数（注意：这不建议用于生产环境）。

基于 Bucket4j Java 库。它需要使用 com.bucket4j:bucket4j_jdk17-core 依赖项以及一个分布式持久化选项

示例
每个用户 10 个请求/秒的速率限制。允许突发 20 个请求，但在下一秒，只有 10 个请求可用。
注意：示例中的 KeyResolver 不建议用于生产环境

您也可以将速率限制器定义为实现 RateLimiter 接口的 Bean。在配置中，您可以使用 SpEL 通过名称引用该 Bean。#{@myRateLimiter} 是一个 SpEL 表达式，它引用名为 myRateLimiter 的 Bean。

示例

当后端服务返回带有 Location 头的响应时（通常是重定向场景），此过滤器用于重写该 Location URL，使其去除后端特定的细节（如内部主机名、版本号），使其成为面向客户端的有效 URL。

Mode
模式

ocationHeaderName
位置头名称

hostValue
主机值

protocols
协议

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

path regexp
路径正则表达式

replacement
替换值

spring:
  cloud:
    gateway:
      routes:
      - id: rewritepath_route       # 路由ID
        uri: https://example.org     # 目标URI (下游服务)
        predicates:
        - Path=/red/**              # 只匹配以 /red/ 开头的路径
        filters:
        - RewritePath=/red/?(?<segment>.*), /$\{segment} # 重写路径过滤器

name（第一个参数）： 指定要重写的请求参数的名称**（例如 campaign）

replacement（第二个参数）： 指定新的参数值**（例如 fall2023）

同名参数的场景： 如果有多个具有相同名称的请求参数，过滤器会将它们全部替换为一个单一的参数，其值为指定的 replacement。

参数不存在的场景： 如果在请求中找不到指定名称的请求参数，过滤器不会做任何更改。

spring:
  cloud:
    gateway:
      routes:
      - id: rewriterequestparameter_route # 路由ID
        uri: https://example.org          # 目标URI (下游服务)
        predicates:
        - Path=/products                  # 匹配路径 /products
        filters:
        - RewriteRequestParameter=campaign,fall2023 # 重写请求参数：将 campaign 的值设为 fall2023

name（第一个参数）： 指定要重写的响应头的名称**（例如 X-Response-Red）

regexp（第二个参数）： 一个 Java 正则表达式字符串。这个正则表达式将用于匹配**原始响应头值中需要被替换的部分。

replacement（第三个参数）： 用于替换被 regexp 匹配到的部分的字符串

spring:
  cloud:
    gateway:
      routes:
      - id: rewriteresponseheader_route
        uri: https://example.org
        filters:
        - RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=*** # 重写响应头过滤器

在 replacement 参数中，如果你想表示正则捕获组的引用（如 $1, $2 等）或文字 $ 字符，在 YAML 中必须使用 $\ 来表示 $。这是由 YAML 规范决定的（$ 在 YAML 中是变量标识符的特殊字符，需要转义）。

全局配置

路由级配置

禁用 (disable): 指定不添加哪些安全头部（使用小写全名）

自定义值： 通过属性覆盖特定安全头部的默认值。

启用额外头部 (enable): 如 permissions-policy。

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

使用 Spring Framework 的 URI 模板语法 ({variableName})，支持更复杂的模板，例如 /newpath/{var1}/sub/{var2}。只要 Path 断言定义的路径中包含相应的变量，这些变量就能在 SetPath 的模板中被使用。

name: 要设置/覆盖的 HTTP 请求头的名称 (例如 X-Request-Red, Authorization, foo）

value: 要设置的值 (例如 Blue, Bearer someToken, bar-{segment})

替换而非添加： 如果请求中已存在同名头，过滤器会删除所有现有的值并用配置的值覆盖它。

如果不存在： 如果请求中不存在该头，过滤器会添加这个请求头。

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

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

name: 要设置/覆盖的 HTTP 响应头的名称 (例如 X-Response-Red, Cache-Control, foo）。

value: 要设置的值 (例如 Blue, max-age=3600, bar-{segment})。

替换而非添加： 如果下游服务的响应中已存在同名头，过滤器会删除所有现有的值并用配置的值覆盖它。

如果不存在： 如果下游服务的响应中不存在该头，过滤器会添加这个响应头。

修改点： 在网关接收到下游服务的响应之后，发送给最终客户端之前。

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

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

status: 要设置的 HTTP 状态码。接受：

两种形式的效果相同：将响应的状态码设置为指定的值。

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

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

parts: 需要从路径开头移除的段（segment）的数量。路径段是由斜杠 / 分隔的部分。

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

retries 重试次数（默认 3 次）

statuses 触发重试的 HTTP 状态码（如 BAD_GATEWAY）

methods 触发重试的 HTTP 方法（如 GET, POST）

exceptions 触发重试的异常（默认 IOException, TimeoutException）

backoff 指数退避策略

jitter 随机抖动：

timeout 重试操作超时时间（默认无限制）

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
            jitter:
              randomFactor: 0.5      # 抖动因子 (50%)
            timeout: 100ms           # 超时时间

spring:
  cloud:
    gateway:
      routes:
      - id: retry_route
        uri: https://example.org
        filters:
        - name: Retry      #完整 YAML 配置
          args:
            retries: 3
            statuses: INTERNAL_SERVER_ERROR
            methods: GET
            backoff:
              firstBackoff: 10ms
              maxBackoff: 50ms
              factor: 2
              basedOnPreviousValue: false
            jitter:
              randomFactor: 0.5
            timeout: 100ms
#快捷语法（参数顺序固定）
      - id: retryshortcut_route
        uri: https://example.org
        filters:
        - Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false,0.5,100ms  #快捷语法（参数顺序固定）

forward: 端点约束

下游过滤器影响

请求体缓存风险

类型为 DataSize

值可以定义为一个数字，后跟一个可选的 DataUnit 后缀，例如 'KB'（千字节）或 'MB'（兆字节）。

默认单位为 'B'（字节）。

它表示允许的请求大小限制（以字节为单位）。

spring:
  cloud:
    gateway:
      routes:
      - id: request_size_route        # 路由ID
        uri: http://localhost:8080/upload  # 目标服务地址
        predicates:
        - Path=/upload                # 匹配路径为 /upload 的请求
        filters:
        - name: RequestSize           # 过滤器名称
          args:
            maxSize: 5000000          # 最大允许请求大小为 5,000,000 字节 (5 MB)

直接拒绝请求，不转发至下游。

返回 HTTP 状态码 **413 Payload Too Large**。

在响应头 **errorMessage** 中提供详细的错误信息（当前请求大小和允许的限制）。

想要设置的新 Host 头的值 (字符串类型，例如 "example.org", "api.service.com:8080")

spring:
  cloud:
    gateway:
      routes:
      - id: set_request_host_header_route  # 路由 ID
        uri: http://localhost:8080/headers # 目标服务地址
        predicates:
        - Path=/headers                     # 匹配路径为 /headers 的请求
        filters:
        - name: SetRequestHostHeader        # 过滤器名称
          args:
            host: example.org               # 要设置的 Host 头新值

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

TokenRelay GatewayFilter 使得 Spring Cloud Gateway 能够透明地将 OAuth2 访问令牌从客户端传播到下游服务，是实现 API 网关安全令牌中继的核心组件。它支持两种模式：使用特定客户端配置获取令牌，或直接传递当前登录用户的令牌。使用时必须确保正确配置了 OAuth2 客户端依赖和属性，并了解其默认内存存储的限制，为生产环境评估存储需求。

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

spring:
  cloud:
    gateway:
      routes:
      - id: resource
        uri: http://localhost:9000   # 目标服务
        predicates:
        - Path=/resource            # 匹配路径
        filters:
        - TokenRelay=myregistrationid # 指定 clientRegistrationId

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
            .route("resource", r -> r.path("/resource")
                    .filters(f -> f.tokenRelay()) // 不指定 clientRegistrationId，使用当前用户的登录令牌
                    .uri("http://localhost:9000"))
            .build();
}

spring:
  cloud:
    gateway:
      routes:
      - id: resource
        uri: http://localhost:9000
        predicates:
        - Path=/resource
        filters:
        - TokenRelay= # 空参数表示使用当前用户的令牌 (或者直接写 - TokenRelay)

该过滤器会从当前已认证用户的安全上下文中提取 OAuth2 访问令牌。

如果配置了 clientRegistrationId 参数，它会尝试获取与该特定客户端注册相关的访问令牌。

如果省略了 clientRegistrationId 参数，它会尝试获取当前已登录用户自身的访问令牌（通常是在用户通过网关进行 oauth2Login() 登录时获得的）。

无论使用哪种方式，过滤器都会将提取到的访问令牌放入向下游服务发送的 HTTP 请求的 Authorization 头 (通常形如 Bearer <token>) 中。

创建条件： TokenRelayGatewayFilterFactory 这个 Bean 仅在配置了正确的 OAuth2 客户端属性时才会被创建。这些属性 (spring.security.oauth2.client.*) 会触发创建 ReactiveClientRegistrationRepository Bean（存储客户端注册信息）。

默认存储方式： TokenRelayGatewayFilterFactory 使用的默认 ReactiveOAuth2AuthorizedClientService 实现是一个 内存存储 (in-memory data store)。

生产环境存储： 如果你需要一个更健壮的解决方案（例如支持集群部署、持久化存储授权状态），你需要提供 自定义的 ReactiveOAuth2AuthorizedClientService 实现 (例如基于 Redis 或数据库的实现)。