
# ハンドラーマッピング

`HandlerMapping` は、どのハンドラーがリクエストに応答するかを決めます。ディスパッチャーはすべての `HandlerMapping` Bean に順に問い合わせ、最初にハンドラーを返したものが採用されます。`dispatcherHandlersMappingDescriptions` Bean は、Actuator の `mappings` エンドポイントのために、それらすべてを一覧にします。

## 使う理由

ほとんどのリクエストはコントローラーメソッドが応答します。しかし、アプリケーションの他の部分もリクエストに応答します。静的ファイル、WebSocket エンドポイント、Actuator エンドポイントです。それぞれがハンドラーマッピングであり、その順序によって、複数が応答できるパスを誰が受け取るかが決まります。たとえば、同じパスの静的ファイルより、コントローラーが常に優先されます。

どのコントローラーも合わないときは、独自のハンドラーマッピングを書きます。実行時に計算するパス、レガシーシステムへのプロキシ、コントローラーの仕組みを使わずに応答するヘルスチェックなどです。

マッピングの一覧は、「このアプリケーションはどの URL を提供し、誰が応答するのか」という問いに、人にもツールにも答えます。

## 例

コントローラーを使わずに応答し、他のマッピングと一緒に一覧に載るヘルスチェック:

```dart
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 が表示するマッピング:

```properties
management.endpoints.web.exposure.include=health,mappings
```

```text
GET /actuator/mappings
```

```json
{"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` を実装してください)。

### マッピングを書く

```dart
abstract interface class HandlerMapping {
  FutureOr<HttpHandler?> getHandler(ServerHttpRequest request);
}
```

- 次のマッピングに試させるには `null` を返します。
- `HttpHandler` を返します。多くの場合 `FunctionHttpHandler` です。ハンドラーはレスポンス全体を書かなければなりません。`response.send(status, text)` は一回の呼び出しでそれを行います。
- リクエストはすでにフィルター (セキュリティ、セッション、フォワードヘッダー) を通過しています。
- ハンドラーが投げたエラーは、コントローラーの `@ExceptionHandler` メソッドと `HandlerExceptionResolver` Bean を通して、`ProblemDetail` で応答されます。[エラー](../errors/index.md) を参照してください。
- `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` の隣に現れます。

一覧はコードでも読めます。たとえばテストで:

```dart
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` がコントローラーと同じ形でマップを作ります。

```dart
@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` にルートを記録します。

```properties
logging.level.spring.web.mvc=trace
```

```text
DEBUG 12 mappings in 'requestMappingHandlerMapping'
TRACE Mapped ...
```

`debug` は数を、`trace` はマッピングごとに一行を表示します。不正なコントローラーは、問題の一覧とともに起動を止めます。[起動時のチェック](../controllers/startup-checks.md) を参照してください。

## Spring (Java) との対応

```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` を実装した場合だけです。

## 関連項目

- [コントローラー](../controllers/index.md)
- [@RequestMapping](../controllers/request-mapping.md)
- [フィルター](../filters.md)
- [静的リソース](../static-resources.md)
- [WebSocket](websocket.md)
- [エラー](../errors/index.md)
- [組み込みサーバー](index.md)
