フィルター

フィルターは、ハンドラーが検索されるよりも前に、すべてのリクエストの前後で実行されます。WebFilter を実装する Bean を宣言すると、スターターはそうした Bean をすべて @Order 順に実行し、その後にハンドラーを実行します。

使う理由

一つのエンドポイントではなく、すべてのリクエストに関わる処理があります。

フィルターはすべてのリクエストを見ます。コントローラーで終わるもの、静的ファイルで終わるもの、404 で終わるもの、CORS のプリフライトで終わるものもです。セキュリティスターターのフィルターチェーンも、そうしたフィルターの一つです。

選ばれたメソッドやその戻り値を手元に置いて行う、コントローラーに結び付いた処理には、HandlerInterceptor のほうが適しています。WebMvcConfigurer を参照してください。

例

import 'dart:math';

import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

const log = SpringLog('app.web');

// すべての応答に、ログを検索できる ID を付ける。
@Component()
@Order(Ordered.highestPrecedence + 100)
class RequestIdFilter implements WebFilter {
  final _random = Random();

  @override
  Future<void> doFilter(
    ServerHttpRequest request,
    ServerHttpResponse response,
    WebFilterChain chain,
  ) {
    final id = request.headers['X-Request-Id'] ??
        _random.nextInt(1 << 32).toRadixString(16);
    request.attributes['requestId'] = id;
    response.headers.set('X-Request-Id', id);
    return chain.doFilter(request, response);
  }
}

// ロードバランサーのヘルスチェックを除き、リクエストを計測する。
@Component()
class TimingFilter extends OncePerRequestFilter {
  @override
  bool shouldNotFilter(ServerHttpRequest request) => request.path == '/health';

  @override
  Future<void> doFilterInternal(
    ServerHttpRequest request,
    ServerHttpResponse response,
    WebFilterChain chain,
  ) async {
    final watch = Stopwatch()..start();
    try {
      await chain.doFilter(request, response);
    } finally {
      log.info('${request.method.value} ${request.path} '
          '${response.statusCode} in ${watch.elapsedMilliseconds} ms');
    }
  }
}

// 自分で応答するフィルター: キーがなければサービスしない。
@Component()
@Order(10)
class ApiKeyFilter extends OncePerRequestFilter {
  ApiKeyFilter(@Value(r'${shop.api-key}') this.key);

  final String key;

  @override
  bool shouldNotFilter(ServerHttpRequest request) =>
      !request.path.startsWith('/api/');

  @override
  Future<void> doFilterInternal(
    ServerHttpRequest request,
    ServerHttpResponse response,
    WebFilterChain chain,
  ) async {
    if (request.headers['X-Api-Key'] != key) {
      // チェーンを呼ばないので、コントローラーは実行されない。
      await response.send(401, 'Missing or wrong API key');
      return;
    }
    await chain.doFilter(request, response);
  }
}

WebFilter

メンバー 意味
Future<void> doFilter(ServerHttpRequest request, ServerHttpResponse response, WebFilterChain chain) リクエストを処理する。次に渡すには、同じオブジェクトかラップしたオブジェクトで chain.doFilter(request, response) を呼ぶ。あるいは response で応答し、チェーンを呼ばずに戻る。
WebFilterChain 意味
Future<void> doFilter(ServerHttpRequest request, ServerHttpResponse response) 次のフィルター、最後のフィルターの後ならハンドラーを実行し、それらが終わると完了する。

ルール:

OncePerRequestFilter

リクエストごとに最大一回だけ処理を行い、一部のリクエストを素通りさせられるフィルターの基底クラスです。一部のパスを飛ばすべきフィルターでは、WebFilter を実装するよりこれを継承してください。

メンバー 意味
bool shouldNotFilter(ServerHttpRequest request) リクエストがこのフィルターを何もされずに通過するかどうか。デフォルトは false。パスやメソッドを除外するにはオーバーライドする。
Future<void> doFilterInternal(request, response, chain) フィルターの処理。扱うリクエストについて doFilter の代わりに呼ばれる。

リクエストに属性 <ClassName>.FILTERED で印を付けます。同じリクエストが再びフィルターを通る場合 (チェーンを二回呼ぶフィルター、独自のフォワード)、二回目はそのままチェーンの先に進みます。

順序

フィルターは Bean の順序どおり、小さい値から実行されます。

