@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> 届いた順のボディ。読まれていない状態 任意

ルール:

必須か省略可能か

ボディが空で、引数が 結果
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()

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) { ... }

重要な違い:

関連項目