Spring Cloud GateWay（4.1.4）

介绍

该项目提供了一个建立在 Spring 生态系统之上的 API 网关，包括：Spring 6、Spring Boot 3 和 Project Reactor。Spring Cloud Gateway 旨在提供一种简单而有效的方法来路由到 API，并为其提供跨领域关注点，例如：安全性、监控/指标和弹性。

Spring Cloud Gateway 有两种不同的版本：服务器和代理交换。每种风格都提供 WebFlux 和 MVC 兼容性。

Server 变体是一个功能齐全的 API 网关，可以独立使用，也可以嵌入到 Spring Boot 应用程序中。
Proxy Exchange 变体专门用于基于注释的 WebFlux 或 MVC 应用程序，并允许使用特殊 ProxyExchange 对象作为 Web 处理程序方法的参数。

Spring Cloud Gateway Reactive Server

引入 Spring Cloud Gateway

若要在项目中包含 Spring Cloud Gateway，请使用组 ID 为且 org.springframework.cloud 工件 ID 为 spring-cloud-starter-gateway 的启动器。有关使用当前 Spring Cloud 发布系列设置构建系统的详细信息，请参阅 Spring Cloud 项目页面。

如果包含启动器，但不希望启用网关，请设置 spring.cloud.gateway.enabled=false 。

Spring Cloud Gateway 基于 Spring Boot、Spring WebFlux 和 Project Reactor 构建。因此，当您使用 Spring Cloud Gateway 时，许多熟悉的同步库（例如 Spring Data 和 Spring Security）和模式可能不适用。如果你不熟悉这些项目，我们建议你在使用 Spring Cloud Gateway 之前先阅读他们的文档，以熟悉一些新概念。

Spring Cloud Gateway 需要 Spring Boot 和 Spring Webflux 提供的 Netty 运行时。它不能在传统的 Servlet 容器中工作，也不能在作为 WAR 构建时工作。

Glossary（核心）

路由：网关的基本构建块。它由 ID、目标 URI、谓词集合和筛选器集合定义。如果聚合断言为 true，则匹配路由。
断言：这是一个 Java 8 函数断言。输入类型是 Spring Framework ServerWebExchange 。这使您可以匹配 HTTP 请求中的任何内容，例如标头或参数。
筛选器：这些是使用特定工厂构建的 GatewayFilter 实例。在这里，您可以在发送下游请求之前或之后修改请求和响应。

总结

web前端请求，通过一些匹配条件，定位到真正的服务节点。并在这个转发过程的前后，进行一些精细化控制。

predicate就是我们的匹配条件；

filter，就可以理解为一个无所不能的拦截器。有了这两个元素，再加上目标uri，就可以实现一个具体的路由

如何工作

下图提供了 Spring Cloud Gateway 工作原理的高级概述：

客户端向 Spring Cloud Gateway 发出请求。如果网关处理程序映射确定请求与路由匹配，则该请求将发送到网关 Web 处理程序。此处理程序通过特定于请求的筛选器链运行请求。筛选器被虚线分隔的原因是，筛选器可以在发送代理请求之前和之后运行逻辑。执行所有“pre”过滤器逻辑。然后发出代理请求。发出代理请求后，将运行“post”筛选器逻辑。

配置路由断言工厂和网关筛选器工厂

快捷方式配置

spring:
  cloud:
    gateway:
      routes:
      - id: after_route
        uri: https://example.org
        predicates:
        - Cookie=mycookie,mycookievalue

前面的示例使用两个参数定义 Cookie 路由断言工厂：cookie 名称 mycookie 和要匹配 mycookievalue 的值。

完全展开的参数

完全扩展的参数看起来更像是具有名称/值对的标准 yaml 配置。通常，会有一个 name 密钥和一个 args 密钥。 args 键是键值对的映射，用于配置断言或筛选器。

spring:
  cloud:
    gateway:
      routes:
      - id: after_route
        uri: https://example.org
        predicates:
        - name: Cookie
          args:
            name: mycookie
            regexp: mycookievalue

