ハンドラーマッピング

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) は次のことを行います。

  1. server.context-path を取り除きます (その外のパスは 404)。
  2. WebFilter Bean を順に実行します。
  3. @Order または Ordered で並べた各 HandlerMapping Bean に、順に問い合わせます。
  4. 最初に返されたハンドラーを呼びます。
  5. どのマッピングもハンドラーを返さなければ 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);
}

マッピングの一覧

dispatcherHandlersMappingDescriptions Bean

スターターは、dispatcherHandlersMappingDescriptions という名前の DispatcherHandlersMappingDescriptions Bean を宣言します。これは (spring_web_dart の) MappingDescriptions です。

形は 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;
  }
}

重要な違い:

関連項目