SpringCloud Gateway 30 个内置过滤器，少写 80% 重复代码-程序员充电站

我发现公司的网关项目里有很多的轮子，几乎每个人接手这个项目开发，都会自定义过滤器，导致有非常非常多的过滤器，修改其中一个，指不定就会影响其他的人功能，非常的恼火。

其实在 Spring Cloud Gateway 本身内置了很多通用的过滤器组件，有些功能无需重复开发，直接通过配置就能完成请求修改、参数处理、安全校验等功能。但遗憾的是，很多同学只知道RewritePath等常用过滤器，却忽略了官方早已内置的 30+ 过滤器。

下边小富梳理Spring Cloud Gateway 30+ 个过滤器，包含配置示例与实战场景，你会发现有些代码真的不用写。

一、请求相关

1.`AddRequestHeader`

作用：给请求添加 Header，转发请求前，给请求添加指定 Header。

配置示例：

spring: cloud: gateway: routes: -id:xiaofu-120412 uri:http://127.0.0.1:12041/ predicates: -Weight=xiaofu-group,1 -Path=/test/version1/** filters: -RewritePath=/test/version1/(?<segment>.*),/$\{segment} -name:AddRequestHeader args: name:X-Request-Source# Header名称 value:gateway # Header值

场景：传递请求来源标识（如gateway、app），方便下游服务做权限控制。

2.`RemoveRequestHeader`

作用：移除请求中的 Header，转发前移除请求中指定的 Header（如敏感信息）。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - name: RemoveRequestHeader args: name: Authorization # 移除客户端传来的 Authorization 头

场景：下游服务不需要客户端直接传递的令牌，由网关统一处理认证时使用。

3.`SetRequestHeader`

作用：覆盖请求中的 Header，若请求中已存在指定 Header，直接覆盖其值；不存在则添加。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - name: SetRequestHeader args: name: Authorization value: 111111 # 强制将 Authorization 设为 111111

注意：与AddRequestHeader的区别是，SetRequestHeader会覆盖原有值，而AddRequestHeader会保留原有值（若存在）。

4.`AddRequestParameter`

作用：转发请求时给请求添加参数，URL 或请求体添加参数（支持 GET/POST）。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - name: AddRequestParameter args: name: from value: gateway # 所有请求会带上 ?from=gateway 参数

场景：统计请求来源，或给下游服务传递额外标识（如灰度标记）。

5.`RemoveRequestParameter`

作用：移除请求中的参数，转发前移除请求中的指定参数（如敏感参数password）。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - name: RemoveRequestParameter args: name: password # 移除请求中的 password 参数

6.`MapRequestHeader`

作用：把网关请求头的值，映射到另一个请求头里。比如前端调用网关，请求头有一个X-User-Id用来验证，但是要转发的下游服务只校验请求头userId，这时要自动做一个映射。

配置示例：

filters: - MapRequestHeader=X-User-Id, userId

7.`RequestSize`

作用：限制请求体大小，拒绝请求体超过指定大小的请求（防止大文件上传压垮服务）。

配置示例：

filters: - name: RequestSize args: maxSize: 10MB # 最大请求体10MB，超过返回413

8.`RequestHeaderSize`

作用：限制请求头大小，拒绝请求头超过指定大小的请求，如下任何请求头的大小超过1000字节，这将发送一个 431状态码的响应。

配置示例：

filters: - RequestHeaderSize=1000B

9.`PreserveHostHeader`

作用：保留原始 Host 头，转发请求时，保留客户端的原始 Host 头（默认会改为下游服务的 Host）。

配置示例：

filters: - name: PreserveHostHeader # 无参数，直接启用

场景：下游服务依赖 Host 头进行逻辑处理时使用。

10.`SetRequestHostHeader`

作用：某些情况下，host 头可能需要被重写。修改请求的 Host 头，转发请求时，强制修改 Host 头为指定值。

配置示例：

filters: - name: SetRequestHostHeader args: host: target-service.com # 强制 Host 头为 target-service.com

