
# @RequestMapping と @GetMapping

マッピングアノテーションは、コントローラーのメソッドがどのリクエストに応答するかを示します。HTTP メソッド、パス、そして `Content-Type`、`Accept` ヘッダー、その他のヘッダーに対する省略可能な条件です。

## 使う理由

各エンドポイントは 1 つのアノテーションを持つ 1 つのメソッドなので、API のルートをコントローラーから読み取れます。ルーターはすべてのリクエストをこれらのマッピングと比較して最も具体的なものを選び、どれも合わなければ標準的なエラーで応答します。未知のパスには `404`、既知のパスに別のメソッドで来たら `405`、メソッドが読まないボディの型には `415`、応答できない `Accept` には `406` です。

## アノテーション

| アノテーション | HTTP メソッド |
|---|---|
| `@GetMapping` | `GET`（と `HEAD`） |
| `@PostMapping` | `POST` |
| `@PutMapping` | `PUT` |
| `@PatchMapping` | `PATCH` |
| `@DeleteMapping` | `DELETE` |
| `@RequestMapping` | `method:` で選ぶ任意のメソッド。クラスに付けるとベースパス |

Dart では名前付き引数と並べて省略可能な位置引数を置けないため、それぞれに 2 つのコンストラクターがあります。

- `@GetMapping('/path')`: パスだけ。パスなしの `@GetMapping()` はベースパスそのものをマップします。
- `@GetMapping.of(path: '/path', produces: ..., consumes: ..., headers: [...])`: すべての属性を名前で指定します。

## 例

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class Book {
  const Book({required this.isbn, required this.title});

  final String isbn;
  final String title;
}

@RestController()
@RequestMapping('/api/books') // 以下のすべてのメソッドのプレフィックス
class BookController {
  // GET /api/books
  @GetMapping()
  List<Book> all() => const [Book(isbn: '978-0', title: 'Dune')];

  // GET /api/books/978-0
  @GetMapping('/{isbn}')
  Book find(@PathVariable() String isbn) => Book(isbn: isbn, title: 'Dune');

  // POST /api/books。JSON のボディのときだけ。
  @PostMapping.of(consumes: MediaType.applicationJson)
  Book create(@RequestBody() Book book) => book;

  // PUT /api/books/978-0 は本を置き換える。
  @PutMapping('/{isbn}')
  Book replace(@PathVariable() String isbn, @RequestBody() Book book) => book;

  // PATCH /api/books/978-0 は一部のフィールドを変更する。
  @PatchMapping('/{isbn}')
  Map<String, Object?> update(
    @PathVariable() String isbn,
    @RequestBody() Map<String, Object?> changes,
  ) => changes;

  // DELETE /api/books/978-0 → 204
  @DeleteMapping('/{isbn}')
  @ResponseStatus(HttpStatus.noContent)
  void delete(@PathVariable() String isbn) {}

  // Accept: text/csv (または */*、または Accept なし) の GET /api/books/export:
  // 両方のメソッドが一致し、こちらのほうが条件が多いので勝つ。
  @GetMapping.of(path: '/export', produces: 'text/csv')
  String csv() => 'isbn,title\n978-0,Dune\n';

  // Accept: application/json なら CSV のメソッドは外れる: JSON。
  @GetMapping('/export')
  List<Book> json() => all();

  // ヘッダーで選ばれる、メソッドのバージョン 2。
  @GetMapping.of(path: '/{isbn}/summary', headers: ['X-Api-Version=2'])
  String summaryV2(@PathVariable() String isbn) => 'v2 $isbn';

  @GetMapping.of(path: '/{isbn}/summary', headers: ['X-Api-Version!=2'])
  String summary(@PathVariable() String isbn) => 'v1 $isbn';

