グローバルフィルター

GlobalFilter インターフェースには、GatewayFilter と同じ署名があります。これらは、すべてのルートに条件付きで適用される特別なフィルターです。

このインターフェースとその使用箇所は、将来のマイルストーンリリースで変更される可能性があります。

グローバルフィルターと `GatewayFilter` の組み合わせオーダー

リクエストがルートに一致すると、フィルタリング Web ハンドラーは GlobalFilter のすべてのインスタンスと GatewayFilter のすべてのルート固有のインスタンスをフィルターチェーンに追加します。この結合されたフィルターチェーンは、getOrder() メソッドを実装することで設定できる org.springframework.core.Ordered インターフェースによってソートされます。

Spring Cloud Gateway は、フィルターロジック実行の「前」フェーズと「後」フェーズを区別するため（使い方を参照）、優先順位が最も高いフィルターは、「前」フェーズの最初と「後」フェーズの最後です。

次のリストは、フィルターチェーンを構成します。

ExampleConfiguration.java

@Bean
public GlobalFilter customFilter() {
    return new CustomGlobalFilter();
}

public class CustomGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        log.info("custom global filter");
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -1;
    }
}

ゲートウェイメトリクスフィルター

ゲートウェイメトリクスを有効にするには、プロジェクトの依存関係として spring-boot-starter-actuator を追加します。次に、デフォルトで、spring.cloud.gateway.metrics.enabled プロパティが false に設定されていない限り、ゲートウェイメトリクスフィルターが実行されます。このフィルターは、次のタグを持つ spring.cloud.gateway.requests という名前のタイマーメトリクスを追加します。

routeId: ルート ID。
routeUri: API がルーティングされる URI。
outcome: HttpStatus.Series (Javadoc) によって分類された結果。
status: クライアントに返されたリクエストの HTTP ステータス。
httpStatusCode: クライアントに返されたリクエストの HTTP ステータス。
httpMethod: リクエストに使用される HTTP メソッド。

さらに、spring.cloud.gateway.metrics.tags.path.enabled プロパティ (デフォルトでは false) を介して、パスタグを使用して追加のメトリクスをアクティブ化できます。

path: リクエストのパス。

これらのメトリクスは、/actuator/metrics/spring.cloud.gateway.requests からスクレイピングできるようになり、Prometheus と簡単に統合して Grafana ダッシュボードを作成できます。

プロメテウスエンドポイントを有効にするには、プロジェクトの依存関係として micrometer-registry-prometheus を追加します。

ローカルレスポンスキャッシュフィルター

関連するプロパティが有効になっている場合、LocalResponseCache が実行されます。

spring.cloud.gateway.global-filter.local-response-cache.enabled: すべてのルートのグローバルキャッシュを有効にします
spring.cloud.gateway.filter.local-response-cache.enabled: 関連付けられたフィルターをアクティブにして、ルートレベルで使用します

この機能は、次の条件を満たすすべてのレスポンスに対して Caffeine を使用してローカルキャッシュを有効にします。

リクエストはボディレス GET です。
レスポンスには、HTTP 200 (OK)、HTTP 206 (部分的なコンテンツ)、または HTTP 301 (完全に移動) のいずれかのステータスコードがあります。
HTTP Cache-Control ヘッダーはキャッシングを許可します (つまり、次のいずれの値も持たないことを意味します: リクエストに存在する no-store およびレスポンスに存在する no-store または private )。

次の 2 つの構成パラメーターを受け入れます。

spring.cloud.gateway.filter.local-response-cache.size: このルートのエントリを削除するためのキャッシュの最大サイズを設定します (KB、MB、GB 単位)。
spring.cloud.gateway.filter.local-response-cache.time-to-live キャッシュエントリの有効期限を設定します (秒は s、分は m、時間は h で表されます)。

これらのパラメーターのいずれも構成されていないが、グローバルフィルターが有効になっている場合、デフォルトでは、キャッシュされたレスポンスに対して 5 分間の存続時間が構成されます。

このフィルターは、HTTP Cache-Control ヘッダーの max-age 値の自動計算も実装します。元のレスポンスに max-age が存在する場合、値は timeToLive 構成パラメーターで設定された秒数で書き換えられます。後続の呼び出しでは、この値は、レスポンスが期限切れになるまでの残りの秒数で再計算されます。

spring.cloud.gateway.global-filter.local-response-cache.enabled を false に設定すると、すべてのルートのローカルレスポンスキャッシュが非アクティブになり、LocalResponseCache フィルターはルートレベルでこの機能を使用できるようにします。

この機能を有効にするには、プロジェクトの依存関係として com.github.ben-manes.caffeine:caffeine と spring-boot-starter-cache を追加します。

プロジェクトでカスタム CacheManager Bean を作成する場合は、@Primary でマークするか、@Qualifier を使用して注入する必要があります。

フォワードルーティングフィルター

