起動時のチェック
アプリケーションが起動すると、スターターはすべてのコントローラーとすべての @ControllerAdvice Bean をチェックします。誤りがあると、見つかったすべての問題を列挙した 1 つのメッセージとともに起動が止まります。
使う理由
そうしなければ、誤ったマッピングはクライアントが呼んだときに初めて、場合によっては本番で表面化します。埋められることのないパス変数、何もバインドできない引数、同じリクエストに対する 2 つのメソッドなどです。起動時にチェックすれば、誤りはテストや開発者のマシンですぐに見つかり、実行ごとに 1 つずつではなく、すべての誤りがまとめて報告されます。
例
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() => [];
}
アプリケーションは起動せず、ログには次のように表示されます。
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 を参照)。 @RequestParamや@RequestHeaderのMapの引数、そしてHttpHeadersの引数は許されます。単純な値ではありませんが、すべての値を受け取ります。- チェックが実行されるタイミング。 すべてのシングルトン Bean が作られた後(
requestMappingHandlerMappingBean の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 で失敗させます。