起動時のチェック

アプリケーションが起動すると、スターターはすべてのコントローラーとすべての @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

ルール:

通過したマッピングを確認するには、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 で失敗させます。

関連項目