フィルター
フィルターは、ハンドラーが検索されるよりも前に、すべてのリクエストの前後で実行されます。WebFilter を実装する Bean を宣言すると、スターターはそうした Bean をすべて @Order 順に実行し、その後にハンドラーを実行します。
使う理由
一つのエンドポイントではなく、すべてのリクエストに関わる処理があります。
- すべての応答とログ行に付けるリクエスト ID。
- アクセスログと計測。
- トークン、API キー、IP 範囲のチェックと、早い段階での拒否。
- セキュリティヘッダーの追加。
- リクエスト (別のパス、プリンシパル) やレスポンス (バイト数の計測) のラップ。
フィルターはすべてのリクエストを見ます。コントローラーで終わるもの、静的ファイルで終わるもの、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) |
次のフィルター、最後のフィルターの後ならハンドラーを実行し、それらが終わると完了する。 |
ルール:
chain.doFilterの前のコード は行きに実行され、後のコード (そのFutureの完了後) は、ハンドラーが応答を書いた後の帰りに実行されます。レスポンスのヘッダーを変更するなら、チェーンの前に行ってください。ボディが始まると、ヘッダーは送信済みです。- チェーンの
Futureを await するか return してください。 どちらもしないフィルターは、リクエストを監視のないまま走らせることになり、そのエラーは失われます。 - チェーンを呼ばない と、リクエストはフィルターで止まります。その場合は応答してください (
response.send(status, text)、または書き込んでclose())。 - フィルターが投げた例外 は
@ExceptionHandlerメソッドとHandlerExceptionResolverBean を飛ばし、デフォルトのエラー応答である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 のリクエストと、それぞれにかかった時間を数える。他のすべてのフィルターの外側で動く。毎秒のリクエスト数 を参照。 |
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、セキュリティヘッダー。 |
フィルターの位置は、必要なものに応じて選びます。
- クライアントの実際のアドレスやスキームが必要:
-10000の後。 - セッションを使う:
-1000の後。 - ログイン中のユーザー (
request.principal) が必要:-100の後。 - セキュリティチェーンが拒否するものも含め、すべてのリクエストを見る必要がある (アクセスログ):
-100の前。
リクエストやレスポンスのラップ
フィルターは、別のオブジェクトをチェーンの先に渡せます。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)。
フィルターが実行される場所
各リクエストについて、ディスパッチャーは次のことを行います。
- リクエストを専用の
Zoneで実行します。そのため、処理中のどこでも、awaitをまたいでも、RequestContextHolder.currentRequestがそのリクエストになります。server.request-timeoutがあれば、リクエストの期限の下でも実行します。 - パスから
server.context-pathを取り除きます (その外のリクエストは、どのフィルターよりも前に404になります)。 - フィルターを順に実行します。
- ハンドラーマッピングに、その順序でハンドラーを問い合わせます。コントローラー (
0)、WebSocket エンドポイント (1)、静的リソース (最後) です。どれもなければ404です。 - ハンドラーの例外に、
@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);
}
}
重要な違い:
- フィルターは非同期メソッドを一つ持つ
WebFilterBean で、サーブレットのFilterよりも WebFlux のWebFilterに近いものです。 FilterRegistrationBeanはありません。フィルターはすべてのリクエストに適用されます。shouldNotFilterで制限してください。- ラッパーは
HttpServletRequestWrapperではなく、ServerHttpRequestDecoratorとServerHttpResponseDecoratorです。 RequestContextHolder.currentRequestは、スレッドローカルではなくZoneによって、awaitをまたいでリクエストを追跡します。- フィルターが投げた例外はデフォルトのエラー応答になります。Spring と同じく、
@ExceptionHandlerメソッドはそれを見ません。
関連項目
- WebMvcConfigurer: インターセプター
- セッション
- CORS
- リバースプロキシの背後で
- ハンドラーマッピング
- @Component