組み込みのフィルター:

フィルター 順序 存在する条件 動作
RequestRateFilter Ordered.highestPrecedence ビルドにデバッグ機能 qps がある (spring.web.debug.qps.enabled: true) 自分の isolate のリクエストと、それぞれにかかった時間を数える。他のすべてのフィルターの外側で動く。毎秒のリクエスト数 を参照。
ForwardedHeaderFilter -10000 server.forward-headers-strategy が native または framework 信頼するプロキシからの Forwarded / X-Forwarded-* を適用する: スキーム、ホスト、ポート、クライアントのアドレス。リバースプロキシの背後で を参照。
Actuator の WebEndpointRequestFilter -5000 Actuator スターターを使う場合 自身のリクエスト。
HttpSessionFilter -1000 常に リクエストのセッションを見つけ、以降のすべてのフィルターで request.getSession() が動くようにする。セッション を参照。
セキュリティスターターのフィルターチェーン (FilterChainProxy) -100 (spring.security.filter.order) セキュリティスターターを使う場合 認証、認可、CSRF、CORS、セキュリティヘッダー。

フィルターの位置は、必要なものに応じて選びます。

リクエストやレスポンスのラップ

フィルターは、別のオブジェクトをチェーンの先に渡せます。ServerHttpRequestDecorator と ServerHttpResponseDecorator は、すべてのメンバーをラップしたオブジェクトに転送します。変更するものだけをオーバーライドしてください。

// /v1/... へのリクエストを /api/... として扱う。
final class _Renamed extends ServerHttpRequestDecorator {
  _Renamed(super.delegate, this.path);

  @override
  final String path;
}

// すべての応答のバイト数を数える。
final class _Counting extends ServerHttpResponseDecorator {
  _Counting(super.delegate);

  var bytes = 0;

  @override
  void add(List<int> data) {
    bytes += data.length;
    super.add(data);
  }

  @override
  void write(String text) => add(utf8.encode(text));
}

@Component()
class LegacyPathFilter implements WebFilter {
  @override
  Future<void> doFilter(request, response, chain) async {
    final path = request.path.startsWith('/v1/')
        ? '/api/${request.path.substring(4)}'
        : request.path;
    final counting = _Counting(response);
    await chain.doFilter(_Renamed(request, path), counting);
    log.debug('${counting.bytes} bytes for $path');
  }
}

(utf8 は dart:convert から来ます。)

リクエストが提供するもの: method、uri、path (コンテキストパスを除く)、headers、queryParameters、cookies、remoteAddress、isSecure、attributes (リクエストの生存期間中のマップ)、principal、body、contentType。レスポンス: statusCode、headers、addCookie、isCommitted、add、write、flush、addStream、close、done、send(status, text)。

フィルターが実行される場所

各リクエストについて、ディスパッチャーは次のことを行います。

  1. リクエストを専用の Zone で実行します。そのため、処理中のどこでも、await をまたいでも、RequestContextHolder.currentRequest がそのリクエストになります。server.request-timeout があれば、リクエストの期限の下でも実行します。
  2. パスから server.context-path を取り除きます (その外のリクエストは、どのフィルターよりも前に 404 になります)。
  3. フィルターを順に実行します。
  4. ハンドラーマッピングに、その順序でハンドラーを問い合わせます。コントローラー (0)、WebSocket エンドポイント (1)、静的リソース (最後) です。どれもなければ 404 です。
  5. ハンドラーの例外に、@ExceptionHandler メソッドとリゾルバーで応答します。

したがって、フィルターにはコンテキストパスを除いた request.path が見え、最終的に何が応答するかに関わらず、その中のすべてのリクエストで実行されます。

// リクエストのために実行されるコードは、パラメーターなしでリクエストを見つけられる。
@Service()
class AuditLog {
  void record(String action) {
    final request = RequestContextHolder.currentRequest;
    log.info('$action by ${request?.principal?.name ?? 'anonymous'} '
        '(${request?.attributes['requestId']})');
  }
}

Spring (Java) との対応

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
class RequestIdFilter extends OncePerRequestFilter {
  @Override
  protected void doFilterInternal(HttpServletRequest request,
      HttpServletResponse response, FilterChain chain)
      throws ServletException, IOException {
    response.setHeader("X-Request-Id", newId());
    chain.doFilter(request, response);
  }
}

重要な違い:

関連項目