メソッド
@FeignClient インターフェースの各メソッドは、一つのエンドポイントを記述します。そのマッピングのアノテーションが HTTP メソッドとパスを与え、パラメーターのアノテーションが各引数の行き先を示し、戻り値の型がレスポンスの読み方を示します。アノテーションはコントローラーのものと同じです。
使う理由
サーバー自身の語彙で書いたクライアントは、それが呼ぶ API のように読め、コントローラーを知っている開発者はすでにその書き方を知っています。ジェネレーターがメソッドを見るため、スターターはアプリケーションの起動時にそれをチェックします。そのため、パス変数のタイプミスは、最初の呼び出しではなく、すぐに失敗します。
例
@FeignClient('catalog', url: r'${catalog.url}', path: '/api')
abstract interface class CatalogClient {
// GET https://.../api/books/978-0
@GetMapping('/books/{isbn}')
Future<Book?> find(@PathVariable() String isbn);
// GET /api/books?q=dune&tag=sf&tag=classic。page が null なら省かれる
@GetMapping('/books')
Future<List<Book>> search(
@RequestParam('q') String query,
@RequestParam('tag') List<String> tags, {
@RequestParam() int? page,
});
// エントリーごとに一つのクエリパラメーター。
@GetMapping('/books/filter')
Future<List<Book>> filter(@RequestParam() Map<String, Object?> filters);
// プレースホルダー付きの固定のヘッダー。呼び出しごとのヘッダーと Cookie。
@PutMapping.of(path: '/books/{isbn}', headers: [r'X-Shop=${shop.name}'])
Future<ResponseEntity<Book>> update(
@PathVariable() String isbn,
@RequestBody() Book book,
@RequestHeader('If-Match') String etag,
@CookieValue('SESSION') String? session,
);
// ステータスにかかわらず、生のレスポンス。
@RequestMapping.of(path: '/books/{isbn}', method: HttpMethod.head)
Future<HttpResponse> probe(@PathVariable() String isbn);
}
マッピングのアノテーション
| アノテーション | リクエスト |
|---|---|
@GetMapping('/books/{isbn}') |
GET |
@PostMapping('/books') |
POST |
@PutMapping、@PatchMapping、@DeleteMapping |
PUT、PATCH、DELETE |
@RequestMapping.of(path: '/x', method: HttpMethod.head) |
任意のメソッド (デフォルトは GET) |
- メソッドのパスは、クライアントの
urlとpathに追加されます。パスのないマッピング (@GetMapping()) は、クライアントの URL とパスそのものを呼びます。 - パスに書いたクエリ (
@GetMapping('/books?sort=title')) は書いたとおりに送られ、呼び出し自身のクエリパラメーターがその後に追加されます。 headers: 毎回の呼び出しで送られる固定のヘッダー。Spring と同じくName=valueと書き、${...}のプレースホルダーは設定から解決されます。'!X-Debug'のような Spring のサーバー側の条件は無視されます。Feign 自身の構文'Name: value'は、起動時にアプリケーションを止めます。produces:Acceptヘッダー (デフォルトはapplication/json)。consumes: ボディのContent-Type。
パスを伴う場合、これらの属性は .of コンストラクターで書きます。Dart のコンストラクターは、任意の位置引数と名前付き引数の両方を持てないためです: @GetMapping.of(path: '/books', headers: ['X-Shop=neon'])。
パラメーター
| パラメーター | 行き先 |
|---|---|
@PathVariable() String isbn |
パスの {isbn}。URL エンコードされる。/ は / のまま (decode-slash を参照)。別の名前には @PathVariable('id')。値 . や .. は、パスを変えてしまうため ArgumentError を投げる。 |
@RequestParam('q') String query |
?q=...。null は省かれ、List はパラメーターを繰り返す。 |
@RequestParam() Map<String, Object?> filters |
エントリーごとに一つのクエリパラメーター。List の値はそれを繰り返し、null は省かれる。 |
@RequestHeader('X-Trace') String? trace |
ヘッダー。null は省かれ、List は複数の値を与える。 |
@RequestHeader() Map<String, String> headers |
エントリーごとに一つのヘッダー。 |
@CookieValue('SESSION') String session |
Cookie。呼び出しのすべての Cookie は一つの Cookie: a=1; b=2 ヘッダーに入る。null は省かれる。 |
@RequestBody() Book book |
ボディ: オブジェクトは JSON として、String はテキストとして、Uint8List はバイトとして。consumes: MediaType.applicationFormUrlencoded ならフォーム。 |
@RequestPart('file') MultipartFile file |
multipart/form-data のボディの一つのパート (ファイルとマルチパート を参照)。 |
| アノテーションのないパラメーター | ボディ。そうしたパラメーターは一つだけ許される。 |
引数を省けるかどうかは、required 属性や defaultValue 属性ではなく、Dart のパラメーターから決まります。
| パラメーター | null の引数 |
|---|---|
nullable (String? sort) |
クエリパラメーター、ヘッダー、パートは省かれる。パス変数は空文字列になる |
デフォルト値あり ({String sort = 'asc'}) |
不可。引数がなければデフォルトが送られる |
| 非 nullable | 不可 |
パス、クエリパラメーター、ヘッダー、Cookie は、単一の値かそのリストを受け取ります。列挙型、DateTime などの値は JSON と同じく書かれます。列挙型はその名前か @JsonValue で、日付は ISO 8601 です。型がオブジェクトであるパラメーター (@RequestParam() Book book) は、起動時にアプリケーションを止めます。そのフィールドを別々のパラメーターとして、または Map として渡してください。実行時の値でしか分からない場合 (Object 型のパラメーター) は、オブジェクトは EncodeException で呼び出しを失敗させます。クエリパラメーターの空白は + として送られます。
結果
| 戻り値の型 | レスポンスから |
|---|---|
Future<Book>、Future<List<Book>>、Future<Map<String, int>> |
ObjectMapper を通して読んだ JSON のボディ。 |
Future<Book?> |
空のボディ (または dismiss404 での 404) なら null。 |
Future<void> |
何も。ステータスは 2xx でなければならない。 |
Future<String>、Future<Uint8List> |
テキストとして、またはバイトとしてのボディ。 |
Future<ResponseEntity<Book>> |
ステータス、ヘッダー (読み取り専用)、ボディ。 |
Future<ResponseEntity<void>> |
ステータスとヘッダー。ボディは無視される。 |
Future<HttpResponse> |
ステータスにかかわらず、生のレスポンス: エラーのデコードも dismiss404 もない (Feign の Response)。 |
EventStream<OrderEvent>、Stream<OrderEvent> |
text/event-stream のレスポンスのイベント (サーバー送信イベント を参照)。 |
Stream<List<int>> |
コンテンツタイプにかかわらず、届いた順のレスポンスのボディ (大きなファイルなど): リスナーごとに一つのリクエスト、produces で指定しない限り Accept: */*、失敗したステータスはエラーデコーダーの例外、再接続なし。 |
Future<Uint8List> はボディ全体を読んでから戻ります。Stream<List<int>> は違います。リクエストのボディは、送る前に常に全体が読まれます。
空のボディの非 nullable な結果や、型に合わないボディは、DecodeException を投げます。
フォームのボディ
ログインのエンドポイントのような一部の API は、HTML フォームのボディを期待します。consumes: MediaType.applicationFormUrlencoded では、ボディのパラメーターは name=value のペアとして送られます。Map のエントリー、またはオブジェクトのプロパティを ObjectMapper が書くとおり (@JsonProperty の名前) にです。ペアはコンテンツタイプの charset (デフォルトは UTF-8) で URL エンコードされ、List の値は名前を繰り返し、null の値は省かれます。ネストしたオブジェクトは EncodeException で呼び出しを失敗させます。
@PostMapping.of(path: '/login', consumes: MediaType.applicationFormUrlencoded)
Future<void> login(@RequestBody() Map<String, String> form);
// 送るもの: username=neo&password=s3cr%3Ft
起動時のチェック
すべてのクライアントは、生成されるときにチェックされます。次のものが見つかると、アプリケーションは理由とともに止まります。
@PathVariableパラメーターのない、パスの中の{variable}。またはその逆。- マッピングのアノテーションがない、または複数あるメソッド。
Futureもイベントストリーム (Future<EventStream<T>>を含む) も返さないメソッド。- パス、クエリ、ヘッダー、Cookie の値としてのオブジェクト。
- Feign の
Name: valueの構文で書いたヘッダー。 @RequestBodyを伴う、またはマルチパート以外のconsumesを伴う@RequestPart。- URL のないクライアント。
Invalid Feign client CatalogClient:
- CatalogClient.find: the path variable {isbn} of "/books/{isbn}" has no @PathVariable parameter
Spring (Java) との対応
@GetMapping("/books")
List<Book> search(@RequestParam("q") String query, @RequestParam(required = false) Integer page);
アノテーションは Spring のものです。メソッドは Future を返し、任意の引数は nullable な Dart のパラメーターから来て、メソッドは複数の Map パラメーターを持てます (Feign: 一つのクエリマップと一つのヘッダーマップ)。@SpringQueryMap はまだありません。