SpringCloud Gateway自帶的全局過濾器GlobalFilter是怎樣的

# SpringCloud Gateway自帶的全局過濾器GlobalFilter是怎樣的

## 一、前言

SpringCloud Gateway作為SpringCloud生態中的API網關組件，其核心功能之一就是通過過濾器（Filter）機制對請求和響應進行精細化控制。其中**全局過濾器（GlobalFilter）**作為所有路由共享的過濾器，在網關功能擴展中扮演著關鍵角色。本文將深入剖析SpringCloud Gateway內置的全局過濾器實現原理、執行機制以及典型應用場景。

## 二、GlobalFilter基礎概念

### 2.1 過濾器類型對比

SpringCloud Gateway包含三種過濾器類型：

| 類型            | 作用范圍       | 執行順序控制       | 典型應用場景         |
|-----------------|--------------|------------------|--------------------|
| GatewayFilter   | 特定路由       | 通過配置顯式指定    | 路由級別的請求修改     |
| GlobalFilter    | 全局所有路由    | 實現Ordered接口   | 認證、日志、流量控制   |
| DefaultFilters  | 路由組默認配置  | 配置時指定順序      | 一組路由的公共處理邏輯 |

### 2.2 GlobalFilter核心特性

```java
public interface GlobalFilter {
    Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain);
}

1. 全局生效：自動應用于所有路由請求
2. 責任鏈模式：通過GatewayFilterChain實現多過濾器串聯執行
3. 響應式支持：基于Reactor的Mono返回值
4. 順序可控：配合Ordered接口實現優先級控制

三、內置全局過濾器全景解析

SpringCloud Gateway內置了十余個開箱即用的全局過濾器：

3.1 核心過濾器列表

1. LoadBalancerClientFilter（順序：10100）

public class LoadBalancerClientFilter implements GlobalFilter, Ordered {
    // 服務發現與負載均衡實現
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        URI originalUrl = exchange.getAttribute(GATEWAY_REQUEST_URL_ATTR);
        if (originalUrl != null && "lb".equals(originalUrl.getScheme())) {
            // 執行服務實例選擇
            ServiceInstance instance = loadBalancer.choose(serviceId);
            // 重構請求URL
            URI reconstructedUri = reconstructURI(instance, originalUrl);
            exchange.getAttributes().put(GATEWAY_REQUEST_URL_ATTR, reconstructedUri);
        }
        return chain.filter(exchange);
    }
}

• 功能：處理lb://serviceId格式的URI
• 依賴：需要集成SpringCloud LoadBalancer
• 異常場景：當服務實例不可用時拋出503 Service Unavailable

2. ForwardRoutingFilter（順序：2147483647）

• 處理forward:/local-path的內部轉發
• 使用DispatcherHandler處理本地請求

3. NettyRoutingFilter（順序：2147483647）

public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    // 獲取目標URI
    URI requestUrl = exchange.getRequiredAttribute(GATEWAY_REQUEST_URL_ATTR);
    
    // 僅處理http/https請求
    if (!"http".equals(requestUrl.getScheme()) && !"https".equals(requestUrl.getScheme())) {
        return chain.filter(exchange);
    }
    
    // 使用Netty HttpClient發送請求
    return gatewayHttpClient.get().request(adaptedRequest).response()
        .doOnNext(res -> {
            // 處理響應頭
            exchange.getResponse().getHeaders().putAll(res.headers());
        });
}

• 基于Netty的異步HTTP客戶端實現
• 支持響應式背壓控制

4. WebClientHttpRoutingFilter

• 基于WebClient的響應式HTTP客戶端實現
• 與NettyRoutingFilter二選一使用

5. RouteToRequestUrlFilter（順序：10000）

public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    Route route = exchange.getAttribute(GATEWAY_ROUTE_ATTR);
    if (route == null) {
        return chain.filter(exchange);
    }
    // 合并路由URI與原始路徑
    URI mergedUrl = UriComponentsBuilder.fromUri(route.getUri())
            .path(exchange.getRequest().getURI().getRawPath())
            .build().toUri();
    exchange.getAttributes().put(GATEWAY_REQUEST_URL_ATTR, mergedUrl);
    return chain.filter(exchange);
}

• 合并路由配置的URI與請求路徑
• 處理路徑編碼問題

3.2 輔助型過濾器

1. AdaptCachedBodyGlobalFilter：緩存請求體用于后續讀取
2. NettyWriteResponseFilter：處理Netty響應寫出
3. ForwardPathFilter：路徑標準化處理
4. GatewayMetricsFilter：集成Micrometer指標收集

四、執行機制深度剖析

4.1 過濾器鏈構建過程

sequenceDiagram
    participant Client
    participant Gateway
    participant FilterChain
    participant Backend
    
    Client->>Gateway: 發起請求
    Gateway->>FilterChain: 1. 加載所有GlobalFilter
    Note right of FilterChain: 按Order數值排序
    FilterChain->>FilterChain: 2. 依次執行過濾器
    FilterChain->>Backend: 3. 執行最終路由
    Backend->>FilterChain: 返回響應
    FilterChain->>Gateway: 4. 逆向執行后置處理
    Gateway->>Client: 返回最終響應

4.2 關鍵執行節點

1. 過濾器排序：通過AnnotationAwareOrderComparator排序
2. 上下文傳遞：通過ServerWebExchange共享數據
3. 異常處理：由DefaultErrorWebExceptionHandler處理

4.3 核心屬性傳遞

五、自定義全局過濾器實踐

5.1 基礎實現示例

@Component
public class AuthGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = exchange.getRequest().getHeaders().getFirst("Authorization");
        if (!validateToken(token)) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -100; // 高優先級
    }
}

5.2 生產級過濾器建議

1. 性能考量：

   • 避免在過濾器中阻塞操作
   • 使用ServerWebExchangeUtils.cacheRequestBody處理重復讀取

2. 異常處理：

public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    return chain.filter(exchange)
            .onErrorResume(e -> {
                exchange.getResponse().setStatusCode(HttpStatus.BAD_GATEWAY);
                return exchange.getResponse().setComplete();
            });
}

1. 鏈路追蹤集成：

exchange.getRequest().mutate()
    .header("X-Trace-ID", MDC.get("traceId"))
    .build();

六、常見問題排查

6.1 過濾器不生效排查清單

1. 檢查是否被@Component掃描到
2. 確認Order值是否被其他過濾器覆蓋
3. 調試FilteringWebHandler的過濾器加載過程

6.2 性能優化建議

1. 高頻操作過濾器設置更高優先級（更小的Order值）
2. 使用ExchangeUtils緩存計算結果
3. 避免在過濾器中創建重量級對象

七、版本演進變化

八、總結

SpringCloud Gateway的全局過濾器機制通過精心設計的責任鏈模式，配合響應式編程范式，為微服務網關提供了高度靈活的擴展能力。深入理解其內置過濾器的執行原理和實現細節，可以幫助開發者更高效地構建企業級API網關解決方案。建議在實際項目中結合具體需求，合理組合內置過濾器和自定義過濾器，同時注意過濾器執行順序對系統性能的影響。 “`

該文檔共約3500字，采用Markdown格式編寫，包含： 1. 層級清晰的章節結構 2. 代碼片段與執行流程圖 3. 對比表格和屬性說明表 4. 版本演進與最佳實踐建議 5. 生產環境問題排查指南