
# @PathVariable

`@PathVariable()` は、コントローラーの引数を、`/books/{isbn}` の `isbn` のようなマッピングのパスの `{variable}` にバインドします。

## 使う理由

パスがリソースを指す場合（`/books/978-0`、`/authors/42/books`）、値はクエリではなくパスに置くべきです。このアノテーションは一致したパスから値を取り、デコードして引数の型に変換するため、メソッドは解析が必要なテキストではなく `int` や enum を受け取ります。

## 例

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

enum Format { pdf, epub }

@RestController()
class BookController {
  // GET /books/978-0: isbn は '978-0'。
  @GetMapping('/books/{isbn}')
  String find(@PathVariable() String isbn) => 'book $isbn';

  // 引数の名前が変数と異なるので、名前を指定する。
  // GET /authors/42/books: authorId は 42。/authors/x/books は 400。
  @GetMapping('/authors/{id}/books')
  String byAuthor(@PathVariable('id') int authorId) => 'author $authorId';

  // 正規表現で数字だけを通す: /orders/abc は 404。
  @GetMapping(r'/orders/{id:\d+}')
  String order(@PathVariable() int id) => 'order $id';

  // enum は大文字小文字を問わず名前で: /downloads/978-0/EPUB。
  @GetMapping('/downloads/{isbn}/{format}')
  String download(@PathVariable() String isbn, @PathVariable() Format format) =>
      '$isbn as ${format.name}';

  // パスの残り、先頭のスラッシュ付き:
  // GET /files/docs/a/b.txt: path は '/docs/a/b.txt'。
  @GetMapping('/files/{*path}')
  String file(@PathVariable() String path) => path;

  // 1 つのセグメントからリスト: GET /books/batch/1,2,3: ids は [1, 2, 3]。
  @GetMapping('/books/batch/{ids}')
  List<int> batch(@PathVariable() List<int> ids) => ids;
}
```

## パラメーター

| 名前 | 型 | デフォルト | 意味 |
|---|---|---|---|
| `name`（位置引数） | `String?` | `null` | パス変数の名前。`null` なら Dart の引数と同じ名前の変数。 |

## ルール

- **すべての変数に引数が、すべての引数に変数が必要です。** `@PathVariable` の引数がない `{variable}` や、名前がパスにない `@PathVariable` は起動を止めます（[起動時のチェック](startup-checks.md) を参照）。
- パスが一致した時点で **値は必ず存在する** ため、引数にデフォルトは不要で、nullable にする必要もありません。
- **値はデコードされます。** `/books/a%20b` は `a b` になります。パス中のエンコードされた `/`、`\`、NUL（`%2F`、`%5C`、`%00`）は、どのフィルターよりも前にサーバーが 400 で拒否するため、変数が `../` を持つことはありません。
- **マトリクスパラメーターは切り落とされます**: `/books/1111;v=1` は `isbn` を `1111` にします。
- **変換。** テキストは引数の型に変換されます。

  | 型 | 受け付けるテキスト |
  |---|---|
  | `String`、`Object`、`dynamic` | そのまま |
  | `int`、`double`、`num`、`BigInt` | 数値（前後の空白は除かれる） |
  | `bool` | `true`、`on`、`yes`、`1` / `false`、`off`、`no`、`0`。大文字小文字は問わない |
  | `DateTime` | ISO 8601（`2026-05-01`、`2026-05-01T10:00:00Z`） |
  | `Duration` | `10s`、`500ms`、`2h`（設定の [期間の形式](../../spring-core-dart/conversion/durations.md)） |
  | `Uri` | URI |
  | enum | その `@JsonValue`、なければ大文字小文字を問わない名前 |
  | `List<T>`、`Set<T>` | 上記のカンマ区切りのリスト |

  変換できないテキストは 400 の problem になります: `Failed to convert 'id' with value: 'x'`（`MethodArgumentTypeMismatchException`）。
- **単純な値だけです。** それ以外の型（独自のクラス、`Map`）の `@PathVariable` は起動を止めます。
- **パターンでメソッドに届くものを制限できます。** `{id:\d+}` を使うと、`/orders/abc` は変換エラーではなく 404 になります。変数がファイル名の一部になる場合は、必ずこのように制限するか、チェックしてください（[ダウンロード](../streaming/downloads.md) を参照）。
- **`{*path}`** は先頭の `/` 付きでパスの残りを取り出します。最後のセグメントにしか置けません。
- **1 つの引数に 1 つの役割。** 1 つの引数に `@PathVariable` と別のバインドアノテーション（`@RequestParam` など）を同時に付けることはできません。

## Spring (Java) との対応

```java
@GetMapping("/authors/{id}/books")
List<Book> byAuthor(@PathVariable("id") int authorId) { ... }
```

重要な違い:

- `required` 属性はありません。パターンの変数は常に存在します。
- 引数のないパス変数、またはその逆は起動を止めます。Spring ではリクエストが失敗するだけです。
- すべての変数を受け取る `Map<String, String>` の引数はサポートされていません。変数はリクエスト属性 `uriTemplateVariablesAttribute`（`request.attributes[uriTemplateVariablesAttribute]`）にあります。

## 関連項目

- [@RequestMapping と @GetMapping](request-mapping.md): パスパターン
- [@RequestParam](request-param.md)
- [起動時のチェック](startup-checks.md)
