@RequestBody
@RequestBody() は、コントローラーの引数をリクエストのボディにバインドします。オブジェクトは JSON から読まれ、String、バイト、バイトストリーム、フォームの Map はそれぞれの方法で読まれます。@Valid() を付けると、オブジェクトが検証されます。
使う理由
POST、PUT、PATCH は、データを通常 JSON としてボディで送ります。このアノテーションはボディを読み、アプリケーションの ObjectMapper を通して引数の型にデコードし、制約をチェックし、クライアントの誤りに代わりに応答します。JSON でないボディには 415、解析できない JSON や合わない JSON には 400、制約を破るフィールドを列挙した 400 です。
例
import 'dart:typed_data';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
class NewBook {
const NewBook({required this.isbn, required this.title, this.stock = 0});
@NotBlank()
@Size(min: 4, max: 13)
final String isbn;
@NotBlank()
final String title;
@PositiveOrZero()
final int stock;
}
class Book {
const Book({required this.isbn, required this.title});
final String isbn;
final String title;
}
abstract final class OnImport {}
@RestController()
@RequestMapping('/api/books')
class BookController {
// {"isbn": "978-0", "title": "Dune"} を持つ POST /api/books。
// 空のタイトルは、そのフィールドを列挙した 400 になる。
@PostMapping()
@ResponseStatus(HttpStatus.created)
Book create(@RequestBody() @Valid() NewBook book) =>
Book(isbn: book.isbn, title: book.title);
// Default グループと OnImport グループで検証される。
@PostMapping('/import')
Book importBook(@RequestBody() @Validated([Default, OnImport]) NewBook book) =>
Book(isbn: book.isbn, title: book.title);
// ボディは省略可能: なければ book は null。
@PatchMapping('/{isbn}/touch')
String touch(@PathVariable() String isbn, @RequestBody() Book? book) =>
book == null ? 'touched $isbn' : 'replaced $isbn';
// 任意の形の JSON オブジェクト。
@PatchMapping('/{isbn}')
Map<String, Object?> update(
@PathVariable() String isbn,
@RequestBody() Map<String, Object?> changes,
) => changes;
// オブジェクトのリスト。
@PostMapping('/batch')
int batch(@RequestBody() List<NewBook> books) => books.length;
// Content-Type にかかわらず、ボディをテキストとして。
@PostMapping('/notes')
int note(@RequestBody() String text) => text.length;
// 生のバイト。
@PostMapping('/{isbn}/cover')
int cover(@PathVariable() String isbn, @RequestBody() Uint8List bytes) =>
bytes.length;
// 大きなアップロード。届いた順に読み、全体をメモリに保持することはない。
@PostMapping('/backup')
Future<int> backup(@RequestBody() Stream<Uint8List> body) async {
var total = 0;
await for (final chunk in body) {
total += chunk.length;
}
return total;
}
// フォームのボディ: Content-Type が application/x-www-form-urlencoded の
// title=Dune&isbn=978-0。
@PostMapping('/form')
Map<String, String> form(@RequestBody() Map<String, String> fields) => fields;
}
検証に失敗した場合:
POST /api/books {"isbn": "978-0", "title": ""}
→ 400 application/problem+json
{"type":"about:blank","title":"Bad Request","status":400,"detail":"Invalid request content.",
"instance":"/api/books",
"errors":[{"field":"title","message":"must not be blank","rejectedValue":""}]}
パラメーター
@RequestBody() にパラメーターはありません。
ボディの読み方
引数の型で決まります。
| 型 | 読み方 | Content-Type |
|---|---|---|
クラス、List、Map など |
ObjectMapper を通した JSON |
application/json、application/*+json、*/*。それ以外は 415 |
フォームでの Map<String, String>(または他の Map) |
フォームのフィールド。@RequestParam の値と同じように変換される | application/x-www-form-urlencoded |
String |
テキスト | 任意 |
Uint8List、List<int> |
生のバイト | 任意 |
Stream<Uint8List> |
届いた順のボディ。読まれていない状態 | 任意 |
ルール:
- メディアタイプが最初にチェックされます。 Spring が最初にコンバーターを選ぶのと同じく、ボディを読む前です。そもそもメディアタイプでない
Content-Typeは、引数の型にかかわらず 415 です。 Content-Typeがない場合。 ボディは Spring と同様にapplication/octet-streamになります。ボディを持つPOST、PUT、PATCHのオブジェクトでは 415 です。ボディがない場合(または別のメソッドの場合)は、ボディがないものとして扱われます。- テキストのエンコーディング。 テキストは UTF-8 です。
Content-Typeがcharset=iso-8859-1(またはlatin1)を示す場合は Latin-1 です。不正な UTF-8 のバイトは U+FFFD になります。 - サイズ。
server.max-http-request-body-size(デフォルト 10 MB)を超えるボディは 413(PayloadTooLargeErrorException)です。Stream<Uint8List>の引数はボディを自分で読むもので、大きなボディ向けです。server.connection-timeout(60 秒)の間何も送らないボディは 408 です(タイムアウト を参照)。 - 1 つのメソッドに 1 つのボディ。 2 つの
@RequestBody引数は起動を止めます。 - JSON のクラス。 コントローラーがボディとして受け取る同じパッケージのクラスは、自動的にイントロスペクトされます。コンストラクターとセッター(
@Valid()があれば、制約を持つプロパティのゲッターも)です。イミュータブルなクラスはコンストラクターを通して作られます(JSON を参照)。クラスに合わない JSON(必須のプロパティがない、型が違う)は 400 です。
必須か省略可能か
| ボディが空で、引数が | 結果 |
|---|---|
nullable: @RequestBody() Book? book |
null |
| デフォルト値付き | 呼び出しから省かれる: Dart のデフォルト |
| それ以外 | 400 Failed to read request(HttpMessageNotReadableException) |
不正な形式の JSON と、形の合わない JSON は同じ 400 になります。その詳細は意図的にあいまいにしてあります。理由は例外の message(JSON parse error: ...、Required request body is missing: BookController.create)にあり、@ExceptionHandler で読めます。クライアントに送られることはありません。
バリデーション: @Valid() と @Validated()
@RequestBody()と並べた@Valid()は、アプリケーションのValidatorBean(spring_boot_dartのdefaultValidator、BeanValidator)でオブジェクトの制約をチェックします。制約 を参照してください。@Validated([Group, ...])は、同じことをバリデーショングループで行います。通常の制約も残すにはDefaultを列挙します。- 違反 は
MethodArgumentNotValidExceptionを投げます。problem のdetailがInvalid request content.で、errorsリストを持つ 400 です。フィールドのエラーは{"field", "message", "rejectedValue"}、オブジェクト全体のエラーは{"object", "message"}です。メッセージはアプリケーションのMessageSourceを通して解決されるため、messages.propertiesで文言を決められます(MessageSource を参照)。なければデフォルトのメッセージが使われます。 - アップロードの JSON パートでも同じことができます:
@RequestPart('book') @Valid() NewBook book(アップロード を参照)。 nullのボディは検証されません。 ボディが必須なら non-nullable の引数を使ってください。- バリデーターがなければチェックもありません。
ValidatorBean が複数あり、どれも@Primaryでない場合、バリデーターは選ばれず、@Valid()のボディは警告なしにチェックされません。 - 違反に別の形で応答するには、
MethodArgumentNotValidException用の@ExceptionHandlerを書きます(@ExceptionHandler を参照)。
Spring (Java) との対応
@PostMapping("/api/books")
@ResponseStatus(HttpStatus.CREATED)
Book create(@RequestBody @Valid NewBook book) { ... }
@PatchMapping("/api/books/{isbn}/touch")
Book touch(@PathVariable String isbn,
@RequestBody(required = false) Book book) { ... }
重要な違い:
@RequestBody(required = false)は nullable な引数です。- 違反の応答は常に
errorsリストを持つProblemDetailです。Spring Boot のデフォルトは、spring.mvc.problemdetails.enabled=trueでない限り/errorの JSON です。 HttpMessageConverterBean はありません。JSON はObjectMapperを通り、テキスト、バイト、ストリーム、フォームの扱いは固定です。Stream<Uint8List>のボディには Spring MVC に対応するものがありません(Spring WebFlux のFlux<DataBuffer>にあたります)。