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

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

## 使う理由

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

## 例

```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) との対応

```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` です。

## 関連項目

- [コントローラーのアノテーション](controller-annotations.md)
- [Web スターターの @RequestMapping](../spring-boot-starter-web/controllers/request-mapping.md)
- [Feign クライアントのメソッド](../spring-boot-starter-feign/methods.md)
