网关处理程序过滤器函数

DeepSeek V3 中英对照 Gateway Handler Filter Functions

Before Filter 函数

WebMvc.fn API 中有一个“before”过滤器函数的概念，它是一个 java.util.Function<ServerRequest, ServerRequest>，仅对请求进行操作。许多 before 过滤器函数在 org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions 中作为静态工厂方法被引用。它们在 org.springframework.cloud.gateway.server.mvc.filter.FilterFunctions 中被适配为通用的 org.springframework.web.servlet.function.HandlerFilterFunction<ServerResponse, ServerResponse>。两者都可以使用，但在可能的情况下，更推荐使用更具体的 BeforeFilterFunctions，因为它更加明确。

筛选后函数

WebMvc.fn API 中有一个“after”过滤器函数的概念，它是一个 java.util.BiFunction<ServerRequest, ServerResponse, ServerResponse>，可以修改响应。许多 after 过滤器函数在 org.springframework.cloud.gateway.server.mvc.filter.AfterFilterFunctions 中被引用为静态工厂方法。它们在 org.springframework.cloud.gateway.server.mvc.filter.FilterFunctions 中被适配为通用的 org.springframework.web.servlet.function.HandlerFilterFunction<ServerResponse, ServerResponse>。两者都可以使用，但在可能的情况下，更推荐使用更具体的 AfterFilterFunctions，因为它更明确。

高级过滤函数

有些过滤器不能简单地归类为前置或后置过滤器。这些过滤器在代理请求之前和之后都会起作用。其中包括位于 BodyFilterFunctions、Bucket4jFilterFunctions、CircuitBreakerFilterFunctions、LoadBalancerFilterFunctions、RetryFilterFunctions 和 TokenRelayFilterFunctions 中的过滤器，它们都位于 org.springframework.cloud.gateway.server.mvc.filter 包中。

章节总结

📄️ AddRequestHeader 过滤器

AddRequestHeader 是一个 \"before\" 过滤器，它接受一个名称和值参数。以下示例配置了一个 AddRequestHeader 过滤器：

📄️ AddRequestHeadersIfNotPresent 过滤器

AddRequestHeadersIfNotPresent 过滤器接受一个由冒号分隔的名称和值对的集合。以下示例配置了一个 AddRequestHeadersIfNotPresent 过滤器：

📄️ AddRequestParameter 过滤器

AddRequestParameter 过滤器需要一个名称和值参数。以下示例配置了一个 AddRequestParameter 过滤器：

📄️ AddResponseHeader 过滤器

AddResponseHeader 过滤器需要一个名称和值参数。以下示例配置了一个 AddResponseHeader 过滤器：

📄️ CircuitBreaker 过滤器

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

📄️ DedupeResponseHeader 过滤器

DedupeResponseHeader GatewayFilter 工厂接收一个 name 参数和一个可选的 strategy 参数。name 可以包含一个由空格分隔的头部名称列表。以下示例配置了一个 DedupeResponseHeader 过滤器：

📄️ FallbackHeaders 过滤器

FallbackHeaders 工厂允许你在转发到外部应用程序的 fallbackUri 的请求头中添加 Spring Cloud CircuitBreaker 执行异常详细信息，如下所示：

📄️ 负载均衡器筛选器

负载均衡器过滤器（LoadBalancer Filter）接受一个 serviceId 参数。LoadBalancerClient 使用该参数来选择用于路由的实例。在 Java DSL 中，需要显式使用负载均衡器过滤器。使用负载均衡器过滤器时，请在 org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions 中使用空的 http() 方法。

📄️ MapRequestHeader 过滤器

MapRequestHeader 过滤器接收 fromHeader 和 toHeader 参数。它会创建一个新的命名头部（toHeader），并从传入的 HTTP 请求中的现有命名头部（fromHeader）中提取值。如果输入的头部不存在，过滤器将不会产生任何影响。如果新的命名头部已经存在，其值将与新值合并。以下示例配置了一个 MapRequestHeader：

📄️ 修改请求体过滤器

你可以使用 ModifyRequestBody 过滤器在网关将请求体发送到下游之前对其进行修改。

📄️ ModifyResponseBody 过滤器

你可以使用 ModifyResponseBody 过滤器在响应发送回客户端之前修改响应体。

📄️ PrefixPath 过滤器

PrefixPath 过滤器接受一个前缀参数。以下示例配置了一个 PrefixPath 过滤器：

📄️ PreserveHostHeader

PreserveHostHeader 过滤器没有参数。此过滤器设置一个请求属性，HandlerFunction 会检查该属性以确定是否应发送原始的主机头，而不是由 HTTP 客户端确定的主机头。以下示例配置了一个 PreserveHostHeader 过滤器：