路由断言工厂

Spring Cloud Gateway 将路由作为 Spring WebFlux HandlerMapping 基础结构的一部分进行匹配。Spring Cloud Gateway 包含许多内置的路由断言工厂。所有这些断言都与 HTTP 请求的不同属性匹配。您可以将多个路由断言工厂与逻辑 and 语句组合在一起。

After/Before Route 断言工厂

After 路由断言工厂采用一个参数 a datetime （即 java ZonedDateTime ）。此断言匹配在指定日期时间之后发生的请求。

Before 路由断言工厂采用一个参数 a datetime （即 java ZonedDateTime ）。此断言匹配在指定的 datetime .以下示例配置 before route 断言：

spring:
  cloud:
    gateway:
      routes:
      - id: after_route
        uri: https://example.org
        predicates:
        - After=2017-01-20T17:42:47.789-07:00[America/Denver]

此路线符合 2017 年 1 月 20 日 17：42 Mountain Time （Denver）之前提出的任何请求。

spring:
  cloud:
    gateway:
      routes:
      - id: before_route
        uri: https://example.org
        predicates:
        - Before=2017-01-20T17:42:47.789-07:00[America/Denver]

此路线符合 2017 年 1 月 20 日 17：42 Mountain Time （Denver）之前提出的任何请求。

路由间断言工厂（between）

Between 路由断言工厂采用两个参数， datetime1 datetime2 它们是 java ZonedDateTime 对象。此断言匹配在 datetime1 之后和之前 datetime2 发生的请求。该 datetime2 参数必须位于 datetime1 之后。以下示例配置 between route 断言：

spring:
  cloud:
    gateway:
      routes:
      - id: between_route
        uri: https://example.org
        predicates:
        - Between=2017-01-20T17:42:47.789-07:00[America/Denver], 2017-01-21T17:42:47.789-07:00[America/Denver]

此路线符合 2017 年 1 月 20 日 17：42 山地时间（丹佛）之后和 2017 年 1 月 21 日 17：42 山地时间（丹佛）之前提出的任何请求。这对于维护时段可能很有用。

Cookie 路由断言工厂采用两个参数，cookie name 和 a regexp （Java 正则表达式）。此断言匹配具有给定名称且其值与正则表达式匹配的 cookie。以下示例配置 cookie 路由断言工厂：

spring:
  cloud:
    gateway:
      routes:
      - id: cookie_route
        uri: https://example.org
        predicates:
        - Cookie=chocolate, ch.p

此路由匹配具有名为 chocolate cookie 的请求，其值与 ch.p 正则表达式匹配。

标头路由断言工厂

Header 路由断言工厂采用两个参数，即和 header a regexp （这是一个 Java 正则表达式）。此断言与具有给定名称的标头匹配，其值与正则表达式匹配。以下示例配置标头路由断言：

spring:
  cloud:
    gateway:
      routes:
      - id: header_route
        uri: https://example.org
        predicates:
        - Header=X-Request-Id, \d+

如果请求具有名为 X-Request-Id 其值与 \d+ 正则表达式匹配的标头（即，它的值为一位或多位），则此路由匹配。

主机路由断言工厂

Host 路由断言工厂采用一个参数：主机名 patterns 列表。该图案是蚂 . 蚁风格的图案，作为分隔符。此断言与 Host 与模式匹配的标头匹配。以下示例配置主机路由断言：

spring:
  cloud:
    gateway:
      routes:
      - id: host_route
        uri: https://example.org
        predicates:
        - Host=**.somehost.org,**.anotherhost.org

还支持 URI 模板变量（如 {sub}.myhost.org ）。

如果请求的 Host 标头值为 www.somehost.org or beta.somehost.org 或 www.anotherhost.org ，则此路由匹配。

此谓词将 URI 模板变量（如 sub 前面示例中定义的）提取为名称和值的映射，并将其 ServerWebExchange.getAttributes() 放在中，并使用中 ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE 定义的键。然后， GatewayFilter 这些值可供工厂使用

