
# @RequestBody

`@RequestBody()` は、コントローラーの引数をリクエストのボディにバインドします。オブジェクトは JSON から読まれ、`String`、バイト、バイトストリーム、フォームの `Map` はそれぞれの方法で読まれます。`@Valid()` を付けると、オブジェクトが検証されます。

## 使う理由

`POST`、`PUT`、`PATCH` は、データを通常 JSON としてボディで送ります。このアノテーションはボディを読み、アプリケーションの `ObjectMapper` を通して引数の型にデコードし、制約をチェックし、クライアントの誤りに代わりに応答します。JSON でないボディには 415、解析できない JSON や合わない JSON には 400、制約を破るフィールドを列挙した 400 です。

## 例

```dart
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;
}
```

検証に失敗した場合:

```text
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](request-param.md) の値と同じように変換される | `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 です（[タイムアウト](../server/timeouts.md) を参照）。
- **1 つのメソッドに 1 つのボディ。** 2 つの `@RequestBody` 引数は起動を止めます。
- **JSON のクラス。** コントローラーがボディとして受け取る同じパッケージのクラスは、自動的にイントロスペクトされます。コンストラクターとセッター（`@Valid()` があれば、制約を持つプロパティのゲッターも）です。イミュータブルなクラスはコンストラクターを通して作られます（[JSON](../../spring-core-dart/json/index.md) を参照）。クラスに合わない 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](../errors/exception-handler.md) で読めます。クライアントに送られることはありません。

## バリデーション: `@Valid()` と `@Validated()`

- `@RequestBody()` と並べた **`@Valid()`** は、アプリケーションの `Validator` Bean（`spring_boot_dart` の `defaultValidator`、`BeanValidator`）でオブジェクトの制約をチェックします。[制約](../../spring-core-dart/validation/constraints.md) を参照してください。
- **`@Validated([Group, ...])`** は、同じことをバリデーショングループで行います。通常の制約も残すには `Default` を列挙します。
- **違反** は `MethodArgumentNotValidException` を投げます。problem の `detail` が `Invalid request content.` で、`errors` リストを持つ 400 です。フィールドのエラーは `{"field", "message", "rejectedValue"}`、オブジェクト全体のエラーは `{"object", "message"}` です。メッセージはアプリケーションの `MessageSource` を通して解決されるため、`messages.properties` で文言を決められます（[MessageSource](../../spring-core-dart/messages/message-source.md) を参照）。なければデフォルトのメッセージが使われます。
- アップロードの **JSON パートでも同じことができます**: `@RequestPart('book') @Valid() NewBook book`（[アップロード](../streaming/uploads.md) を参照）。
- **`null` のボディは検証されません。** ボディが必須なら non-nullable の引数を使ってください。
- **バリデーターがなければチェックもありません。** `Validator` Bean が複数あり、どれも `@Primary` でない場合、バリデーターは選ばれず、`@Valid()` のボディは警告なしにチェックされません。
- 違反に別の形で応答するには、`MethodArgumentNotValidException` 用の `@ExceptionHandler` を書きます（[@ExceptionHandler](../errors/exception-handler.md) を参照）。

## Spring (Java) との対応

```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 です。
- `HttpMessageConverter` Bean はありません。JSON は `ObjectMapper` を通り、テキスト、バイト、ストリーム、フォームの扱いは固定です。
- `Stream<Uint8List>` のボディには Spring MVC に対応するものがありません（Spring WebFlux の `Flux<DataBuffer>` にあたります）。

## 関連項目

- [バリデーション](../../spring-core-dart/validation/index.md)
- [JSON](../../spring-core-dart/json/index.md)
- [アップロード](../streaming/uploads.md)
- [ProblemDetail](../errors/problem-detail.md)