📄️ 重定向过滤器

RedirectTo 过滤器接受两个参数，status 和 url。status 参数应该是一个 300 系列的 HTTP 重定向代码，例如 301。url 参数应该是一个有效的 URL，它将是 Location 头的值。对于相对重定向，你应该在路由定义的 uri 中使用 uri: no://op。以下示例配置了一个 RedirectTo 过滤器：

📄️ RemoveRequestHeader GatewayFilter Factory

RemoveRequestHeader 过滤器需要一个 name 参数。它是需要被移除的请求头的名称。以下代码配置了一个 RemoveRequestHeader 过滤器：

📄️ RemoveRequestParameter 过滤器

RemoveRequestParameter 过滤器需要一个 name 参数。它是需要移除的查询参数的名称。以下示例配置了一个 RemoveRequestParameter 过滤器：

📄️ RemoveResponseHeader 过滤器

RemoveResponseHeader 过滤器接受一个 name 参数。这是要移除的响应头的名称。以下配置展示了一个 RemoveResponseHeader 过滤器的示例：

📄️ RequestHeaderSize 过滤器

RequestHeaderSize 过滤器接受 maxSize 和 errorHeaderName 参数。maxSize 参数是请求头（包括键和值）允许的最大数据大小。errorHeaderName 参数设置包含错误信息的响应头的名称，默认情况下为 \"errorMessage\"。以下清单配置了一个 RequestHeaderSize 过滤器：

📄️ 速率限制器过滤器

RateLimiter 过滤器使用 Bucket4j 来确定当前请求是否允许继续执行。如果不允许，默认情况下将返回 HTTP 429 - 请求过多 的状态。

📄️ RewriteLocationResponseHeader 过滤器

RewriteLocationResponseHeader 过滤器用于修改 Location 响应头的值，通常是为了去除与后端相关的细节。它接受 stripVersionMode、locationHeaderName、hostValue 和 protocolsRegex 参数。以下清单配置了一个 RewriteLocationResponseHeader 过滤器：

📄️ RewritePath 过滤器

RewritePath 过滤器接受一个路径正则表达式参数和一个替换参数。它使用 Java 正则表达式来灵活地重写请求路径。以下清单配置了一个 RewritePath 过滤器：

📄️ RewriteResponseHeader 过滤器

RewriteResponseHeader 过滤器接受 name、regexp 和 replacement 参数。它使用 Java 正则表达式来灵活地重写响应头的值。以下示例配置了一个 RewriteResponseHeader 过滤器：

📄️ SetPath 过滤器

SetPath 过滤器接受一个路径模板参数。它提供了一种简单的方式来操作请求路径，允许使用模板化的路径段。这里使用了 Spring Framework 中的 URI 模板。允许多个匹配的路径段。以下示例配置了一个 SetPath 过滤器：

📄️ SetRequestHeader 过滤器

SetRequestHeader 过滤器接受 name 和 value 参数。以下代码清单配置了一个 SetRequestHeader 过滤器：

📄️ SetResponseHeader 过滤器

SetResponseHeader 过滤器接受 name 和 value 参数。以下代码清单配置了一个 SetResponseHeader 过滤器：

📄️ 设置状态过滤器

SetStatus 过滤器接受一个参数 status。它必须是一个有效的 Spring HttpStatus。可以是整数值 404 或枚举的字符串表示形式：NOT\_FOUND。以下清单配置了一个 SetStatus 过滤器：

📄️ StripPrefix 过滤器

StripPrefix 过滤器接受一个参数 parts。parts 参数表示在将请求发送到下游之前，从请求路径中剥离的部分数量。以下代码片段配置了一个 StripPrefix 过滤器：

📄️ 重试过滤器

重试过滤器支持以下参数：

📄️ RequestSize 过滤器

当请求大小超过允许的限制时，RequestSize 过滤器可以阻止请求到达下游服务。该过滤器接受一个 maxSize 参数。maxSize 是一个 DataSize 类型，因此值可以定义为一个数字，后跟一个可选的 DataUnit 后缀，如 'KB' 或 'MB'。默认单位为 'B'，表示字节。这是以字节为单位的允许请求大小限制。以下列表配置了一个 RequestSize 过滤器：

📄️ SetRequestHostHeader 过滤器

在某些情况下，可能需要覆盖主机头（host header）。在这种情况下，可以使用 SetRequestHostHeader 过滤器将现有的主机头替换为指定的值。该过滤器接受一个 host 参数。以下列表配置了一个 SetRequestHostHeader 过滤器：

📄️ TokenRelay 过滤器

令牌中继是指一个 OAuth2 消费者充当客户端，并将传入的令牌转发到发起的资源请求中。该消费者可以是纯客户端（如单点登录应用程序）或资源服务器。