别再手写过滤器！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:

value: gateway # Header值

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

2. RemoveRequestHeader

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

配置示例：

filters:

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

- name: RemoveRequestHeader

args:

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

3. SetRequestHeader

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

配置示例：

filters:

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

- name: SetRequestHeader

args:

value: 111111 # 强制将 Authorization 设为 111111

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

4. AddRequestParameter

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

配置示例：

filters:

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

- name: AddRequestParameter

args:

value: gateway # 所有请求会带上 ?from=gateway 参数

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

5. RemoveRequestParameter

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

配置示例：

filters:

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

- name: RemoveRequestParameter

args:

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:

value: 120 # 可结合全局过滤器动态设置响应时间

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

2. RemoveResponseHeader

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

配置示例：

filters:

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

- name: RemoveResponseHeader

args:

3. SetResponseHeader

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

配置示例：

filters:

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

- name: SetResponseHeader

args:

value: gzip # 强制响应使用 gzip 编码

4. RewriteResponseHeader

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

配置示例：

filters:

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

- name: RewriteResponseHeader

args:

regexp: "(.{3}).\*(.{4})" # 保留前3位和后4位

replacement: "\$1\*\*\*\*\$2" # 手机号脱敏为 138\*\*\*\*5678

5. DedupeResponseHeader

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

配置示例：

filters:

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

- name: DedupeResponseHeader

args:

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:

四、安全相关：

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

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:

fallbackUri: forward:/fallback # 降级接口（返回默认数据）

4. CircuitBreaker

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

配置示例：

filters:

- name: CircuitBreaker

args:

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:

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 ，而且希望确保安全细节已被转发到下游进程，这一点至关重要。

写在最后

别再手写过滤器！SpringCloud Gateway 内置30 个，少写 80% 重复代码

开源 + 国产芯片：具身智能的 DeepSeek 时刻来了？

PHP 8.5 新特性闭包可以作为常量表达式了

在PySide6/PyQt6的开发框架中，增加对表格多种格式录入的处理，以及主从表的数据显示和保存操作。

分布式抢券系统限流器降级与CAP权衡全攻略

通达信周KDJ副图

成功案例」何帆律师代理因存在冠心病、急性心肌梗塞、心梗等既往症猝死，意外险拒赔案

开源 + 国产芯片：具身智能的 DeepSeek 时刻来了？

PHP 8.5 新特性 闭包可以作为常量表达式了

在PySide6/PyQt6的开发框架中，增加对表格多种格式录入的处理，以及主从表的数据显示和保存操作。

分布式抢券系统限流器降级与CAP权衡全攻略

通达信周KDJ副图

成功案例」何帆律师代理因存在冠心病、急性心肌梗塞、心梗等既往症猝死，意外险拒赔案

PHP 8.5 新特性闭包可以作为常量表达式了