
# メソッド

`@FeignClient` インターフェースの各メソッドは、一つのエンドポイントを記述します。そのマッピングのアノテーションが HTTP メソッドとパスを与え、パラメーターのアノテーションが各引数の行き先を示し、戻り値の型がレスポンスの読み方を示します。アノテーションはコントローラーのものと同じです。

## 使う理由

サーバー自身の語彙で書いたクライアントは、それが呼ぶ API のように読め、コントローラーを知っている開発者はすでにその書き方を知っています。ジェネレーターがメソッドを見るため、スターターはアプリケーションの起動時にそれをチェックします。そのため、パス変数のタイプミスは、最初の呼び出しではなく、すぐに失敗します。

## 例

```dart
@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` のボディの一つのパート ([ファイルとマルチパート](multipart.md) を参照)。 |
| アノテーションのないパラメーター | ボディ。そうしたパラメーターは一つだけ許される。 |

引数を省けるかどうかは、`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` のレスポンスのイベント ([サーバー送信イベント](server-sent-events.md) を参照)。 |
| `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` で呼び出しを失敗させます。

```dart
@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 のないクライアント。

```text
Invalid Feign client CatalogClient:
  - CatalogClient.find: the path variable {isbn} of "/books/{isbn}" has no @PathVariable parameter
```

## Spring (Java) との対応

```java
@GetMapping("/books")
List<Book> search(@RequestParam("q") String query, @RequestParam(required = false) Integer page);
```

アノテーションは Spring のものです。メソッドは `Future` を返し、任意の引数は nullable な Dart のパラメーターから来て、メソッドは複数の `Map` パラメーターを持てます (Feign: 一つのクエリマップと一つのヘッダーマップ)。`@SpringQueryMap` はまだありません。

## 関連項目

- [設定](configuration.md)
- [エラー、リトライ、タイムアウト](errors-and-retries.md)
- [@RequestMapping](../spring-boot-starter-web/controllers/request-mapping.md)
