@RequestParam
@RequestParam() は、コントローラーの引数をクエリパラメーター(?q=dune)に、なければフォームやマルチパートのボディのフィールドにバインドします。
使う理由
検索語、フィルター、ページ番号、並び順は、リソースのアドレスの一部ではない呼び出しの入力です。これらはクエリ文字列で送られます。このアノテーションは値を読み、引数の型に変換し、必須の値がない場合や変換できない場合は 400 で応答します。
値が必須かどうかは Dart の引数自身で決まります。nullable かデフォルト付きなら省略可能、それ以外は必須です。required や defaultValue の属性はありません。
例
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 という名前の引数では、次の順に探します。
- クエリ文字列(
?q=...) - リクエストがフォーム(
Content-Type: application/x-www-form-urlencoded)なら、ボディのフィールドq - リクエストが
multipart/form-dataなら、アップロードのテキストフィールドq
MultipartFile または List<MultipartFile> の引数は、代わりにその名前のアップロードされたファイルを、@RequestPart とまったく同じように受け取ります(アップロード を参照)。
必須、省略可能、デフォルト
リクエストに 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>: アップロードされたファイル(アップロード を参照)。- それ以外 は起動を止めます:
the @RequestParam parameter ... is not a simple value。
変換できない値は、引数を示す 400 の problem になります: Failed to convert 'page' with value: 'two'。
アノテーションなしの場合
アノテーションのない単純な型(または MultipartFile)の引数は、Spring と同様に、@RequestParam() が付いているものとして、自身の名前のクエリパラメーターとして読まれます。アノテーションのないそれ以外の型の引数は、スターターが自分で埋める型(ServerHttpRequest、HttpHeaders など。ヘッダー、クッキー、リクエスト を参照)か、HandlerMethodArgumentResolver が埋めるものでない限り、起動を止めます。
Spring (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 を参照)。