マッピングのアノテーション
これらのアノテーションは、メソッドがどの 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
- クライアントでは、マッピングの
headersが送られます。サーバーのための条件にすぎないエントリー ('Name'、'!Name'、'Name!=value') は、Spring Cloud OpenFeign と同じく無視されます。Feign 自身の'Name: value'は起動時に拒否されます。 - サーバーでは、リクエストが満たすべき条件です:
'Name'(存在する)、'!Name'(存在しない)、'Name=value'、'Name!=value'。 producesとconsumesは、一つのメディアタイプ、またはカンマ区切りのリストを、一つのStringとして受け取ります。
アノテーションを読むコードのために
すべてのマッピングのアノテーションは 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 です。