1. 为什么全局过滤器值得单独拎出来讲但凡做过微服务网关的大概率都写过GlobalFilter。但很多人对它的理解停留在“抄一段代码实现filter方法返回chain.filter(exchange)就完事了”。真到线上出问题的时候比如鉴权失效、日志丢失、响应被截断、过滤器执行顺序乱套才发现对这个组件的理解欠了火候。Spring Cloud Gateway的过滤器分两种GatewayFilter和GlobalFilter。前者绑定在具体路由上配置里写在哪条路由就只对哪条生效后者是全局的只要请求经过网关它就会参与处理。这个“全局”二字意味着它天然适合做那些跨所有路由的统一逻辑——统一鉴权、统一日志埋点、统一请求头清洗、统一响应包装、统一灰度标记。换句话说它是网关层最像“切面”的东西。这篇文章面向的是已经用过Spring Cloud Gateway、但想把GlobalFilter用扎实的开发者。我会从它的执行模型讲起把顺序控制、请求改写、响应改写、异常处理、性能注意点这些容易踩坑的地方一个个拆开配上可直接复现的代码和参数说明。看完你应该能做到知道过滤器为什么这么排序、知道exchange里哪些东西能改哪些不能改、知道怎么写一个既安全又不拖慢网关的全局过滤器。先给一个整体认知GlobalFilter的核心接口就一个方法签名是MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain)。整个网关基于Spring WebFlux是响应式非阻塞模型所以过滤器里绝对不能写阻塞代码这是后面所有注意事项的根源。2. GlobalFilter 的执行模型与顺序机制2.1 过滤器链是怎么串起来的请求进到网关后RoutePredicateHandlerMapping先根据断言匹配到路由然后FilteringWebHandler把该路由的GatewayFilter和所有GlobalFilter合并成一个列表排序后逐个执行。合并后的链条里每个过滤器拿到GatewayFilterChain调用chain.filter(exchange)就代表“放行到下一个过滤器”返回的Mono完成时代表“后续链条执行完毕”。这里有个关键点chain.filter(exchange)返回的Mono是后续整条链的完成信号。所以你在调用它之前写的代码是“前置逻辑”调用之后用.then(...)或doFinally挂上去的是“后置逻辑”。这个结构决定了过滤器天然支持环绕式处理类似 Servlet 里的Filter但因为是响应式写法完全不同。Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { // 前置逻辑请求进入时执行 long start System.currentTimeMillis(); return chain.filter(exchange) .then(Mono.fromRunnable(() - { // 后置逻辑响应返回后执行 long cost System.currentTimeMillis() - start; log.info(cost{}ms, cost); })); }上面这段是最小可用的耗时统计过滤器。注意.then()里的逻辑是在响应写回之后触发的如果你要修改响应体光靠.then()不够得用ServerHttpResponseDecorator这个后面单独讲。2.2 Ordered 接口与执行顺序的真相GlobalFilter排序靠的是Ordered接口或者Order注解。数字越小优先级越高越先执行。前置逻辑按升序走后置逻辑按降序回形成一个洋葱模型。很多人以为随便给个数字就行实际上顺序错了会出大问题。举个典型场景你有一个鉴权过滤器和一个日志过滤器。如果日志过滤器先执行、鉴权后执行那么未通过鉴权的请求也会被记进日志日志里全是 401噪音很大。正确做法是让鉴权优先级更高数字更小先拦截非法请求日志只记录合法流量。过滤器类型建议 Order 值理由请求 ID 注入-200最靠前后续所有日志都能带上 traceId鉴权 / 令牌校验-100尽早拦截非法请求减少无效下游调用请求头清洗 / 改写0在鉴权之后、业务转发之前日志埋点100记录经过前面处理后的最终请求响应包装200最后处理响应体注意Ordered值不要用Integer.MIN_VALUE或MAX_VALUE这种极端值框架内部有些过滤器用了接近边界的值容易撞车导致顺序不确定。2.3 与 GatewayFilter 的优先级关系合并列表时GatewayFilter和GlobalFilter是放在一起排序的。也就是说一个配置在路由上的GatewayFilter如果Order是 -50它会插在鉴权-100和请求头清洗0之间。这个特性很有用你可以用全局过滤器定框架用路由级过滤器做局部微调。但要注意路由级GatewayFilter通过配置文件写的时候顺序由它在 YAML 里的位置决定默认按声明顺序给递增的 order。混用两种过滤器时建议全局过滤器统一用负数到正数的大区间给路由级过滤器留出插入空间避免顺序打架。3. 请求阶段的改写实操3.1 修改请求头与请求参数请求改写是GlobalFilter最高频的用途。ServerWebExchange提供了mutate()方法来构造一个可修改的副本直接改原始对象是不行的因为它是不可变的。Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest().mutate() .header(X-Gateway-Tag, global-filter) .headers(h - h.remove(X-Internal-Token)) .build(); return chain.filter(exchange.mutate().request(request).build()); }这段代码做了两件事加一个自定义头删掉一个不该外泄的内部头。mutate()返回的是Builder可以链式调用。headers(ConsumerHttpHeaders)这个重载特别适合做批量清洗比如把客户端伪造的X-Forwarded-*系列头统一处理掉。改查询参数稍微麻烦一点因为 query string 在 URI 里。常见做法是重建 URIURI original exchange.getRequest().getURI(); String newQuery original.getQuery() null ? sourcegateway : original.getQuery() sourcegateway; URI newUri UriComponentsBuilder.fromUri(original).replaceQuery(newQuery).build(true).toUri(); ServerHttpRequest request exchange.getRequest().mutate().uri(newUri).build();提示build(true)表示参数已经编码过不要再编码一次。如果 query 里有中文或特殊字符用build(false)让框架处理编码否则会出现双重编码导致下游解析乱码。3.2 请求体的读取与缓存请求体是FluxDataBuffer只能被消费一次。如果你在过滤器里读了请求体做校验下游就拿不到了会报DataBuffer已释放的错误。解决办法是用ServerHttpRequestDecorator把读到的数据缓存下来重新包装成 Flux 往下传。ServerHttpRequestDecorator decorator new ServerHttpRequestDecorator(exchange.getRequest()) { Override public FluxDataBuffer getBody() { return super.getBody().doOnNext(buffer - { byte[] bytes new byte[buffer.readableByteCount()]; buffer.read(bytes); DataBufferUtils.release(buffer); // 缓存 bytes 用于校验 cachedBody.set(bytes); }); } };这段代码有个坑doOnNext里读完后必须release否则内存泄漏。而且cachedBody得用能跨线程访问的容器因为响应式链路可能切换线程。更稳妥的方案是用DataBufferUtils.join把整个 body 聚合起来但那样会失去流式优势大文件上传场景要慎用。我的经验是网关层尽量别碰请求体。鉴权用请求头里的令牌就够了参数校验能放下游就放下游。非要在网关读 body一定要评估请求体大小上限配合spring.codec.max-in-memory-size配置防止大请求把网关内存打爆。3.3 动态路由与路径重写GlobalFilter里可以动态改路由目标比如做灰度发布时根据用户标签把请求导向不同服务实例。核心是改GATEWAY_REQUEST_URL_ATTR这个属性URI originalUri exchange.getAttribute(ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR); URI newUri UriComponentsBuilder.fromUri(originalUri) .host(gray-instance) .port(8081) .build().toUri(); exchange.getAttributes().put(ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR, newUri);这个属性是RouteToRequestUrlFilter读取的所以你的过滤器 order 必须小于它的 order默认 10000否则改完不生效。这也是为什么动态路由类过滤器通常给负数 order。4. 响应阶段的改写与包装4.1 用 ResponseDecorator 改响应体改响应比改请求更绕因为响应是下游写回来的。你需要用ServerHttpResponseDecorator拦截writeWith方法把原始响应体聚合、修改、再写回。ServerHttpResponseDecorator responseDecorator new ServerHttpResponseDecorator(exchange.getResponse()) { Override public MonoVoid writeWith(Publisher? extends DataBuffer body) { return DataBufferUtils.join(body).flatMap(dataBuffer - { byte[] bytes new byte[dataBuffer.readableByteCount()]; dataBuffer.read(bytes); DataBufferUtils.release(dataBuffer); String original new String(bytes, StandardCharsets.UTF_8); String wrapped {\code\:0,\data\: original }; byte[] newBytes wrapped.getBytes(StandardCharsets.UTF_8); DataBuffer buffer bufferFactory().wrap(newBytes); getDelegate().getHeaders().setContentLength(newBytes.length); return getDelegate().writeWith(Mono.just(buffer)); }); } }; return chain.filter(exchange.mutate().response(responseDecorator).build());几个必须注意的点第一DataBufferUtils.join会把整个响应聚合到内存大响应体会撑爆内存所以这种包装只适合小 JSON 响应最好加个长度判断超过阈值就原样透传。第二改完内容必须重设Content-Length否则客户端会按旧长度截断或等待。第三如果响应是流式比如 SSE绝对不能聚合会破坏实时性。4.2 响应头的增删改响应头相对简单在writeWith之前或beforeCommit回调里改都行exchange.getResponse().beforeCommit(() - { HttpHeaders headers exchange.getResponse().getHeaders(); headers.add(X-Response-From, gateway); headers.remove(Server); return Mono.empty(); });beforeCommit是在响应提交前最后的机会适合做安全头注入比如加X-Content-Type-Options、X-Frame-Options这类。注意Server头有些容器会强制加回来网关层删了不一定彻底得看底层实现。4.3 响应状态码的改写有时候下游返回 200 但业务码是错误网关想统一转成 HTTP 错误码。可以在writeWith里判断后调setStatusCodeif (original.contains(\code\:500)) { getDelegate().setStatusCode(HttpStatus.INTERNAL_SERVER_ERROR); }但改状态码要谨慎因为一旦响应头已经提交就不能改了。writeWith阶段头还没提交是安全的。如果下游是流式响应头可能早就提交了这时候改状态码无效得靠beforeCommit提前判断。5. 异常处理与容错设计5.1 过滤器内异常的捕获响应式链路里抛异常如果不处理会直接冒到ErrorWebExceptionHandler返回默认错误页。你可以在过滤器里用onErrorResume兜底return chain.filter(exchange) .onErrorResume(ex - { log.error(gateway filter error, ex); exchange.getResponse().setStatusCode(HttpStatus.BAD_GATEWAY); return exchange.getResponse().setComplete(); });但要注意如果异常发生在响应已提交之后setComplete会失败。所以更稳的做法是判断exchange.getResponse().isCommitted()已提交就只记日志不再动响应。5.2 超时与降级网关层做超时控制可以用Mono.timeoutreturn chain.filter(exchange) .timeout(Duration.ofMillis(3000)) .onErrorResume(TimeoutException.class, ex - { exchange.getResponse().setStatusCode(HttpStatus.GATEWAY_TIMEOUT); return exchange.getResponse().setComplete(); });超时时间要根据下游 P99 来定一般设成 P99 的 1.5 到 2 倍。设太短会误杀正常慢请求设太长会拖垮网关线程。注意 WebFlux 是非阻塞的超时不会占线程但会占连接资源所以也不能无限长。5.3 常见异常速查表异常现象可能原因排查方向DataBufferalready released请求体被多次消费检查是否重复读 body用 Decorator 缓存响应被截断改了 body 没改 Content-Length重设Content-Length过滤器不生效order 太大被覆盖检查 order 是否小于目标过滤器内存持续上涨大响应体被 join 聚合加长度阈值超限透传顺序随机order 值冲突统一规划 order 区间避免重复6. 性能与线程安全的实操心得6.1 绝对不要阻塞这是最重要的一条。GlobalFilter跑在 Netty 事件循环线程上一个阻塞操作就能卡住整条链路。以下操作都是禁忌Thread.sleep、同步 HTTP 调用、同步数据库查询、future.get()。需要远程调用就用WebClient返回Mono需要查缓存就用响应式客户端。我见过有人在过滤器里用RestTemplate调鉴权服务压测时 QPS 上不去线程全堵在那。换成WebClient后同样的硬件 QPS 翻了好几倍。这个坑非常典型。6.2 共享状态要小心过滤器实例是单例成员变量会被所有请求共享。如果你在成员变量里存请求相关数据必然串数据。所有请求级数据要么放exchange.getAttributes()要么放方法局部变量。exchange是每个请求独立的是唯一安全的请求级容器。// 错误示范 private String currentUser; // 多请求会互相覆盖 // 正确示范 exchange.getAttributes().put(currentUser, userId);6.3 日志埋点的轻量化日志过滤器很常用但写不好会成为性能瓶颈。几个原则用异步 Appender别在过滤器里做字符串拼接用占位符traceId 通过 MDC 传递时注意响应式线程切换会导致 MDC 丢失需要用Hooks.onEachOperator或contextWrite来传播上下文。// 用占位符避免无谓拼接 log.info(path{} cost{}ms status{}, path, cost, status);7. 一个完整的鉴权过滤器实战把前面的点串起来写一个生产可用的鉴权过滤器。需求是从请求头取令牌校验有效性有效则把用户信息注入下游请求头无效则返回 401。Component Order(-100) public class AuthGlobalFilter implements GlobalFilter { private final WebClient authClient; public AuthGlobalFilter(WebClient.Builder builder) { this.authClient builder.baseUrl(http://auth-service).build(); } Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String token exchange.getRequest().getHeaders().getFirst(Authorization); if (token null || token.isEmpty()) { return unauthorized(exchange); } return authClient.post() .uri(/verify) .header(Authorization, token) .retrieve() .bodyToMono(UserInfo.class) .flatMap(user - { ServerHttpRequest request exchange.getRequest().mutate() .header(X-User-Id, user.getId()) .header(X-User-Role, user.getRole()) .build(); return chain.filter(exchange.mutate().request(request).build()); }) .onErrorResume(ex - unauthorized(exchange)); } private MonoVoid unauthorized(ServerWebExchange exchange) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); exchange.getResponse().getHeaders().setContentType(MediaType.APPLICATION_JSON); byte[] body {\code\:401,\msg\:\unauthorized\}.getBytes(StandardCharsets.UTF_8); DataBuffer buffer exchange.getResponse().bufferFactory().wrap(body); return exchange.getResponse().writeWith(Mono.just(buffer)); } }这个过滤器有几个设计取舍值得说。第一鉴权服务调用用WebClient而非阻塞客户端保证非阻塞。第二校验失败统一走unauthorized返回结构化 JSON 而不是空响应方便前端处理。第三用户信息通过请求头注入下游下游服务不用再解析令牌减少重复计算。第四onErrorResume兜住了鉴权服务不可用的情况此时按未授权处理是安全优先的策略。注意X-User-Id这类头必须确保外部无法伪造。做法是在网关入口处先删掉客户端传来的同名头再注入网关校验后的值。否则客户端自己带一个X-User-Id就能冒充任意用户这是很严重的安全漏洞。8. 调试与验证的实用手段写完过滤器怎么验证几个我常用的手段。第一开DEBUG日志看过滤器执行顺序org.springframework.cloud.gateway包下的日志会打印过滤器链。第二用Actuator的/gateway/routes端点确认路由和过滤器绑定情况。第三本地起一个 echo 服务当下游把收到的请求头原样返回一眼就能看出网关改了什么。顺序验证有个小技巧在每个过滤器里往响应头塞一个标记比如X-Filter-Auth: passed然后看响应头里标记的排列就能反推执行顺序。这个方法比看日志直观尤其适合过滤器多的时候。另外GlobalFilter的单元测试可以用MockServerWebExchange配合GatewayFilterChain的 mock 实现断言exchange的变更和chain.filter是否被调用。集成测试则建议用WebTestClient打真实网关端口覆盖完整链路。9. 几个容易忽略的边界情况最后聊几个边界。第一OPTIONS预检请求通常不带令牌鉴权过滤器要放行否则跨域预检直接失败。第二WebSocket 升级请求的过滤器行为和普通 HTTP 不同响应装饰器可能不生效涉及 WebSocket 的路由要单独测试。第三exchange.getResponse().setComplete()和writeWith不能混用前者用于无响应体场景后者用于有响应体用错会报响应已提交。还有一个隐蔽的坑过滤器里如果用了ThreadLocal在响应式线程切换后会拿到错误的值甚至 null。所有跨异步边界的上下文传递都要走 Reactor 的Context用contextWrite写入、deferContextual读取。这个和 MDC 传播是同一类问题本质是响应式模型下没有“线程绑定”这回事。把这些边界都考虑到你的GlobalFilter才算真正能在生产环境扛住流量。我个人踩过最深的坑就是请求体重复消费和响应体聚合导致的内存问题这两个都是上线后才暴露的压测时不一定能发现因为压测流量往往请求体很小。真实业务里一个文件上传接口就能把网关打挂所以涉及 body 的操作务必加大小限制和降级逻辑。