网关处理器过滤器函数

DeepSeek V3 中英对照 Gateway Handler Filter Functions

前置过滤器函数

WebMvc.fn API 中有一个“前置”过滤器函数的概念，它是一个 java.util.Function<ServerRequest, ServerRequest>，仅作用于请求。许多前置过滤器函数在 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 是首选，因为它更明确。

After Filter Functions

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 是首选，因为它更明确。

高级筛选函数

有些过滤器无法简单地归类为前置或后置过滤器。这些过滤器在代理请求发起前后均会执行。其中包括位于 org.springframework.cloud.gateway.server.mvc.filter 包中的 BodyFilterFunctions、Bucket4jFilterFunctions、CircuitBreakerFilterFunctions、LoadBalancerFilterFunctions、RetryFilterFunctions 和 TokenRelayFilterFunctions。

章节总结

📄️AddRequestHeader 过滤器

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

📄️AddRequestHeadersIfNotPresent 过滤器

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

📄️AddRequestParameter 过滤器

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

📄️AddResponseHeader Filter

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

📄️CircuitBreaker Filter

Spring Cloud CircuitBreaker GatewayFilter 工厂使用 Spring Cloud CircuitBreaker API 将网关路由包装在断路器内。Spring Cloud CircuitBreaker 支持多个可与 Spring Cloud Gateway 配合使用的库。Spring Cloud 默认支持 Resilience4J。

📄️DedupeResponseHeader 过滤器

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

📄️FallbackHeaders 过滤器

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

📄️LoadBalancer Filter

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

📄️MapRequestHeader 过滤器

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

📄️ModifyRequestBody 过滤器

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

📄️ModifyResponseBody 过滤器

您可以使用 ModifyResponseBody 过滤器在响应体发送回客户端之前对其进行修改。

📄️PrefixPath Filter

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

📄️PreserveHostHeader 过滤器

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

📄️RedirectTo 过滤器

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

📄️RemoveRequestHeader GatewayFilter Factory

RemoveRequestHeader 过滤器接收一个 name 参数，该参数指定了需要移除的请求头名称。以下配置展示了如何配置 RemoveRequestHeader 过滤器：

📄️RemoveRequestParameter 过滤器

RemoveRequestParameter 过滤器接收一个 name 参数。该参数指定了需要被移除的查询参数的名称。以下示例配置了一个 RemoveRequestParameter 过滤器：

📄️RemoveResponseHeader 过滤器

RemoveResponseHeader 过滤器接收一个 name 参数，该参数指定了需要被移除的响应头名称。以下配置示例展示了如何配置一个 RemoveResponseHeader 过滤器：

📄️RequestHeaderSize Filter

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

📄️RateLimiter Filter

RateLimiter 过滤器使用 Bucket4j 来判断当前请求是否允许继续执行。如果不允许，则返回 HTTP 429 - 请求过多（默认）状态码。

📄️RewriteLocationResponseHeader 过滤器

RewriteLocationResponseHeader 过滤器用于修改 Location 响应头的值，通常用于移除后端特定的细节信息。它接受 stripVersionMode、locationHeaderName、hostValue 和 protocolsRegex 参数。以下配置展示了如何设置 RewriteLocationResponseHeader 过滤器：

📄️RewritePath 过滤器

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

📄️RewriteResponseHeader Filter

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

📄️SetPath 过滤器

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

📄️SetRequestHeader Filter

SetRequestHeader 过滤器接收 name 和 value 参数。以下配置展示了 SetRequestHeader 过滤器的使用：

📄️SetResponseHeader Filter

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

📄️SetStatus 过滤器

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

📄️StripPrefix 过滤器

StripPrefix 过滤器接收一个参数 parts。parts 参数表示在将请求发送到下游之前，需要从请求路径中剥离的部分数量。以下配置展示了如何设置 StripPrefix 过滤器：

📄️重试过滤器

Retry过滤器根据类路径上可用的实现自动选择合适的重试实现：

📄️RequestSize 过滤器

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

📄️SetRequestHostHeader 过滤器

在某些情况下，可能需要覆盖主机头。此时，SetRequestHostHeader 过滤器可以用指定值替换现有的主机头。该过滤器接受一个 host 参数。以下配置展示了如何设置 SetRequestHostHeader 过滤器：

📄️TokenRelay 过滤器

令牌中继是指 OAuth2 消费者充当客户端，并将传入的令牌转发给传出的资源请求。该消费者可以是纯客户端（如 SSO 应用程序）或资源服务器。