
# 起動時のチェック

アプリケーションが起動すると、スターターはすべてのコントローラーとすべての `@ControllerAdvice` Bean をチェックします。誤りがあると、見つかったすべての問題を列挙した 1 つのメッセージとともに起動が止まります。

## 使う理由

そうしなければ、誤ったマッピングはクライアントが呼んだときに初めて、場合によっては本番で表面化します。埋められることのないパス変数、何もバインドできない引数、同じリクエストに対する 2 つのメソッドなどです。起動時にチェックすれば、誤りはテストや開発者のマシンですぐに見つかり、実行ごとに 1 つずつではなく、すべての誤りがまとめて報告されます。

## 例

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class BookFilter {
  String? author;
}

@RestController()
@RequestMapping('/api/books')
class BookController {
  // 引数は {id} を指定しているが、パスにあるのは {isbn}: 2 つの問題。
  @GetMapping('/{isbn}')
  String find(@PathVariable('id') String isbn) => isbn;

  // アノテーションのないクラスの引数: 何もこれを埋められない。
  @GetMapping('/search')
  String search(BookFilter filter) => '';
}

@RestController()
@RequestMapping('/api/orders')
class OrderController {
  @GetMapping()
  List<String> list() => [];

  // list() と同じリクエスト。
  @GetMapping()
  List<String> all() => [];
}
```

アプリケーションは起動せず、ログには次のように表示されます。

```text
Invalid controllers:
  - BookController.find: @PathVariable "id" is not in the path
  - BookController.find: the path variable {isbn} of "/api/books/{isbn}" has no @PathVariable parameter
  - BookController.search: parameter filter (BookFilter) needs @PathVariable, @RequestParam, @RequestHeader, @CookieValue or @RequestBody
  - Ambiguous mapping: OrderController.all and OrderController.list both map GET /api/orders
```

## チェックされること

リストの各行は、`Class.method` の形でメソッドから始まります。チェックとそのメッセージ:

| 誤り | メッセージ |
|---|---|
| 1 つのメソッドに 2 つのマッピングアノテーション | `BookController.find has several mapping annotations; use one (@RequestMapping.of for other methods)` |
| 不正な形式のパスパターン | `BookController.find: <reason> in "<path>"`。たとえば `"**" and "{*name}" may only appear at the end of a pattern`、`Duplicate variable {isbn}`、`Unbalanced "{" in "{isbn"`、`Malformed variable {...}`、`Invalid regex in {...}`、`A {*name} needs a name` |
| メディアタイプでない `produces` または `consumes` | `BookController.find: invalid produces "<value>": <reason>`（または `consumes`） |
| 2 つのバインドアノテーションを持つ引数 | `BookController.find: parameter isbn has several roles` |
| 名前がパスにない `@PathVariable` | `BookController.find: @PathVariable "id" is not in the path` |
| `@PathVariable` のないパスの `{variable}` | `BookController.find: the path variable {isbn} of "/api/books/{isbn}" has no @PathVariable parameter` |
| 単純な値でない型の `@PathVariable`、`@RequestParam`、`@RequestHeader`、`@CookieValue` | `BookController.find: the @RequestParam parameter filter (Filter) is not a simple value; use a String, number, bool, enum, DateTime, Duration, Uri or a List of them` |
| 何も埋められない、アノテーションのない引数 | `BookController.search: parameter filter (Filter) needs @PathVariable, @RequestParam, @RequestHeader, @CookieValue or @RequestBody` |
| 2 つの `@RequestBody` 引数 | `BookController.create has more than one @RequestBody` |
| ストリームの `Future` を返すメソッド | `BookController.changes returns a Future of a stream: return the EventStream / Stream directly` |
| すべてのオリジンでの `@CrossOrigin(allowCredentials: true)` | `BookController.find: @CrossOrigin(allowCredentials: true) needs origins or originPatterns (all origins, "*", cannot be allowed with credentials)` |
| すべてのオリジンでの `@CrossOrigin(allowPrivateNetwork: true)` | `BookController.find: @CrossOrigin(allowPrivateNetwork: true) needs origins or originPatterns (all origins, "*", cannot be allowed to a private network)` |
| 例外、リクエスト、レスポンス、ヘッダーのいずれでもない `@ExceptionHandler` の引数 | `@ExceptionHandler ApiErrors.notFound: parameter extra must be the exception, the ServerHttpRequest, the ServerHttpResponse or the HttpHeaders` |
| 例外の型のない `@ExceptionHandler` | `@ExceptionHandler ApiErrors.timeout: give the exception types (@ExceptionHandler([MyException])) or take the exception as a parameter` |
| 同じリクエストに対する 2 つのメソッド | `Ambiguous mapping: OrderController.all and OrderController.list both map GET /api/orders` |

ルール:

- **「同じリクエスト」** とは、同じ HTTP メソッド、同じパターン、同じ条件を意味します。`consumes`、`produces`、`headers` が異なる 2 つのメソッドはあいまいではなく、リクエストが決めます（`GET /api/orders produces [text/csv]` と `GET /api/orders` は 2 つのマッピングです）。
- **プレースホルダーが先に解決されます。** パスやメディアタイプの `${...}` は設定から埋められてからチェックされます。
- **独自の `HandlerMethodArgumentResolver` がサポートする引数** が報告されることはありません。リゾルバーが先に問い合わせられます（[WebMvcConfigurer](../web-mvc-configurer.md) を参照）。
- `@RequestParam` や `@RequestHeader` の **`Map` の引数**、そして `HttpHeaders` の引数は許されます。単純な値ではありませんが、すべての値を受け取ります。
- **チェックが実行されるタイミング。** すべてのシングルトン Bean が作られた後（`requestMappingHandlerMapping` Bean の `afterSingletonsInstantiated`）、サーバーが起動する前です。問題は 1 つの `StateError` として投げられ、他の起動時エラーと同じように起動を失敗させます。
- **ここでチェックされないもの。** JSON のクラスは、ビルド時にジェネレーターが、実行時に `ObjectMapper` がチェックします。コンストラクター引数のためのサービスが存在するかどうかは、コンテナがチェックします。

通過したマッピングを確認するには、`logging.level.spring.web.mvc=trace` を設定します。debug レベルの件数の後に、それぞれが `Mapped GET /api/books/{isbn} -> BookController.find` としてログに出ます。

## Spring (Java) との対応

Spring が起動時にチェックすることはもっと少なくなります。あいまいなマッピングは起動を失敗させます（`Ambiguous mapping. Cannot map 'orderController' method ...`）。引数のないパス変数、何も埋められない引数、誤った `@ExceptionHandler` は、それに届いたリクエストだけを、多くの場合 500 で失敗させます。

## 関連項目

- [@RequestMapping と @GetMapping](request-mapping.md)
- [@PathVariable](path-variable.md)
- [@ExceptionHandler](../errors/exception-handler.md)
- [CORS](../cors.md)