11.`CacheRequestBody`

作用：缓存请求体，请求体（如 POST 请求的 JSON 数据），我们知道默认请求体只能读一次，所以为了后续的操作，使用该过滤器来缓存请求体，然后再把它发送到下游，从 exchange 属性中获取请求体。

配置示例：

filters: - name: CacheRequestBody args: cacheName: requestBodyCache # 缓存名称

场景：多个过滤器需要读取请求体时使用（如先校验签名，再解析参数）。

二、响应相关

主要是调整服务返回的响应信息，比如响应头 Header 等。

1.`AddResponseHeader`

作用：给响应添加 Header，服务返回响应后，给响应添加指定 Header（如跨域标识、缓存控制）。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - name: AddResponseHeader args: name: X-Response-Time value: 120 # 可结合全局过滤器动态设置响应时间

场景：添加Cache-Control: max-age=3600控制静态资源缓存。

2.`RemoveResponseHeader`

作用：移除响应中的 Header，移除服务返回的敏感响应头（如X-Application-Context暴露服务信息）。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - name: RemoveResponseHeader args: name: X-Application-Context

3.`SetResponseHeader`

作用：覆盖响应中的 Header，覆盖服务返回的响应头（如统一设置Content-Encoding）。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - name: SetResponseHeader args: name: Content-Encoding value: gzip # 强制响应使用 gzip 编码

4.`RewriteResponseHeader`

作用：重写响应 Header 的值，用正则表达式修改响应 Header 的值（如脱敏处理）。

配置示例：

filters: -RewritePath=/test/version1/(?<segment>.*),/$\{segment} -name:RewriteResponseHeader args: name:X-User-Phone regexp:"(.{3}).\*(.{4})"# 保留前3位和后4位 replacement:"\$1\*\*\*\*\$2" # 手机号脱敏为 138\*\*\*\*5678

5.`DedupeResponseHeader`

作用：去重响应头，当响应头存在多个相同名称时，去重并保留指定值。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - name: DedupeResponseHeader args: name: Access-Control-Allow-Origin strategy: RETAIN\_FIRST # 保留第一个值

场景：解决跨域配置中Access-Control-Allow-Origin重复的问题。

6.`RemoveJsonAttributesResponseBody`

作用：从根层 JSON 响应结果中移除指定字段，只对 Content-Type: application/json 的响应生效。

配置示例：

filters: - RewritePath=/test/version1/(?<segment>.*),/$\{segment} - RemoveJsonAttributesResponseBody=xiaofu

场景：比如在某些敏感或无意义的字段，下游服务暂时无法改动，而响应结果又不想暴漏出来的字段。注意：2021.x版本的网关还不支持，需要高版本。

7.`SetStatus`：设置响应状态码

作用：强制修改响应的 HTTP 状态码（如将 404 改为 200 并返回自定义提示）。

配置示例：

filters: - name: SetStatus args: status: 200 # 无论服务返回什么，响应状态码都设为 200

8.`RewriteLocationResponseHeader`

作用：重写响应头中的 Location（用于反向代理场景）。 NEVER_STRIP、AS_IN_REQUEST（默认）和 ALWAYS_STRIP。

NEVER_STRIP: 即使最初的请求路径不包含version，version也不会被剥离。
AS_IN_REQUEST: 只有当原始请求路径不包含version时，才会剥离version。
ALWAYS_STRIP: version 总是被剥离，即使原始请求路径包含version 。

配置示例：

filters: - RewriteLocationResponseHeader=AS_IN_REQUEST, Location

三、路径处理相关

修改请求路径与跳转相关的操作

1.`RewritePath`（最常用）

作用：重写请求路径，用正则表达式修改请求路径（如去掉/api前缀）。

配置示例：

filters: - name: RewritePath args: regexp: /api/(?\<segment>.\*) # 匹配 /api/test replacement: /\$\\{segment} # 重写为 /test（转发到下游服务）

