@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 という名前の引数では、次の順に探します。

  1. クエリ文字列(?q=...)
  2. リクエストがフォーム(Content-Type: application/x-www-form-urlencoded)なら、ボディのフィールド q
  3. リクエストが 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 になります。

型

変換できない値は、引数を示す 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) { ... }

重要な違い:

関連項目