
# @RequestParam

`@RequestParam()` は、コントローラーの引数をクエリパラメーター（`?q=dune`）に、なければフォームやマルチパートのボディのフィールドにバインドします。

## 使う理由

検索語、フィルター、ページ番号、並び順は、リソースのアドレスの一部ではない呼び出しの入力です。これらはクエリ文字列で送られます。このアノテーションは値を読み、引数の型に変換し、必須の値がない場合や変換できない場合は 400 で応答します。

値が必須かどうかは Dart の引数自身で決まります。nullable かデフォルト付きなら省略可能、それ以外は必須です。`required` や `defaultValue` の属性はありません。

## 例

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

enum Genre { fiction, science, poetry }

@RestController()
@RequestMapping('/api/books')
class BookSearchController {
  // GET /api/books?q=dune&page=2&genre=science
  @GetMapping()
  String search(
    @RequestParam('q') String query, { // 必須: q がなければ 400
    @RequestParam() int page = 0,      // 省略可: Dart のデフォルト
    @RequestParam() Genre? genre,      // 省略可: null
  }) => '$query, page $page, ${genre?.name ?? 'any genre'}';

  // GET /api/books/by-ids?id=1&id=2、または ?id=1,2: ids は [1, 2]。
  @GetMapping('/by-ids')
  List<int> byIds(@RequestParam('id') List<int> ids) => ids;

  // アノテーションなし: 単純な型は同じ名前のクエリパラメーター。
  // GET /api/books/count?max=10
  @GetMapping('/count')
  int count(int max) => max;

  // すべてのクエリパラメーター: GET /api/books/filter?author=herbert&year=1965
  @GetMapping('/filter')
  Map<String, String> filter(@RequestParam() Map<String, String> filters) =>
      filters;

  // 繰り返されたパラメーターを保持: ?tag=a&tag=b は {'tag': ['a', 'b']}。
  @GetMapping('/tags')
  Map<String, List<String>> tags(
    @RequestParam() Map<String, List<String>> parameters,
  ) => parameters;

  // フォーム: Content-Type が application/x-www-form-urlencoded で
  // ボディが title=Dune&count=2 の POST。
  @PostMapping('/form')
  String form(
    @RequestParam('title') String title,
    @RequestParam('count') int count,
  ) => '$title x$count';
}
```

## パラメーター

| 名前 | 型 | デフォルト | 意味 |
|---|---|---|---|
| `name`（位置引数） | `String?` | `null` | クエリパラメーターまたはフォームのフィールドの名前。`null` なら Dart の引数の名前。`Map` の引数では使われない。 |

## 値の出どころ

`q` という名前の引数では、次の順に探します。

1. クエリ文字列（`?q=...`）
2. リクエストがフォーム（`Content-Type: application/x-www-form-urlencoded`）なら、ボディのフィールド `q`
3. リクエストが `multipart/form-data` なら、アップロードのテキストフィールド `q`

`MultipartFile` または `List<MultipartFile>` の引数は、代わりにその名前のアップロードされたファイルを、`@RequestPart` とまったく同じように受け取ります（[アップロード](../streaming/uploads.md) を参照）。

## 必須、省略可能、デフォルト

| リクエストに `q` がなく、引数が | 結果 |
|---|---|
| nullable: `@RequestParam() String? q` | `null` |
| デフォルト付きの名前付き引数: `{@RequestParam() int page = 0}` | 呼び出しから省かれる: `0` |
| デフォルト付きの省略可能な位置引数: `[@RequestParam() int page = 0]` | 呼び出しから省かれる: `0` |
| 省略可能な non-nullable の `List<MultipartFile>` | 空のリスト |
| それ以外 | 400 `Required parameter 'q' is not present.` |

空の値も値です。`?q=` は `String` には `''` を与え、`int` では 400 になります。

## 型

- **単純な値:** `String`、`int`、`double`、`num`、`bool`（`true`、`on`、`yes`、`1`、`false`、`off`、`no`、`0`）、`BigInt`、`DateTime`（ISO 8601）、`Duration`（`10s`）、`Uri`、enum（`@JsonValue` または大文字小文字を問わない名前で）、`Object` と `dynamic`（テキスト）。
- 単純な値の **リストとセット** は、繰り返されたパラメーターのすべての値を受け取ります（`?id=1&id=2`）。カンマを含む 1 つの値は分割され（`?id=1,2`）、要素の前後の空白は除かれます。
- **`Map<String, V>`** はすべてのパラメーターを受け取ります。マルチパートのテキストフィールド、フォームのフィールド、クエリパラメーターで、同じ名前ならクエリが勝ちます。`V` は単純な型（名前ごとの最初の値を変換したもの）か、単純な型のリスト（すべての値）です。キーは送られた名前のままです。
- **`MultipartFile`、`List<MultipartFile>`:** アップロードされたファイル（[アップロード](../streaming/uploads.md) を参照）。
- **それ以外** は起動を止めます: `the @RequestParam parameter ... is not a simple value`。

変換できない値は、引数を示す 400 の problem になります: `Failed to convert 'page' with value: 'two'`。

## アノテーションなしの場合

アノテーションのない単純な型（または `MultipartFile`）の引数は、Spring と同様に、`@RequestParam()` が付いているものとして、自身の名前のクエリパラメーターとして読まれます。アノテーションのないそれ以外の型の引数は、スターターが自分で埋める型（`ServerHttpRequest`、`HttpHeaders` など。[ヘッダー、クッキー、リクエスト](headers-and-cookies.md) を参照）か、`HandlerMethodArgumentResolver` が埋めるものでない限り、起動を止めます。

## Spring (Java) との対応

```java
@GetMapping("/api/books")
List<Book> search(@RequestParam("q") String query,
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(required = false) Genre genre) { ... }

@GetMapping("/api/books/filter")
List<Book> filter(@RequestParam Map<String, String> filters) { ... }
```

重要な違い:

- `@RequestParam(name = "sort", required = false) String sort` は `@RequestParam('sort') String? sort` です。
- `@RequestParam(defaultValue = "0") int page` は `{@RequestParam() int page = 0}` です。デフォルトは変換されるテキストではなく Dart の値です。
- `MultiValueMap<String, String>` は `Map<String, List<String>>` です。
- `@ModelAttribute` はありません。フォームのフィールドはオブジェクトにバインドされません。1 つずつ、`Map` として、または `@RequestBody() Map<String, String>` として受け取ってください（[@RequestBody](request-body.md) を参照）。

## 関連項目

- [@PathVariable](path-variable.md)
- [@RequestBody](request-body.md)
- [ヘッダー、クッキー、リクエスト](headers-and-cookies.md)
- [アップロード](../streaming/uploads.md)