方法路由断言工厂

The Method Route Predicate Factory takes a methods argument which is one or more parameters: the HTTP methods to match. The following example configures a method route predicate:
Method 路由断言工厂采用一个 methods 参数，该参数是一个或多个参数：要匹配的 HTTP 方法。下面的示例配置方法路由断言：

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: method_route
        uri: https://example.org
        predicates:
        - Method=GET,POST

Copied!
如果请求方法是 a GET 或 . POST

路径路由断言工厂

Path 路由断言工厂采用两个参数：Spring PathMatcher patterns 列表和名为 matchTrailingSlash （默认为 true ）的可选标志。以下示例配置路径路由断言：

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: path_route
        uri: https://example.org
        predicates:
        - Path=/red/{segment},/blue/{segment}

Copied!

如果请求路径为，则此路由匹配，例如： /red/1 或 /red/1/ 或 /red/blue /blue/green 或。

如果 matchTrailingSlash 设置为 false ，则请求路径 /red/1/ 将不匹配。

此谓词将 URI 模板变量（如 segment 前面示例中定义的）提取为名称和值的映射，并将其 ServerWebExchange.getAttributes() 放在中，并使用中 ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE 定义的键。然后， GatewayFilter 这些值可供工厂使用

可以使用实用程序方法（称为 get ）来更轻松地访问这些变量。下面的示例演示如何使用该 get 方法：

Map<String, String> uriVariables = ServerWebExchangeUtils.getUriTemplateVariables(exchange);

String segment = uriVariables.get("segment");

Copied!
查询路由谓词工厂

Query 路由断言工厂采用两个参数：必需 param 参数和可选参数 regexp （Java 正则表达式）。以下示例配置查询路由断言：

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: query_route
        uri: https://example.org
        predicates:
        - Query=green

Copied!
如果请求包含 green 查询参数，则上述路由匹配。

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: query_route
        uri: https://example.org
        predicates:
        - Query=red, gree.

如果请求包含的 red 查询参数的值与 gree. 正则表达式匹配，则上述路由匹配，因此 green 和 greet 将匹配。

RemoteAddr 路由断言工厂

RemoteAddr 路由断言工厂采用 sources 的列表（最小大小为 1），这些列表是 CIDR 表示法（IPv4 或 IPv6）字符串，例如 192.168.0.1/16 （where 192.168.0.1 是 IP 地址， 16 是子网掩码）。以下示例配置 RemoteAddr 路由断言：

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: remoteaddr_route
        uri: https://example.org
        predicates:
        - RemoteAddr=192.168.1.1/24

Copied
如果请求的远程地址为，则此路由匹配 192.168.1.10 ，例如。

`GatewayFilter` 工厂

路由过滤器允许以某种方式修改传入的 HTTP 请求或传出的 HTTP 响应。路由筛选器的作用域为特定路由。Spring Cloud Gateway 包含许多内置的 GatewayFilter 工厂。

`AddRequestHeader`

AddRequestHeader GatewayFilter 工厂采用 name - value 参数。以下示例配置： AddRequestHeader GatewayFilter

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

此列表将标头添加到 X-Request-red:blue 所有匹配请求的下游请求的标头中。

AddRequestHeader 知道用于匹配路径或主机的 URI 变量。URI 变量可以在值中使用，并在运行时展开。以下示例配置一个 AddRequestHeader GatewayFilter 使用变量的变量：

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

`RemoveRequestHeader` GatewayFilter 工厂

RemoveRequestHeader GatewayFilter 工厂采用一个 name 参数。它是要删除的标头的名称。以下列表配置： RemoveRequestHeader GatewayFilter

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

这将在标 X-Request-Foo 头发送到下游之前将其删除。

AddRequestHeadersIfNotPresent

AddRequestHeadersIfNotPresent GatewayFilter Factory :: Spring Cloud Gateway