场景：前端请求带/api前缀，网关转发时去掉，适配下游服务接口路径。

2.`PrefixPath`

作用：给路径添加前缀，转发前给请求路径添加指定前缀（如下游服务接口统一带/v1）。

配置示例：

filters: - name: PrefixPath args: prefix: /v1 # 请求 /user → 转发到 /v1/user

3.`StripPrefix`

作用：移除路径前缀，移除路径中指定数量的前缀段（如/api/v1/user移除 2 段前缀）。

配置示例：

filters: - name: StripPrefix args: parts: 2 # /api/v1/user → 转发到 /user

注意：与RewritePath的区别是，StripPrefix按段数移除，RewritePath按正则匹配，更灵活。

4.`RedirectTo`

作用：重定向请求，将请求重定向到指定 URL（支持 301/302 状态码）。

配置示例：

filters: - name: RedirectTo args: status: 302 # 临时重定向 url: https://baidu.com # 重定向到新域名

场景：域名迁移、旧接口废弃时引导到新地址。

5.`SetPath`

作用：直接设置路径，用模板语法直接设置请求路径（替代原有路径）。

配置示例：

filters: - name: SetPath args: template: /fixed/path # 所有请求都转发到 /fixed/path

四、安全相关：

控制请求参数与路由转发相关的操作，比如请求限流、重试、负载均衡等。

1.`RequestRateLimiter`

作用：基于令牌桶算法限流（默认用 Redis 存储限流计数）。

配置示例：

filters: -RewritePath=/test/version1/(?<segment>.*),/$\{segment} -name:RequestRateLimiter args: redis-rate-limiter.replenishRate:10# 令牌桶填充速率（每秒10个） redis-rate-limiter.burstCapacity:20# 令牌桶最大容量（最多存20个） key-resolver:"#{@myKeyResolver}" # 需自定义 KeyResolver

key-resolver用于定义如何生成限流的key，这通常基于请求的某些属性（如IP地址、用户ID等）。你可以通过实现 KeyResolver 接口来自定义key解析器。

