メソッド

@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)

パスを伴う場合、これらの属性は .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

起動時のチェック

すべてのクライアントは、生成されるときにチェックされます。次のものが見つかると、アプリケーションは理由とともに止まります。

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 はまだありません。

関連項目