ForwardRoutingFilter は、交換属性 ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR で URI を探します。URL に forward スキーム（forward:///localendpoint など）がある場合、URL は Spring DispatcherHandler を使用してリクエストを処理します。リクエスト URL のパス部分は、フォワード URL のパスで上書きされます。変更されていない元の URL は、ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR 属性のリストに追加されます。

Netty ルーティングフィルター

Netty ルーティングフィルターは、ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR 交換属性にある URL に http または https スキームがある場合に実行されます。Netty HttpClient を使用して、ダウンストリームプロキシリクエストを行います。レスポンスは、後のフィルターで使用するために ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR 交換属性に入れられます。(同じ機能を実行するが Netty を必要としない実験的な WebClientHttpRoutingFilter もあります。)

Netty 書き込みレスポンスフィルター

ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR 交換属性に Netty HttpClientResponse がある場合、NettyWriteResponseFilter が実行されます。他のすべてのフィルターが完了した後に実行され、プロキシレスポンスをゲートウェイクライアントレスポンスに書き戻します。(同じ機能を実行するが Netty を必要としない実験的な WebClientWriteResponseFilter もあります。)

`ReactiveLoadBalancerClientFilter`

ReactiveLoadBalancerClientFilter は、ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR という名前の交換属性で URI を探します。URL に lb スキーム（lb://myservice など）がある場合、URL は Spring Cloud ReactorLoadBalancer を使用して名前（この例では myservice）を実際のホストとポートに解決し、同じ属性の URI を置き換えます。変更されていない元の URL は、ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR 属性のリストに追加されます。フィルターは、ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR 属性も調べて、lb と等しいかどうかを確認します。その場合、同じルールが適用されます。次のリストは、ReactiveLoadBalancerClientFilter を構成します。

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: myRoute
        uri: lb://service
        predicates:
        - Path=/service/**

デフォルトでは、サービスインスタンスが ReactorLoadBalancer で見つからない場合、503 が返されます。spring.cloud.gateway.loadbalancer.use404=true を設定することにより、404 を返すようにゲートウェイを構成できます。

ReactiveLoadBalancerClientFilter から返された ServiceInstance の isSecure 値は、ゲートウェイに対して行われたリクエストで指定されたスキームをオーバーライドします。例: リクエストが HTTPS を介してゲートウェイに到着したが、ServiceInstance が安全でないことを示している場合、ダウンストリームリクエストは HTTP を介して行われます。逆の状況も当てはまります。ただし、ゲートウェイ構成のルートに GATEWAY_SCHEME_PREFIX_ATTR が指定されている場合、プレフィックスは削除され、ルート URL からの結果のスキームが ServiceInstance 構成を上書きします。

ゲートウェイは、すべての LoadBalancer 機能をサポートします。Spring Cloud Commons ドキュメントでそれらについてさらに読むことができます。

`RouteToRequestUrl` フィルター

ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR 交換属性に Route オブジェクトがある場合、RouteToRequestUrlFilter が実行されます。リクエスト URI に基づいて新しい URI を作成しますが、Route オブジェクトの URI 属性で更新されます。新しい URI は ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR 交換属性に配置されます。

URI に lb:ws://serviceid などのスキームプレフィックスがある場合、lb スキームは URI から削除され、後でフィルターチェーンで使用するために ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR に配置されます。

Websocket ルーティングフィルター

ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR 交換属性にある URL に ws または wss スキームがある場合、WebSocket ルーティングフィルターが実行されます。Spring WebSocket インフラストラクチャを使用して、WebSocket リクエストをダウンストリームに転送します。

URI の前に lb:ws://serviceid などの lb を付けることで、WebSocket の負荷を分散できます。

通常の HTTP のフォールバックとして SockJS [GitHub] (英語) を使用する場合は、通常の HTTP ルートと WebSocket ルートを構成する必要があります。

次のリストは、WebSocket ルーティングフィルターを構成します。

application.yml

spring:
  cloud:
    gateway:
      routes:
      # SockJS route
      - id: websocket_sockjs_route
        uri: http://localhost:3001
        predicates:
        - Path=/websocket/info/**
      # Normal Websocket route
      - id: websocket_route
        uri: ws://localhost:3001
        predicates:
        - Path=/websocket/**

交換をルーティング済みとしてマークする

ゲートウェイが ServerWebExchange をルーティングした後、交換属性に gatewayAlreadyRouted を追加することにより、その交換を「ルーティング済み」としてマークします。リクエストがルーティング済みとしてマークされると、他のルーティングフィルターはリクエストを再度ルーティングせず、基本的にフィルターをスキップします。交換をルーティング済みとしてマークしたり、交換がすでにルーティングされているかどうかを確認したりするために使用できる便利なメソッドがあります。

ServerWebExchangeUtils.isAlreadyRouted は、ServerWebExchange オブジェクトを受け取り、それが「ルーティング」されているかどうかを確認します。
ServerWebExchangeUtils.setAlreadyRouted は ServerWebExchange オブジェクトを受け取り、それを「ルーティング済み」としてマークします。

グローバルフィルター