ハンドラーマッピング
HandlerMapping は、どのハンドラーがリクエストに応答するかを決めます。ディスパッチャーはすべての HandlerMapping Bean に順に問い合わせ、最初にハンドラーを返したものが採用されます。dispatcherHandlersMappingDescriptions Bean は、Actuator の mappings エンドポイントのために、それらすべてを一覧にします。
使う理由
ほとんどのリクエストはコントローラーメソッドが応答します。しかし、アプリケーションの他の部分もリクエストに応答します。静的ファイル、WebSocket エンドポイント、Actuator エンドポイントです。それぞれがハンドラーマッピングであり、その順序によって、複数が応答できるパスを誰が受け取るかが決まります。たとえば、同じパスの静的ファイルより、コントローラーが常に優先されます。
どのコントローラーも合わないときは、独自のハンドラーマッピングを書きます。実行時に計算するパス、レガシーシステムへのプロキシ、コントローラーの仕組みを使わずに応答するヘルスチェックなどです。
マッピングの一覧は、「このアプリケーションはどの URL を提供し、誰が応答するのか」という問いに、人にもツールにも答えます。
例
コントローラーを使わずに応答し、他のマッピングと一緒に一覧に載るヘルスチェック:
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
@Component()
@Order(10)
class HealthMapping implements HandlerMapping, DescribableHandlerMapping {
static final _handler = FunctionHttpHandler(
(request, response) => response.send(200, 'UP'),
);
@override
HttpHandler? getHandler(ServerHttpRequest request) =>
request.path == '/health' ? _handler : null;
@override
List<Map<String, Object?>> describeHandlers() => [
{'predicate': '/health', 'handler': 'HealthMapping'},
];
}
Actuator が表示するマッピング:
management.endpoints.web.exposure.include=health,mappings
GET /actuator/mappings
{"contexts": {"application": {"mappings": {
"dispatcherHandlers": {"webHandler": [
{"predicate": "{GET [/api/books/{isbn}]}",
"handler": "BookController#find(String)",
"details": {
"handlerMethod": {"className": "BookController", "name": "find",
"descriptor": "(String isbn) -> Future<Book>"},
"requestMappingConditions": {"consumes": [], "headers": [], "methods": ["GET"],
"params": [], "patterns": ["/api/books/{isbn}"], "produces": []}}},
{"predicate": "/health", "handler": "HealthMapping"},
{"predicate": "/**", "handler": "ResourceWebHandler [resources:static/, resources:public/]"},
{"predicate": "(GET && /)", "handler": "WelcomePage [index.html]"}]}},
"parentId": null}}}
ハンドラーの選び方
すべてのリクエストについて、dispatcherHandler Bean (Spring の DispatcherServlet) は次のことを行います。
server.context-pathを取り除きます (その外のパスは 404)。WebFilterBean を順に実行します。@OrderまたはOrderedで並べた各HandlerMappingBean に、順に問い合わせます。- 最初に返されたハンドラーを呼びます。
- どのマッピングもハンドラーを返さなければ 404 で応答します。詳細
No endpoint GET /x.を持つProblemDetailです。
マッピングが例外を投げることもあります。たとえば、既知のパスに別のメソッドで来た場合の 405 です。その場合、ディスパッチャーはそのエラーで応答します。
スターターのマッピング:
| Bean | 順序 | 応答するもの |
|---|---|---|
Actuator スターターの WebEndpointHandlerMapping |
-100 |
Actuator のエンドポイント (/actuator/...) |
requestMappingHandlerMapping |
0 |
@RestController のメソッド |
WebSocket スターターの WebSocketHandlerMapping |
1 |
WebSocket ハンドシェイク |
resourceHandlerMapping |
Ordered.lowestPrecedence - 1 |
静的リソースとウェルカムページ |
順序のないマッピング は Ordered.lowestPrecedence になり、静的リソースよりも後、最後に問い合わせられます。それらより先に問い合わせられるよう、マッピングに @Order を付けてください (または Ordered を実装してください)。
マッピングを書く
abstract interface class HandlerMapping {
FutureOr<HttpHandler?> getHandler(ServerHttpRequest request);
}
- 次のマッピングに試させるには
nullを返します。 HttpHandlerを返します。多くの場合FunctionHttpHandlerです。ハンドラーはレスポンス全体を書かなければなりません。response.send(status, text)は一回の呼び出しでそれを行います。- リクエストはすでにフィルター (セキュリティ、セッション、フォワードヘッダー) を通過しています。
- ハンドラーが投げたエラーは、コントローラーの
@ExceptionHandlerメソッドとHandlerExceptionResolverBean を通して、ProblemDetailで応答されます。エラー を参照してください。 HandlerInterceptorは実行されません。コントローラーメソッドのためのものです。
マッピングの一覧
dispatcherHandlersMappingDescriptions Bean
スターターは、dispatcherHandlersMappingDescriptions という名前の DispatcherHandlersMappingDescriptions Bean を宣言します。これは (spring_web_dart の) MappingDescriptions です。
mappingsNameはdispatcherHandlersです。describeMappings()は{'webHandler': [...]}を返します。DescribableHandlerMappingを実装したディスパッチャーのすべてのハンドラーマッピングの、すべてのハンドラーを、マッピングに問い合わせる順に並べたものです。
形は Spring WebFlux の dispatcherHandlers です。webHandler は Spring でのディスパッチャーの名前です。
Actuator の mappings エンドポイント (spring_boot_starter_actuator) は、すべての MappingDescriptions Bean をその名前の下に置きます。ナビゲーションスターターを使うと、アプリの screens が dispatcherHandlers の隣に現れます。
一覧はコードでも読めます。たとえばテストで:
final mappings = context.getBean<DispatcherHandlersMappingDescriptions>();
final handlers = mappings.describeMappings()['webHandler']! as List<Object?>;
final predicates = [
for (final handler in handlers.cast<Map<String, Object?>>()) handler['predicate'],
];
expect(predicates, contains('/health'));
各エントリーの内容
| キー | 内容 |
|---|---|
predicate |
マッピングが一致するもの。Spring の RequestMappingInfo.toString() と同じ形: {GET [/api/books/{isbn}], produces [application/json]} |
handler |
応答するもの: BookController#find(String)、ResourceWebHandler [resources:static/]、WelcomePage [index.html] |
details.handlerMethod |
コントローラーメソッドの場合: className、name、そして Dart のシグネチャーである descriptor ((String isbn) -> Future<Book>)。Spring の descriptor は JVM のもの。 |
details.requestMappingConditions |
methods、patterns、params と headers (それぞれ {name, value, negated})、consumes と produces (それぞれ {mediaType, negated}) |
predicate には、マッピングが持つ条件だけが Spring の順序で並びます。メソッド、パターン、そして params、headers、consumes、produces です。複数の値は || で連結されます。
独自のマッピングの記述
DescribableHandlerMapping を実装し、ハンドラーごとに一つのマップを返します。メソッドのような条件を持つマッピングでは、describeRequestMapping がコントローラーと同じ形でマップを作ります。
@override
List<Map<String, Object?>> describeHandlers() => [
describeRequestMapping(
handler: 'LegacyProxy',
patterns: ['/legacy/**'],
methods: ['GET', 'POST'],
produces: ['application/xml'],
),
];
// {"predicate": "{[GET, POST] [/legacy/**], produces [application/xml]}", ...}
起動時
コントローラーのマッピングは、ロガー spring.web.mvc にルートを記録します。
logging.level.spring.web.mvc=trace
DEBUG 12 mappings in 'requestMappingHandlerMapping'
TRACE Mapped ...
debug は数を、trace はマッピングごとに一行を表示します。不正なコントローラーは、問題の一覧とともに起動を止めます。起動時のチェック を参照してください。
Spring (Java) との対応
@Component
class HealthMapping extends AbstractHandlerMapping {
@Override
protected Object getHandlerInternal(HttpServletRequest request) {
return "/health".equals(request.getRequestURI()) ? new HealthHandler() : null;
}
}
重要な違い:
HandlerMappingは、HandlerAdapterが呼ぶハンドラーオブジェクトではなく、レスポンスを書くHttpHandlerを返します。- Actuator の一覧は Spring MVC の形 (
dispatcherServlets) ではなく Spring WebFlux の形 (dispatcherHandlers) で、descriptor は Dart のシグネチャーです。 - マッピングが一覧に載るのは、
DescribableHandlerMappingを実装した場合だけです。