1. 从一个真实需求说起：为什么全局过滤器值得单独拎出来讲
刚接触 Spring Cloud Gateway 的时候，大多数人都是从路由配置开始的：spring.cloud.gateway.routes里配一堆id、uri、predicates、filters，跑起来能转发请求，感觉就够用了。但真正到了生产环境，你会发现路由级别的过滤器有个绕不开的局限——它是绑定在单条路由上的。也就是说，你配了十条路由，想给所有请求统一加一个请求头、统一记录一次耗时日志、统一做一次鉴权校验，就得在十条路由里各写一遍，或者用default-filters凑合。前者维护成本高，后者能力受限，改起来牵一发动全身。
GlobalFilter就是来解决这个问题的。它不需要绑定任何一条具体路由，只要被 Spring 容器管理起来，就会自动作用于所有经过网关的请求。这个特性决定了它的定位：适合做那些"跟具体业务路由无关、但每个请求都得过一遍"的事情，比如全局鉴权、全链路追踪 ID 注入、统一响应头处理、请求耗时统计、灰度标记透传等等。
这篇文章面向的是已经能跑通 Gateway 基础路由、准备把网关往生产级别推进的开发者。我会从GlobalFilter的执行机制讲起，把它的加载顺序、与GatewayFilter的关系、Ordered排序这些容易含糊的点掰开说清楚，然后给出一套可以直接抄的全局过滤器写法，最后重点讲几个我自己踩过的坑——尤其是过滤器执行顺序错乱导致鉴权失效和响应体被重复读取这两类问题，这两类问题在线上排查起来非常费劲。看完你应该能独立写出一个稳定、可维护的全局过滤器，并且知道它什么时候该用、什么时候不该用。
2. GlobalFilter 到底在网关的哪个环节生效
2.1 请求进入网关后的完整链路
要理解GlobalFilter，得先知道一个请求从进网关到出网关，中间经历了什么。Spring Cloud Gateway 底层是基于 Spring WebFlux 的响应式模型，整个处理链路大致是这样的：
请求到达网关后，先经过DispatcherHandler，然后交给RoutePredicateHandlerMapping。这个 HandlerMapping 的职责是根据请求去匹配路由——它遍历所有配置的RouteDefinition，用每条路由的Predicate去判断这个请求该不该走这条路由。匹配成功后，请求会被交给FilteringWebHandler。
FilteringWebHandler是核心。它做的事情是：把当前路由上配置的GatewayFilter和容器里所有的GlobalFilter合并成一条过滤器链，然后按顺序依次执行。注意这里的"合并"两个字，它意味着GlobalFilter和GatewayFilter在运行时是被平等对待的，最终都变成GatewayFilterAdapter或者直接就是过滤器实例，统一排序后串成链。
这条链的执行模型是响应式的，用的是Mono的chain.filter(exchange)递归调用。每个过滤器在调用chain.filter()之前的代码是"前置逻辑"，调用之后（通过then()或doFinally()）的代码是"后置逻辑"。这一点非常关键，后面讲顺序问题时会反复用到。
2.2 GlobalFilter 与 GatewayFilter 的本质区别
很多人分不清这两个东西，我用一句话概括：GatewayFilter是"路由级"的，GlobalFilter是"应用级"的。
GatewayFilter必须通过配置或者RouteLocatorBuilder绑定到某条路由上才会生效，它的作用范围就是那条路由。而GlobalFilter只要加上@Component注解被 Spring 扫描到，就会自动加入每一条路由的过滤器链。从接口定义上看，两者也很像：
public interface GlobalFilter { Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain); } public interface GatewayFilter { Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain); }方法签名几乎一模一样，区别只在注册方式和作用范围。正因为签名一致，Gateway 内部才能把它们统一成一条链。这里有个细节值得注意：GlobalFilter没有Ordered接口的强制要求，但如果你想控制执行顺序，就必须实现Ordered或者加@Order注解，否则顺序是不确定的。
2.3 过滤器链的排序规则
排序是GlobalFilter最容易出问题的地方，我单独拎出来讲。整条过滤器链的排序依据是Ordered接口返回的int值，值越小越先执行。这个规则本身简单，但坑在于：GatewayFilter和GlobalFilter是混在一起排序的，而且 Gateway 内置了一大批过滤器，它们各自占了不同的 order 值。
我整理了一张常用内置过滤器的 order 参考表，这个在实际开发中很有用：
| 过滤器名称 | 类型 | 典型 Order 值 | 作用 |
|---|---|---|---|
RemoveCachedBodyFilter | Global | Integer.MIN_VALUE | 清理缓存的请求体 |
AdaptCachedBodyGlobalFilter | Global | Integer.MIN_VALUE + 1000 | 缓存请求体供后续读取 |
NettyWriteResponseFilter | Global | -1 | 写响应回客户端 |
ForwardPathFilter | Global | 0 | 处理 forward 场景 |
RouteToRequestUrlFilter | Global | 10000 | 把路由 URI 转成实际请求 URL |
LoadBalancerClientFilter | Global | 10100 | 负载均衡选实例 |
NettyRoutingFilter | Global | Integer.MAX_VALUE | 真正发起下游请求 |
这张表的意义在于：你的自定义过滤器 order 值决定了它相对于这些内置过滤器的位置。比如你想在请求真正发往下游之前修改请求头，那 order 就得小于NettyRoutingFilter的Integer.MAX_VALUE；如果你想在响应写回客户端之前处理响应，那 order 得小于NettyWriteResponseFilter的-1。这个逻辑不理解，写出来的过滤器行为会很诡异。
3. 手写一个生产可用的全局过滤器
3.1 最小可用骨架与注册方式
先给一个最朴素的骨架，把结构立起来：
@Component public class SimpleGlobalFilter implements GlobalFilter, Ordered { private static final Logger log = LoggerFactory.getLogger(SimpleGlobalFilter.class); @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { long start = System.currentTimeMillis(); String path = exchange.getRequest().getURI().getPath(); log.info("request in, path={}", path); return chain.filter(exchange).then(Mono.fromRunnable(() -> { long cost = System.currentTimeMillis() - start; log.info("request out, path={}, cost={}ms", path, cost); })); } @Override public int getOrder() { return 0; } }这段代码做了两件事：请求进来时记录开始时间，请求处理完后计算耗时。注意chain.filter(exchange).then(...)这个写法——then里的逻辑会在整个过滤器链执行完毕之后才触发，也就是响应已经准备好、即将写回客户端的时候。这是响应式编程里做"后置处理"的标准姿势。
注册方式就是@Component，没有别的花样。只要它在 Spring 的扫描路径下，就会被FilteringWebHandler自动收集。这里有个新手常犯的错误：把过滤器类写在@SpringBootApplication启动类所在包的外层，导致没被扫描到，然后纳闷为什么过滤器不生效。包路径一定要覆盖到。
3.2 用 exchange 的 attributes 在过滤器之间传数据
多个过滤器之间经常需要共享数据，比如鉴权过滤器解析出用户 ID，后面的日志过滤器想把它记下来。ServerWebExchange提供了一个getAttributes()方法，返回一个Map<String, Object>，这就是过滤器之间传递数据的标准通道。
// 上游过滤器写入 exchange.getAttributes().put("userId", userId); // 下游过滤器读取 Object userId = exchange.getAttributes().get("userId");这个 map 的生命周期是单次请求级别的，请求结束就销毁，不会串请求，可以放心用。但要注意两点：一是 key 命名最好加个前缀避免和内置属性冲突，比如用myapp.userId而不是userId；二是存进去的对象如果是可变的，注意线程安全，虽然响应式模型下同一个请求基本是串行处理的，但养成好习惯没坏处。
3.3 修改请求与响应：可变与不可变的边界
GlobalFilter最常被用来改请求头和响应头，但这里有个响应式框架特有的约束：请求和响应对象在创建后是不可变的，你不能直接request.getHeaders().add(...)就完事，得用mutate()构造一个新对象。
改请求头：
ServerHttpRequest newRequest = exchange.getRequest().mutate() .header("X-Trace-Id", traceId) .build(); ServerWebExchange newExchange = exchange.mutate().request(newRequest).build(); return chain.filter(newExchange);改响应头：
exchange.getResponse().getHeaders().add("X-Response-Time", String.valueOf(cost));响应头这里稍微特殊一点，getHeaders()返回的是可变的HttpHeaders，可以直接 add。但如果你想在响应已经提交之后再改，那就晚了——响应头一旦 flush 出去就改不了了。所以改响应头的逻辑必须放在chain.filter()的then回调里，且要确保此时响应还没提交。
注意：
exchange.mutate()返回的是Builder，必须调用.build()才能拿到新的 exchange。忘了 build 是新手高频错误，编译能过但行为不对。
3.4 读取请求体的正确姿势
读取请求体是GlobalFilter里最麻烦的操作，因为请求体是流，读一次就没了。如果你在过滤器里读了，下游就拿不到数据了。Gateway 内置的AdaptCachedBodyGlobalFilter和RemoveCachedBodyFilter就是专门处理这个问题的。
正确做法是借助ServerWebExchangeUtils提供的缓存机制：
@Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { return DataBufferUtils.join(exchange.getRequest().getBody()) .flatMap(dataBuffer -> { byte[] bytes = new byte[dataBuffer.readableByteCount()]; dataBuffer.read(bytes); DataBufferUtils.release(dataBuffer); String body = new String(bytes, StandardCharsets.UTF_8); // 处理 body exchange.getAttributes().put("cachedBody", body); // 重新包装请求体，让下游还能读到 ServerHttpRequest newRequest = exchange.getRequest().mutate() .body(Flux.just(exchange.getResponse().bufferFactory().wrap(bytes))) .build(); return chain.filter(exchange.mutate().request(newRequest).build()); }); }这段代码的关键在于最后一步：把读出来的字节重新包回请求体，否则下游服务收到的就是空 body。DataBufferUtils.release也不能忘，响应式里 DataBuffer 是池化的，不释放会造成内存泄漏。这个坑我在早期项目里踩过，表现为运行一段时间后堆外内存持续增长，排查了很久才定位到。
4. 顺序、异常与响应处理：三个最容易翻车的地方
4.1 鉴权过滤器顺序错乱导致的安全漏洞
这是我认为最严重的一类问题。假设你写了一个鉴权过滤器，order 设为100，同时用了 Gateway 内置的LoadBalancerClientFilter（order10100）。看起来没问题，鉴权在负载均衡之前执行。但如果你的鉴权过滤器里做了异步操作，比如调用远程鉴权服务，而chain.filter()的调用时机没处理好，就可能出现请求已经转发到下游了，鉴权结果才回来的情况。
更隐蔽的是这种：鉴权过滤器 order 设得太大，比如设成了Integer.MAX_VALUE，那它就会排在NettyRoutingFilter后面，等于请求都发出去了才鉴权，完全失效。所以鉴权类过滤器的 order 一定要设成负数或者很小的正数，确保它在所有业务逻辑之前执行。我一般用-100到-1这个区间。
@Override public int getOrder() { return -100; // 确保在路由转发之前执行 }判断顺序对不对，有个简单的验证方法：在过滤器里打日志，同时把 Gateway 的日志级别调到DEBUG，观察NettyRoutingFilter的日志和你的过滤器日志谁先出现。你的日志必须先出现。
4.2 异常处理：别让过滤器把异常吞了
GlobalFilter里抛出的异常，默认会被 Gateway 的ErrorWebExceptionHandler捕获，返回一个 500 响应。但如果你在过滤器里用了try-catch把异常吞了，或者用了onErrorResume返回了空，那异常就消失了，下游可能收到一个不完整的请求，问题很难查。
我的建议是：过滤器里只捕获你明确知道怎么处理的异常，其他一律往上抛。如果确实需要自定义错误响应，用exchange.getResponse()直接写：
if (tokenInvalid) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); exchange.getResponse().getHeaders().setContentType(MediaType.APPLICATION_JSON); String body = "{\"code\":401,\"msg\":\"unauthorized\"}"; DataBuffer buffer = exchange.getResponse().bufferFactory() .wrap(body.getBytes(StandardCharsets.UTF_8)); return exchange.getResponse().writeWith(Mono.just(buffer)); }注意这里直接return了，没有调用chain.filter()，意味着请求到此为止，不会继续往下走。这是过滤器"短路"的标准写法，鉴权失败、限流拦截都是这个套路。
4.3 响应体修改：为什么你的过滤器读不到响应内容
想在过滤器里修改响应体（比如统一包装返回格式），比改请求体还麻烦。因为响应是下游服务产生的，GlobalFilter默认拿不到响应体的内容——响应是流式的，边产生边写回客户端。
要拿到响应体，得用ServerHttpResponseDecorator包装原始响应，拦截writeWith方法：
ServerHttpResponse originalResponse = exchange.getResponse(); DataBufferFactory bufferFactory = originalResponse.bufferFactory(); ServerHttpResponseDecorator decoratedResponse = new ServerHttpResponseDecorator(originalResponse) { @Override public Mono<Void> writeWith(Publisher<? extends DataBuffer> body) { if (body instanceof Flux) { Flux<? extends DataBuffer> fluxBody = (Flux<? extends DataBuffer>) body; return super.writeWith(fluxBody.buffer().map(dataBuffers -> { DataBuffer joined = bufferFactory.join(dataBuffers); byte[] content = new byte[joined.readableByteCount()]; joined.read(content); DataBufferUtils.release(joined); String original = new String(content, StandardCharsets.UTF_8); String modified = wrapResponse(original); return bufferFactory.wrap(modified.getBytes(StandardCharsets.UTF_8)); })); } return super.writeWith(body); } }; return chain.filter(exchange.mutate().response(decoratedResponse).build());这段代码有几个坑必须说清楚。第一，fluxBody.buffer()会把多个 DataBuffer 合并成一个列表，但如果响应体很大，合并会占用大量内存，所以这种方案只适合小响应体场景，大文件下载千万别这么干。第二，修改后的内容长度变了，必须同步更新Content-Length头，否则客户端会解析出错：
originalResponse.getHeaders().setContentLength(modified.getBytes(StandardCharsets.UTF_8).length);第三，DataBufferUtils.release一定要调用，理由和前面一样。我见过因为漏了 release 导致网关跑几天就 OOM 的案例，排查成本极高。
5. 几个真实场景下的过滤器设计取舍
5.1 全链路追踪 ID 注入：为什么用 order = -200
全链路追踪要求在请求进入网关的第一时间生成一个 traceId，注入到请求头里传给下游。这个过滤器必须尽可能早执行，因为后面的日志、鉴权过滤器都想用这个 traceId。我一般把 order 设成-200，比鉴权还早。
@Component public class TraceIdFilter implements GlobalFilter, Ordered { @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { String traceId = exchange.getRequest().getHeaders().getFirst("X-Trace-Id"); if (traceId == null || traceId.isEmpty()) { traceId = UUID.randomUUID().toString().replace("-", ""); } exchange.getAttributes().put("traceId", traceId); ServerHttpRequest request = exchange.getRequest().mutate() .header("X-Trace-Id", traceId).build(); return chain.filter(exchange.mutate().request(request).build()); } @Override public int getOrder() { return -200; } }这里有个细节：如果上游已经带了 traceId（比如从更外层的入口传进来的），就复用而不是重新生成，保证链路完整。这个判断不能省。
5.2 统一响应包装：收益与代价的权衡
很多团队想在网关层统一包装响应格式，把下游返回的{"data":...}包成{"code":0,"data":...,"msg":"ok"}。技术上用 4.3 节的ServerHttpResponseDecorator能实现，但我要泼盆冷水：这个方案在生产环境要慎用。
原因有三。一是性能，每个响应都要在网关层做一次完整的字节拷贝和字符串拼接，QPS 高的时候网关 CPU 会明显上升。二是兼容性，下游如果有文件流、SSE、WebSocket 这类特殊响应，包装逻辑会直接把它们搞坏。三是排错困难，响应体在网关被改过，出问题时你看到的和下游实际返回的不一致，定位链路变长。
我的建议是：响应包装尽量放在业务服务层做，网关层只做响应头级别的统一处理，比如加个X-Gateway-Version之类的标记。如果非要在网关做，一定要加开关，能按路由粒度控制，别一刀切。
5.3 灰度标记透传：一个轻量但实用的过滤器
灰度发布场景下，网关需要根据用户特征打上灰度标记，透传给下游做路由。这个过滤器逻辑简单但很实用：
@Component public class GrayTagFilter implements GlobalFilter, Ordered { @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { String userId = exchange.getRequest().getHeaders().getFirst("X-User-Id"); String grayTag = "stable"; if (userId != null && isGrayUser(userId)) { grayTag = "gray"; } ServerHttpRequest request = exchange.getRequest().mutate() .header("X-Gray-Tag", grayTag).build(); return chain.filter(exchange.mutate().request(request).build()); } private boolean isGrayUser(String userId) { // 按用户 ID 哈希取模，保证同一用户稳定命中同一分组 return Math.abs(userId.hashCode()) % 100 < 10; } @Override public int getOrder() { return -50; } }这里isGrayUser用的是哈希取模，好处是同一个用户每次请求的灰度结果一致，不会出现用户一会儿走灰度一会儿走稳定版的诡异现象。如果用随机数，用户体验会很割裂。这个细节很多人不注意，但实际影响很大。
6. 调试与验证：怎么确认你的过滤器真的按预期跑了
写完过滤器，怎么验证它生效了、顺序对了、数据传对了？我总结了几个实用手段。
第一招是日志埋点。在每个过滤器的前置和后置逻辑里都打日志，带上 order 值和 traceId。启动后发一个请求，看日志输出顺序。如果顺序和你预期的 order 不一致，说明有过滤器没实现Ordered，或者被@Order注解覆盖了。
第二招是利用 Actuator。Gateway 提供了/actuator/gateway/routes端点，能看到所有路由及其绑定的过滤器。虽然它不直接列出GlobalFilter，但能帮你确认路由匹配是否正确——很多时候过滤器"没生效"其实是路由压根没匹配上。
第三招是单元测试。GlobalFilter是可以脱离网关单独测的，用MockServerWebExchange构造请求，用MockServerHttpResponse验证响应：
@Test public void testTraceIdFilter() { MockServerHttpRequest request = MockServerHttpRequest.get("/test").build(); MockServerWebExchange exchange = MockServerWebExchange.from(request); AtomicReference<ServerWebExchange> captured = new AtomicReference<>(); GatewayFilterChain chain = ex -> { captured.set(ex); return Mono.empty(); }; traceIdFilter.filter(exchange, chain).block(); String traceId = captured.get().getRequest().getHeaders().getFirst("X-Trace-Id"); assertNotNull(traceId); }这个测试模式很实用，能覆盖大部分过滤器逻辑，比每次启动整个网关去点接口快得多。
第四招是压测验证。过滤器在低并发下正常不代表高并发下正常，尤其是涉及请求体缓存、响应体装饰的过滤器。用压测工具跑一轮，观察网关的内存和 CPU，以及有没有请求丢失或响应错乱。我踩过的内存泄漏问题，都是压测阶段才暴露出来的。
提示：调试过滤器顺序时，把
org.springframework.cloud.gateway的日志级别设为DEBUG，能看到过滤器链的完整执行过程，比猜快得多。
7. 写在最后的一点个人体会
GlobalFilter这个机制本身不复杂，接口就一个方法，难的是在响应式模型下把顺序、异常、数据传递这三件事同时处理对。我自己的经验是，每写一个全局过滤器，都先问自己三个问题：它的 order 值应该落在哪个区间？它失败了会不会影响其他请求？它有没有可能读到或改坏请求响应体？把这三个问题想清楚，基本就不会出大问题。
另外，全局过滤器不是越多越好。每加一个，所有请求都要多走一遍，网关的吞吐会受影响。能用路由级GatewayFilter解决的，就别用全局的。全局过滤器留给那些真正"全局"的事情——追踪、鉴权、日志、灰度，这些才是它的主场。
