マッピングのアノテーション

これらのアノテーションは、メソッドがどの HTTP 呼び出しを表すかを示します。HTTP メソッド、パス、そして各パラメーターの行き先 (パス、クエリ文字列、ヘッダー、Cookie、ボディ) です。サーバーはそれらを使ってリクエストをメソッドにルーティングし、クライアントはそれらを使ってリクエストを組み立てます。

使う理由

両側に一つの語彙があれば、クライアントのインターフェースはコントローラーを一行ずつ写せ、一方を知る開発者はもう一方も分かります。アノテーションは Spring のものを Dart に合わせたものです。

例

// 書籍カタログのクライアント (`@FeignClient` は spring_boot_starter_feign から来る)。
// @RestController も同じアノテーションを使う。
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogClient {
  // GET /books/978-0
  @GetMapping('/books/{isbn}')
  Future<Book> find(@PathVariable('isbn') String isbn);

  // GET /books?q=dune&page=0: `page` はデフォルトがあるため任意。
  @GetMapping('/books')
  Future<List<Book>> search(@RequestParam('q') String query, {@RequestParam() int page = 0});

  // GET /books?author=...&year=...: マップのエントリーごとに一つのクエリパラメーター。毎回の呼び出しにヘッダー。
  @GetMapping.of(path: '/books', headers: ['X-Api-Version=2'])
  Future<List<Book>> filter(@RequestParam() Map<String, Object?> filters);

  // 本を JSON として POST /books し、ログのためにリクエスト ID も付ける。
  @PostMapping.of(path: '/books', consumes: MediaType.applicationJson)
  Future<ResponseEntity<Book>> create(
    @RequestBody() Book book,
    @RequestHeader('X-Request-Id') String requestId,
  );

  // パスなし: クライアントのベースパスそのもの。
  @GetMapping()
  Future<List<Book>> all({@RequestParam('sort') String sort = 'title'});

  // 名前がなければ、{isbn} は isbn という名前のパラメーターにバインドされる。
  @DeleteMapping('/books/{isbn}')
  Future<void> delete(@PathVariable() String isbn);
}

アノテーション

アノテーション 付ける場所 意味
@GetMapping([path])、@PostMapping、@PutMapping、@PatchMapping、@DeleteMapping メソッド HTTP メソッドとパス (/books/{isbn})。パスがなければベースパス: クライアントのもの、またはコントローラークラスのもの。
@GetMapping.of({path, headers, produces, consumes})、その他も同様 メソッド すべての属性を名前で指定する。headers は 'Name=value' のエントリー、produces は応答のメディアタイプ (Accept)、consumes はボディのメディアタイプ (Content-Type)。
@RequestMapping([path])、@RequestMapping.of({path, method, headers, produces, consumes}) メソッド、クラス 任意の HTTP メソッド (method: HttpMethod.head。デフォルトは GET)。コントローラークラスでは、すべてのメソッドのパスのプレフィックス。
@PathVariable([name]) パラメーター パスの {name} を埋める。クライアントは値をパーセントエンコードする。
@RequestParam([name]) パラメーター クエリパラメーター。List はそれを繰り返し、Map はすべてのクエリパラメーターを表す。
@RequestHeader([name]) パラメーター ヘッダー。List は複数の値を与え、Map はすべてのヘッダーを表す。
@CookieValue([name]) パラメーター Cookie ヘッダーの中の Cookie。
@RequestBody() パラメーター ボディ。オブジェクトなら JSON として。
@RequestPart([name]) パラメーター multipart/form-data のボディの一つのパート: ファイル (MultipartFile、List<MultipartFile>)、テキストのフィールド、または JSON のパートとして送るオブジェクト。

名前がなければ、@PathVariable()、@RequestParam()、@RequestHeader()、@CookieValue()、@RequestPart() はパラメーター自身の名前を使います (ジェネレーターはパラメーター名を保持します)。

必須か任意か

required 属性も defaultValue 属性もありません。Dart のパラメーターがそれを示します。

パラメーター クライアント サーバー
nullable (String? q) null の引数は省く。パス変数は空文字列になる リクエストに値がなければ null を渡す
デフォルトあり ({int page = 0}) 引数がなければデフォルトを送る 値がなければデフォルトを使う
それ以外 必須 値がなければ 400 で応答する

つまり @RequestParam(name = "page", defaultValue = "0") int page は @RequestParam('page') int page = 0 になります。

headers、produces、consumes

アノテーションを読むコードのために

すべてのマッピングのアノテーションは Mapping (method、path、headers、produces、consumes。パスがなければ path は '') を実装しているため、ライブラリは annotations.whereType<Mapping>() でそのどれでも見つけられます。それらと @ExceptionHandler は @BeanMethodAnnotation() を持ちます。そのためジェネレーターは、アノテーションを付けたメソッド (パラメーター、そのアノテーション、結果の型) を Bean 定義に記録し、Web サーバーはそこからそれらを見つけます。

Spring (Java) との対応

@GetMapping(value = "/books", produces = "application/json")
List<Book> search(@RequestParam("q") String query, @RequestParam(defaultValue = "0") int page);

Dart では任意の位置引数と名前付き引数を組み合わせられないため、位置引数のパスと並ぶ属性は .of コンストラクターで書きます: @GetMapping('/books', produces: ...) は @GetMapping.of(path: '/books', produces: ...) になります。produces と consumes は配列ではなく String です。

関連項目