import org.springframework.cloud.gateway.filter.ratelimit.KeyResolver; import org.springframework.stereotype.Component; import org.springframework.web.server.ServerWebExchange; import reactor.core.publisher.Mono; @Component("myKeyResolver") public class MyKeyResolver implements KeyResolver { @Override public Mono<String> resolve(ServerWebExchange exchange) { // 例如，根据请求头中的某个字段生成key return Mono.just("8888888x-api-key:"+exchange.getRequest().getHeaders().getFirst("x-api-key")); } }

由于默认是 redis 做底层限流，所以这里要加上 redis 配置信息

spring: redis: host: localhost port: 6379 password: xxxx

场景：保护下游服务，防止流量过载（如秒杀接口限制单 IP 访问频率）。

2.`Retry`

作用：请求重试，当服务返回指定状态码或超时，自动重试请求。

配置示例：

filters: -name:Retry args: retries:3# 最多重试3次 statuses:BAD_GATEWAY,SERVICE_UNAVAILABLE# 遇到 502/503 重试 methods:GET,POST backoff: firstBackoff:10ms# 第一次重试延迟100ms maxBackoff:50ms# 最大延迟1s factor:2# 延迟倍数（100ms → 200ms → 400ms） basedOnPreviousValue:false

注意：重试可能导致下游服务重复处理，需确保接口幂等性。

3.`Hystrix`

作用：熔断降级（已过时，推荐CircuitBreaker），服务调用超时或失败时，触发熔断并返回降级响应。

配置示例：

filters: - name: Hystrix args: name: fallbackCommand # 熔断命令名 fallbackUri: forward:/fallback # 降级接口（返回默认数据）

4.`CircuitBreaker`

作用：熔断降级（替代 Hystrix），基于 Resilience4j 实现熔断，支持超时、失败率阈值配置。

配置示例：

filters: -name:CircuitBreaker args: name:myCircuitBreaker fallbackUri:forward:/inCaseOfFailureUseThis# 这里是网关内的控制器uri statusCodes:# 也可根据状态来控制是否熔断 -500 -"NOT_FOUND"

@RestController @RequestMapping("/") @Slf4j public class InCaseOfFailureUseThisController { @GetMapping(value = "/inCaseOfFailureUseThis") public String inCaseOfFailureUseThis() { System.out.println("inCaseOfFailureUseThis"); return "inCaseOfFailureUseThis"; } }

如果我们希望熔断后不路由到网关，而且是转发到其他的外部路径，可以如下设置。

spring: cloud: gateway: routes: -id:ingredients uri:http://127.0.0.1:12041/ predicates: -Path=//ingredients/** filters: -name:CircuitBreaker args: name:myCircuitBreaker fallbackUri:forward:/fallback -id:myCircuitBreaker-fallback uri:http://localhost:9994 predicates: -Path=/fallback

5.`SaveSession`

在转发调用下游之前强制进行 WebSession::save 操作，这在使用类似 Spring Session 的懒数据存储时特别有用，因为你需要确保在进行转发调用之前已经保存了Session状态。

配置示例：

filters: - SaveSession

如果集成了 Spring Security 与 Spring Session ，而且希望确保安全细节已被转发到下游进程，这一点至关重要。

写在最后

这期东西还是很多的，其实 80% 的路由增强场景（如路径重写、限流、跨域）都能通过内置过滤器实现，无需手写代码，所有不要动不动就想着加过滤器。还有在使用过滤器的时候要注意，多个过滤器的配置顺序，顺序不对容易出奇奇怪怪的问题哦。

看完等于学会，点个赞吧！！！

一、请求相关

1.AddRequestHeader

2.RemoveRequestHeader

3.SetRequestHeader

4.AddRequestParameter

5.RemoveRequestParameter

6.MapRequestHeader

7.RequestSize

8.RequestHeaderSize

9.PreserveHostHeader

10.SetRequestHostHeader

11.CacheRequestBody

二、响应相关

1.AddResponseHeader

2.RemoveResponseHeader

3.SetResponseHeader

4.RewriteResponseHeader

5.DedupeResponseHeader

6.RemoveJsonAttributesResponseBody

7.SetStatus：设置响应状态码

8.RewriteLocationResponseHeader

三、路径处理相关

1.RewritePath（最常用）

2.PrefixPath

3.StripPrefix

4.RedirectTo

5.SetPath

四、安全相关：

1.RequestRateLimiter

2.Retry

3.Hystrix

4.CircuitBreaker

5.SaveSession

写在最后

10分钟极速配置：沉浸式翻译第三方API集成实战指南

3小时从零部署CompreFace：企业级人脸识别系统搭建完全指南

8 种异步实现方式，性能炸裂！！

CapsLock+键盘革命：重新定义你的输入效率

如何解决FunASR语音识别工具常见使用问题

SenseVoice量化部署终极方案：3倍性能提升与75%模型压缩实战指南

1.`AddRequestHeader`

2.`RemoveRequestHeader`

3.`SetRequestHeader`

4.`AddRequestParameter`

5.`RemoveRequestParameter`

6.`MapRequestHeader`

7.`RequestSize`

8.`RequestHeaderSize`

9.`PreserveHostHeader`

10.`SetRequestHostHeader`

11.`CacheRequestBody`

1.`AddResponseHeader`

2.`RemoveResponseHeader`

3.`SetResponseHeader`

4.`RewriteResponseHeader`

5.`DedupeResponseHeader`

6.`RemoveJsonAttributesResponseBody`

7.`SetStatus`：设置响应状态码

8.`RewriteLocationResponseHeader`

1.`RewritePath`（最常用）

2.`PrefixPath`

3.`StripPrefix`

4.`RedirectTo`

5.`SetPath`

1.`RequestRateLimiter`

2.`Retry`

3.`Hystrix`

4.`CircuitBreaker`

5.`SaveSession`