此列表为所有匹配请求添加 2 个标头 X-Request-Color-1:blue 和 X-Request-Color-2:green 下游请求的标头。这与工作方式 AddRequestHeader 类似，但与它不同的 AddRequestHeader 是，只有在标头不存在时才会这样做。否则，将发送客户端请求中的原始值。

`AddRequestParameter`

AddRequestParameter GatewayFilter Factory :: Spring Cloud Gateway

`AddResponseHeader`

AddResponseHeader GatewayFilter Factory :: Spring Cloud Gateway

其余参考官网：GatewayFilter Factories :: Spring Cloud Gateway

全局筛选器

该 GlobalFilter 接口具有与 GatewayFilter 相同的签名。这些是有条件地应用于所有路由的特殊过滤器。

组合全局筛选和 `GatewayFilter` 排序

当请求与路由匹配时，筛选 Web 处理程序会 GatewayFilter 将的所有 GlobalFilter 实例和所有特定于路由的实例添加到筛选器链中。此组合筛选器链按 org.springframework.core.Ordered 接口排序，您可以通过实现 getOrder() 该方法进行设置。

由于Spring Cloud Gateway区分了过滤器逻辑执行的“pre”和“post”阶段（请参阅工作原理），因此优先级最高的过滤器是“pre”阶段的第一个，最后一个是“post”阶段的最后一个。

@Bean
public GlobalFilter customFilter() {
    return new CustomGlobalFilter();
}

public class CustomGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        log.info("custom global filter");
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -1;
    }
}

网关指标筛选器（查看网关运行情况）

要启用网关指标，请添加 spring-boot-starter-actuator 为项目依赖项。然后，默认情况下， spring.cloud.gateway.metrics.enabled 该属性为 true ，网关指标筛选器就会运行。此筛选器添加一个以以下标签命名 spring.cloud.gateway.requests 的计时器指标：

routeId ：路由 ID。
routeUri ：API 路由到的 URI。
outcome ：按 HttpStatus.Series 分类的结果。
status ：返回客户端的请求的 HTTP 状态。
httpStatusCode ：返回给客户端的请求的 HTTP 状态。
httpMethod ：用于请求的 HTTP 方法。

然后，可以从中抓取这些指标， /actuator/metrics/spring.cloud.gateway.requests 并可以轻松地与 Prometheus 集成以创建 Grafana 仪表板。

本地缓存过滤器

如果启用了关联属性，则 LocalResponseCache 运行：

spring.cloud.gateway.global-filter.local-response-cache.enabled ：激活所有路由的全局缓存
spring.cloud.gateway.filter.local-response-cache.enabled ：激活关联的过滤器以在路由级别使用

此功能为满足以下条件的所有响应启用使用 Caffeine 的本地缓存：

该请求是无体 GET。
响应具有以下状态代码之一：HTTP 200（确定）、HTTP 206（部分内容）或 HTTP 301（永久移动）。
HTTP Cache-Control 标头允许缓存（这意味着它不具有以下任何值： no-store 存在于请求中和 no-store /或 private 存在于响应中）。

它接受两个配置参数：

spring.cloud.gateway.filter.local-response-cache.size ：设置缓存的最大大小以逐出此路由的条目（以 KB、MB 和 GB 为单位）。
spring.cloud.gateway.filter.local-response-cache.time-to-live 设置缓存条目的过期时间（以 s 表示秒，m 表示分钟，h 表示小时）。

如果未配置这些参数，但启用了全局筛选器，则默认情况下，它会为缓存的响应配置 5 分钟的生存时间。

此筛选器还实现 HTTP Cache-Control 标头中值 max-age 的自动计算。如果 max-age 原始响应中存在该值，则使用 timeToLive 配置参数中设置的秒数重写该值。在后续调用中，此值将使用响应过期前的剩余秒数重新计算。
spring.cloud.gateway.global-filter.local-response-cache.enabled 设置为 false 停用所有路由的本地响应缓存，LocalResponseCache 筛选器允许在路由级别使用此功能。