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_routeuri: https://example.orgpredicates:- Cookie=mycookie,mycookievalue

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

完全展开的参数

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

spring:cloud:gateway:routes:- id: after_routeuri: https://example.orgpredicates:- name: Cookieargs:name: mycookieregexp: 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_routeuri: https://example.orgpredicates:- 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_routeuri: https://example.orgpredicates:- 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_routeuri: https://example.orgpredicates:- 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 路由断言工厂采用两个参数，cookie name 和 a regexp （Java 正则表达式）。此断言匹配具有给定名称且其值与正则表达式匹配的 cookie。以下示例配置 cookie 路由断言工厂：

spring:cloud:gateway:routes:- id: cookie_routeuri: https://example.orgpredicates:- Cookie=chocolate, ch.p

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

标头路由断言工厂

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

spring:cloud:gateway:routes:- id: header_routeuri: https://example.orgpredicates:- Header=X-Request-Id, \d+

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

主机路由断言工厂

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

spring:cloud:gateway:routes:- id: host_routeuri: https://example.orgpredicates:- 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_routeuri: https://example.orgpredicates:- Method=GET,POST

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

路径路由断言工厂

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

application.yml

spring:cloud:gateway:routes:- id: path_routeuri: https://example.orgpredicates:- 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_routeuri: https://example.orgpredicates:- Query=green

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

application.yml

spring:cloud:gateway:routes:- id: query_routeuri: https://example.orgpredicates:- 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_routeuri: https://example.orgpredicates:- 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_routeuri: https://example.orgfilters:- AddRequestHeader=X-Request-red, blue

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

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

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

RemoveRequestHeader GatewayFilter 工厂

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

spring:cloud:gateway:routes:- id: removerequestheader_routeuri: https://example.orgfilters:- 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 {@Overridepublic Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {log.info("custom global filter");return chain.filter(exchange);}@Overridepublic 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 筛选器允许在路由级别使用此功能。