コントローラーのアノテーション
これらのアノテーションは、クラスを Web コントローラーにし、その応答とエラーの形を決めます。Web サーバー (spring_boot_starter_web) がそれらを読みます。他のパッケージがサーバーに依存せずにそれらを参照できるよう、このパッケージに置かれています。
使う理由
エンドポイントを追加するライブラリや、アプリケーションの API を列挙するツールには、アノテーションは必要ですが、動作中のサーバーは不要です。それらをここに置くことで、そうした依存関係を軽く保てます。
例
@RestController()
@RequestMapping('/api/books')
@CrossOrigin(origins: ['https://shop.neon.books']) // ショップのページから呼べる
class BookController {
BookController(this.books);
final BookService books;
// POST /api/books は 200 ではなく 201 Created で応答する。
@PostMapping()
@ResponseStatus(HttpStatus.created)
Future<Book> create(@RequestBody() Book book) => books.create(book);
// すでにある本は、上のすべてのメソッドで 409 になる。
@ExceptionHandler()
ProblemDetail duplicate(DuplicateBookException e) =>
ProblemDetail.forStatusAndDetail(HttpStatus.conflict, e.message);
}
アノテーション
| アノテーション | 付ける場所 | Spring | 意味 |
|---|---|---|---|
@RestController([name]) |
クラス | @RestController |
マッピングしたメソッドがリクエストに応答する Bean。戻り値がレスポンスボディになる。 |
@RequestMapping('/api/books') |
クラス | 同じ | すべてのメソッドのパスのプレフィックスと、それらすべての produces、consumes、headers。 |
@ResponseStatus(HttpStatus.created, reason: ...) |
メソッド、コントローラークラス | 同じ | 通常の応答のステータス。reason があると結果は無視され、応答はその理由を詳細とするエラーになる。 |
@ExceptionHandler([types]) |
メソッド | 同じ | コントローラーのメソッド (アドバイスではすべてのコントローラーのもの) が投げた例外を処理する。例外パラメーターの型、または types が対象を選び、実行時の型の完全一致で照合する。 |
@ControllerAdvice([name])、@RestControllerAdvice([name]) |
クラス | 同じ | すべてのコントローラーのための例外ハンドラー。@Order の順に試される。 |
@CrossOrigin(origins:, originPatterns:, methods:, allowedHeaders:, exposedHeaders:, allowCredentials:, allowPrivateNetwork:, maxAge:) |
クラス、メソッド | 同じ | 他のオリジンの Web ページがコントローラーを呼べるようにする (CORS)。maxAge は秒。 |
引数のない @CrossOrigin() は、Spring と同じく、すべてのオリジン、ハンドラーがマッピングされたメソッド (@DeleteMapping なら DELETE、@GetMapping なら GET だけ)、すべてのリクエストヘッダー、クレデンシャルなし、30 分のプリフライトのキャッシュを許可します。
サーバーがそれらを適用する方法は Web スターターで説明しています: @RestController、@ExceptionHandler、@ControllerAdvice、CORS。
Spring (Java) との対応
@RestController
@RequestMapping("/api/books")
@CrossOrigin(origins = "https://shop.neon.books")
class BookController { ... }
アノテーションは同じです。@ExceptionHandler(types) は実行時の型の完全一致で照合します。Dart は実行時に、ある Type が別の Type のサブタイプかどうかを調べられないためです。