
# フィルター

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

## 使う理由

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

- すべての応答とログ行に付けるリクエスト ID。
- アクセスログと計測。
- トークン、API キー、IP 範囲のチェックと、早い段階での拒否。
- セキュリティヘッダーの追加。
- リクエスト (別のパス、プリンシパル) やレスポンス (バイト数の計測) のラップ。

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

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

## 例

```dart
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)` | 次のフィルター、最後のフィルターの後ならハンドラーを実行し、それらが終わると完了する。 |

ルール:

- **`chain.doFilter` の前のコード** は行きに実行され、**後のコード** (その `Future` の完了後) は、ハンドラーが応答を書いた後の帰りに実行されます。レスポンスのヘッダーを変更するなら、チェーンの前に行ってください。ボディが始まると、ヘッダーは送信済みです。
- **チェーンの `Future` を await するか return してください。** どちらもしないフィルターは、リクエストを監視のないまま走らせることになり、そのエラーは失われます。
- **チェーンを呼ばない** と、リクエストはフィルターで止まります。その場合は応答してください (`response.send(status, text)`、または書き込んで `close()`)。
- **フィルターが投げた例外** は `@ExceptionHandler` メソッドと `HandlerExceptionResolver` Bean を飛ばし、デフォルトのエラー応答である `ProblemDetail` になります。
- **ハンドラーの例外** は、まずチェーンの内側で `@ExceptionHandler` メソッドとリゾルバーに渡されます。そのどれかが応答した場合、フィルターには完了したエラーレスポンスが見えます。どれも応答しなかった場合、例外は `chain.doFilter` から出てフィルターを通り抜け (`try`/`finally` で見える)、最後にデフォルトの `ProblemDetail` で応答されます。
- **フィルターは Bean です。** 他の Bean やプロパティを注入できます。

## `OncePerRequestFilter`

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

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

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

## 順序

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

- クラスに `@Order(n)` を付けるか、クラスが `Ordered` (`int get order`) を実装します。
- `Ordered.highestPrecedence` (最小の `int`) が最初に実行されます。順序のないフィルターは最後 (`Ordered.lowestPrecedence`)、順序のあるものすべての後に実行されます。
- オフセット (`Ordered.highestPrecedence + 100`) や小さな数を使い、間に余裕を残してください。

組み込みのフィルター:

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

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

- クライアントの実際のアドレスやスキームが必要: `-10000` の後。
- セッションを使う: `-1000` の後。
- ログイン中のユーザー (`request.principal`) が必要: `-100` の後。
- セキュリティチェーンが拒否するものも含め、すべてのリクエストを見る必要がある (アクセスログ): `-100` の前。

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

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

```dart
// /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` が見え、最終的に何が応答するかに関わらず、その中のすべてのリクエストで実行されます。

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

## Spring (Java) との対応

```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);
  }
}
```

重要な違い:

- フィルターは非同期メソッドを一つ持つ `WebFilter` Bean で、サーブレットの `Filter` よりも WebFlux の `WebFilter` に近いものです。
- `FilterRegistrationBean` はありません。フィルターはすべてのリクエストに適用されます。`shouldNotFilter` で制限してください。
- ラッパーは `HttpServletRequestWrapper` ではなく、`ServerHttpRequestDecorator` と `ServerHttpResponseDecorator` です。
- `RequestContextHolder.currentRequest` は、スレッドローカルではなく `Zone` によって、`await` をまたいでリクエストを追跡します。
- フィルターが投げた例外はデフォルトのエラー応答になります。Spring と同じく、`@ExceptionHandler` メソッドはそれを見ません。

## 関連項目

- [WebMvcConfigurer](web-mvc-configurer.md): インターセプター
- [セッション](sessions.md)
- [CORS](cors.md)
- [リバースプロキシの背後で](server/reverse-proxy.md)
- [ハンドラーマッピング](server/handler-mappings.md)
- [@Component](../spring-core-dart/beans/component.md)
