コントローラーのアノテーション

これらのアノテーションは、クラスを 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 のサブタイプかどうかを調べられないためです。

関連項目