  // ショートカットのアノテーションがないメソッド: HEAD。
  @RequestMapping.of(path: '/{isbn}/exists', method: HttpMethod.head)
  ResponseEntity<void> exists(@PathVariable() String isbn) =>
      ResponseEntity.status(HttpStatus.ok).build();
}
```

クラスに付けた `@RequestMapping.of` は、すべてのメソッドに条件を追加します。

```dart
// すべてのメソッドが JSON を読み書きし、API キーのヘッダーを必要とする。
@RestController()
@RequestMapping.of(
  path: '/api/v2',
  produces: MediaType.applicationJson,
  consumes: MediaType.applicationJson,
  headers: ['X-Api-Key'],
)
class V2Controller {
  @GetMapping('/ping')
  Map<String, String> ping() => {'status': 'ok'};
}
```

## 属性

すべてのマッピングアノテーションが次の属性を持ちます。`method` は `@RequestMapping.of` だけです。

| 名前 | 型 | デフォルト | 意味 |
|---|---|---|---|
| `path` | `String` | `''` | クラスの `@RequestMapping` からの相対のパスパターン。空ならベースパスそのもの。`{variables}`、ワイルドカード、`${...}` プレースホルダーを含められる。短いコンストラクターでは位置引数。 |
| `method` | `HttpMethod` | `HttpMethod.get` | `@RequestMapping.of` のみ: HTTP メソッド（`get`、`head`、`post`、`put`、`patch`、`delete`、`options`、`trace`）。ショートカットのアノテーションでは固定。クラスでは無視される。 |
| `produces` | `String?` | `null` | レスポンスのメディアタイプ。1 つ、またはカンマ区切りのリスト。`Accept` がそのいずれかを許すときだけメソッドが選ばれ（そうでなければ 406）、ボディはそれで書かれる。`null` なら任意の `Accept`。 |
| `consumes` | `String?` | `null` | リクエストボディのメディアタイプ。1 つ、またはカンマ区切りのリスト。`Content-Type` がそのいずれかのときだけメソッドが選ばれる（そうでなければ 415）。`null` なら任意のボディ。 |
| `headers` | `List<String>` | `const []` | リクエストヘッダーに対する条件（後述）。条件を満たすメソッドがなければ 400。 |

`@RequestMapping('/path')`（短い形式）は `GET` をマップします。パスだけが意味を持つクラスでは、これが通常の形式です。

## パス

パスは、クエリ文字列と `server.context-path` を除いたリクエストパスに対して照合されるパスパターン（`spring_web_dart` の `PathPattern`）です。

| パターン | 一致するもの |
|---|---|
| `/books` | そのパス自体。末尾のスラッシュは区別される: Spring 6 と同じく、`/books/` は別のパス。 |
| `/books/{isbn}` | 1 つのセグメント。`isbn` として取り出され、デコードされる |
| `/books/{isbn:\d+}` | 正規表現に一致する 1 つのセグメント。取り出される |
| `/files/{*path}` | パスの残り。先頭の `/` 付きで取り出される（末尾のみ） |
| `/static/**` | 0 個以上のセグメント（末尾のみ） |
| `/b?ok` | `?`: セグメントの 1 文字 |
| `/*.json` | `*`: セグメントの 0 文字以上 |

- **結合。** クラスのパスとメソッドのパスはつなげられます。`@RequestMapping('/api/books')` と `@GetMapping('/{isbn}')` で `/api/books/{isbn}` になります。先頭の `/` がなければ追加されます。
- **プレースホルダー。** パスの中の `${...}` は、起動時に設定から埋められます: `@GetMapping(r'${shop.api.base:/api}/books')`。`produces` と `consumes` でも同じです。Dart が `$` を自分で解釈しないよう、そのようなパスは raw 文字列（`r'...'`）で書いてください。
- **マトリクスパラメーター** は、Spring と同様に照合から除外されます。`/books/1111;v=1` は `isbn` を `1111` として `/books/{isbn}` に一致します。
- **安全でないパスは届きません。** エンコードされた `/`、`\`、NUL（`%2F`、`%5C`、`%00`）を含むパス、マトリクスパラメーターで隠された `.` や `..` のセグメント（`/files/..;/secret`）、UTF-8 でない `%` エスケープには、どのフィルターよりも前にサーバーが 400 で応答します。そのため `..%2F..%2Fsecret` がパス変数に届くことはありません。
- **不正な形式のパターンは起動を止めます**: 末尾以外の `**` や `{*name}`、対応しない波括弧、不正な正規表現、2 回使われた変数などです（[起動時のチェック](startup-checks.md) を参照）。

## ヘッダーの条件

`headers` の各要素が 1 つの条件で、構文は Spring と同じです。クラスの要素とメソッドの要素は合算されます。

| 要素 | リクエストに求められること |
|---|---|
| `'X-Api-Key'` | そのヘッダーを持つ |
| `'!X-Debug'` | そのヘッダーを持たない |
| `'X-Api-Version=2'` | そのヘッダーをちょうどこの値で持つ |
| `'X-Api-Version!=2'` | そのヘッダーをこの値で持たない（ヘッダーがなければ通る） |

パス、メソッド、メディアタイプには一致するが、どのヘッダー条件にも一致しないリクエストには、400 `Unsatisfied header conditions` が返ります。

## メディアタイプ

- **`consumes`** はリクエストの `Content-Type` と比較されます。`application/*` のような型は `application/json` を含みます。`Content-Type` のないリクエストは、Spring と同様に `application/octet-stream` として比較されます。415 の応答には、そのパスが読む型を列挙した `Accept` ヘッダーが付きます。
- **`produces`** はリクエストの `Accept` と比較されます。`Accept` のない（または解析できない）リクエストはすべてを受け付けます。406 の応答の詳細には、そのパスが書く型が列挙されます: `Acceptable representations: [text/csv].`
- **書かれる型。** `produces` を持つマッピングでは、レスポンスの `Content-Type` は、クライアントの `q` 値の順で、クライアントが受け付ける最初の型になります。[戻り値](results.md) を参照してください。
- **クラスとメソッドの両方にある場合**、メソッドの `produces` や `consumes` はクラスのものに追加されるのではなく、置き換えます。
- メディアタイプの定数は `MediaType` にあります: `applicationJson`、`applicationProblemJson`、`applicationNdjson`、`applicationOctetStream`、`applicationFormUrlencoded`、`multipartFormData`、`textPlain`、`textHtml`、`textEventStream`、`imagePng` などです。

## どのマッピングが勝つか

リクエストに対して、ルーターは次のように処理します。

1. パターンがパスに一致するマッピングを残します。なければ、次のハンドラーマッピング（WebSocket のエンドポイント、静的リソース）に問い合わせ、それでもなければ 404 `No endpoint GET /x.` です。
2. リクエストの HTTP メソッドのものを残します。`GET` マッピングは `HEAD` にも応答します。なければ `Allow` ヘッダー付きの 405（`OPTIONS` なら `Allow` 付きの 200）です。
3. `consumes` が `Content-Type` を含むものを残します（なければ 415）。
4. `produces` が `Accept` に合うものを残します（なければ 406）。
5. `headers` の条件が成り立つものを残します（なければ 400）。
6. 最も具体的なパターンを選びます。`**` や `{*name}` のないパターンがそれらを持つものより先、次に変数とワイルドカードが少ないもの、次に固定テキストが長いものです。そのため `/books/new` は `/books/{isbn}` に勝ちます。パターンが同等なら、条件（`produces`、`consumes`、`headers`）の多いマッピングが勝ちます。

ルール:

- **`HEAD`** は `GET` のメソッドを実行します。ハンドラーは通常どおり書き込み、ボディは捨てられ、`Content-Length` は保たれます。
- `OPTIONS` マッピングのないマップ済みのパスへの **`OPTIONS`** には、`200` と `Allow` で応答します。`Allow` には、マップされたメソッド、`GET` があれば `HEAD`、そして `OPTIONS` が列挙されます。
- **CORS のプリフライト**（`Origin` と `Access-Control-Request-Method` を持つ `OPTIONS`）には CORS のルールから応答し、メソッドに渡すことはありません（[CORS](../cors.md) を参照）。
- **2 つのメソッドが同じリクエストをマップしている**（同じメソッド、パターン、条件）と、`Ambiguous mapping` で起動が止まります。
- **1 つのメソッドに 1 つのマッピング。** 1 つのメソッドに複数のマッピングアノテーションがあると起動が止まります。他の HTTP メソッドには `@RequestMapping.of` を使ってください。
- **どのメソッドもストリーミングできます。** `GET` と同じく `POST` もサーバー送信イベントで応答できます（[サーバー送信イベント](../streaming/sse.md) を参照）。

起動時にすべてのマッピングを確認するには、`logging.level.spring.web.mvc=trace` を設定します。debug レベルの件数（`12 mappings in 'requestMappingHandlerMapping'`）の後に、マッピングごとに 1 行（`Mapped GET /api/books/{isbn} -> BookController.find`）が出力されます。debug レベルでは、各リクエストで選ばれたメソッドもログに出ます（`Mapped to BookController#find()`）。

## Spring (Java) との対応

```java
@RestController
@RequestMapping("/api/books")
class BookController {
  @GetMapping("/{isbn}")
  Book find(@PathVariable String isbn) { ... }

  @GetMapping(path = "/export", produces = "text/csv")
  String csv() { ... }

  @RequestMapping(path = "/{isbn}/exists", method = RequestMethod.HEAD)
  ResponseEntity<Void> exists(@PathVariable String isbn) { ... }
}
```

重要な違い:

- パス以外の属性には `.of` コンストラクターが必要です: `@GetMapping.of(path: '/export', produces: 'text/csv')`。
- `produces`、`consumes`、`method` は配列ではなく 1 つの値（メディアタイプはカンマ区切りのリスト）を受け取ります。`path` は複数ではなく 1 つのパターンを受け取ります。
- `params` の条件（`params = "version=2"`）はサポートされていません。
- より多くの誤りが起動を止めます（[起動時のチェック](startup-checks.md) を参照）。

## 関連項目

- [@PathVariable](path-variable.md)
- [戻り値](results.md)
- [エラー](../errors/index.md)
- [CORS](../cors.md)
- [プレースホルダー](../../spring-core-dart/config/placeholders.md)
