@PathVariable
@PathVariable() は、コントローラーの引数を、/books/{isbn} の isbn のようなマッピングのパスの {variable} にバインドします。
使う理由
パスがリソースを指す場合(/books/978-0、/authors/42/books)、値はクエリではなくパスに置くべきです。このアノテーションは一致したパスから値を取り、デコードして引数の型に変換するため、メソッドは解析が必要なテキストではなく int や enum を受け取ります。
例
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は起動を止めます(起動時のチェック を参照)。 -
パスが一致した時点で 値は必ず存在する ため、引数にデフォルトは不要で、nullable にする必要もありません。
-
値はデコードされます。
/books/a%20bはa bになります。パス中のエンコードされた/、\、NUL(%2F、%5C、%00)は、どのフィルターよりも前にサーバーが 400 で拒否するため、変数が../を持つことはありません。 -
マトリクスパラメーターは切り落とされます:
/books/1111;v=1はisbnを1111にします。 -
変換。 テキストは引数の型に変換されます。
型 受け付けるテキスト String、Object、dynamicそのまま int、double、num、BigInt数値(前後の空白は除かれる) booltrue、on、yes、1/false、off、no、0。大文字小文字は問わないDateTimeISO 8601( 2026-05-01、2026-05-01T10:00:00Z)Duration10s、500ms、2h(設定の 期間の形式)UriURI enum その @JsonValue、なければ大文字小文字を問わない名前List<T>、Set<T>上記のカンマ区切りのリスト 変換できないテキストは 400 の problem になります:
Failed to convert 'id' with value: 'x'(MethodArgumentTypeMismatchException)。 -
単純な値だけです。 それ以外の型(独自のクラス、
Map)の@PathVariableは起動を止めます。 -
パターンでメソッドに届くものを制限できます。
{id:\d+}を使うと、/orders/abcは変換エラーではなく 404 になります。変数がファイル名の一部になる場合は、必ずこのように制限するか、チェックしてください(ダウンロード を参照)。 -
{*path}は先頭の/付きでパスの残りを取り出します。最後のセグメントにしか置けません。 -
1 つの引数に 1 つの役割。 1 つの引数に
@PathVariableと別のバインドアノテーション(@RequestParamなど)を同時に付けることはできません。
Spring (Java) との対応
@GetMapping("/authors/{id}/books")
List<Book> byAuthor(@PathVariable("id") int authorId) { ... }
重要な違い:
required属性はありません。パターンの変数は常に存在します。- 引数のないパス変数、またはその逆は起動を止めます。Spring ではリクエストが失敗するだけです。
- すべての変数を受け取る
Map<String, String>の引数はサポートされていません。変数はリクエスト属性uriTemplateVariablesAttribute(request.attributes[uriTemplateVariablesAttribute])にあります。