
# HTTP の型

サーバー、クライアント、テストが共有する、リクエストとレスポンスの構成要素です。ステータスとヘッダーを持つレスポンス (`ResponseEntity`)、ヘッダー (`HttpHeaders`)、ステータスコード (`HttpStatus`)、メディアタイプ (`MediaType`)、標準のエラーボディ (`ProblemDetail`)、そしてマルチパートのファイルです。

## 使う理由

コントローラーも、Feign クライアントも、テストも、同じものについて話します。404、`Content-Type`、JSON のエラーボディです。Spring の名前を持つ一つの型の集まりにすることで、それらは交換可能で、なじみやすいものになります。

## 例

```dart
// トークンを求める API への呼び出しのヘッダー。
final headers = HttpHeaders()
  ..contentType = MediaType.applicationJson
  ..setBearerAuth(token);
headers.forEach((name, values) => log.debug('$name: ${values.join(', ')}'));

// ステータスコードは int なので、直接比較できる。
if (response.statusCode.is2xxSuccessful) { /* ... */ }
if (response.statusCode == HttpStatus.notFound) { /* ... */ }
HttpStatus.valueOf(503).reasonPhrase; // 'Service Unavailable'

// ステータスと Location ヘッダーを持つコントローラーの応答。
ResponseEntity<Book> created(Book book) =>
    ResponseEntity.created(Uri.parse('/api/books/${book.isbn}')).body(book);

// 存在しない本へのリクエストに対する応答。
final problem = ProblemDetail.forStatusAndDetail(HttpStatus.notFound, 'No book 978-0')
  ..setProperty('isbn', '978-0'); // クライアントがどの本かを表示できる
problem.toJson();
// {type: about:blank, title: Not Found, status: 404, detail: No book 978-0, isbn: 978-0}
```

## レスポンス、ヘッダー、ステータス

| 型 | Spring | 内容 |
|---|---|---|
| `ResponseEntity<T>` | `ResponseEntity<T>` | ステータスコード、ヘッダー、ボディ。`ResponseEntity.ok(body)`、`ResponseEntity.created(uri).body(x)`、`ResponseEntity.notFound().build()`、`ResponseEntity.status(s)`、`accepted()`、`noContent()`、`badRequest()`、`unprocessableContent()`、`internalServerError()`、`ResponseEntity.of(nullableBody)` (または `ofNullable`)。 |
| `HttpHeaders` | `HttpHeaders` | 名前ごとのヘッダー。大文字小文字を区別せず、名前ごとに複数の値を持ち、順序と大文字小文字の表記を保つ。`forEach((name, values))`、`toSingleValueMap()`、`toMap()`、`getAll`、`operator []` (最初の値)。型付きのアクセサー `contentType`、`accept`、`eTag`、`ifNoneMatch`、`lastModified`、`date`、`contentDisposition`、`location`、`contentLength`。`setBearerAuth`、`setBasicAuth`。`HttpHeaders.contentTypeHeader` のような定数。 |
| `HttpStatus` | `HttpStatus` | Spring 7 のすべてのステータスを `int` の定数として (`notFound`、`unprocessableContent`、`contentTooLarge`...)。`reasonPhrase`、`series`、`is2xxSuccessful`、`is4xxClientError`、`isError`。`valueOf(404)`、`resolve(599)`。`100 Continue` は `HttpStatus.continue_`。 |
| `HttpStatusCode` | `HttpStatusCode` | 任意のステータスコード。定数のないものも: `HttpStatusCode.valueOf(599).is5xxServerError`。レスポンスの `statusCode` はこの型。 |
| `HttpStatusSeries` | `HttpStatus.Series` | `informational`、`successful`、`redirection`、`clientError`、`serverError`。 |
| `HttpMethod` | `HttpMethod` | `get`、`post`...。`value` はテキスト (`GET`)、`parse('POST')` はそれを読む (大文字小文字を区別する。それ以外のテキストは例外を投げる)。 |
| `MediaType` | `MediaType` | 文字列としての定数 (`applicationJson`、`applicationProblemJson`...)。アノテーションで使える。`MediaType.parse` は `includes`、`isCompatibleWith`、`charset`、`qualityValue` を持つオブジェクトを返す。 |
| `CacheControl` | `CacheControl` | `Cache-Control` の値: `CacheControl.maxAge(d)`、`.noCache()`、`.noStore()`、`.empty()`、その後に追加のディレクティブ。 |

## エラー: ProblemDetail

API のエラーには、クライアントが読めるボディが必要です。`ProblemDetail` はその標準 (RFC 9457、`application/problem+json`) で、ステータス、短いタイトル、詳細のテキスト、任意の追加フィールドを持ちます。

| 型 | Spring | 内容 |
|---|---|---|
| `ProblemDetail` | `ProblemDetail` | `type` (デフォルトは `about:blank`)、`title` (デフォルトはステータスのリーズンフレーズ)、`status`、`detail`、`instance`、追加の `properties`。`forStatus`、`forStatusAndDetail`、`setProperty`、`toJson`、`fromJson`。 |
| `ErrorResponse` | `ErrorResponse` | 自分の応答を知っている例外: `statusCode`、`headers`、`body` (`ProblemDetail`)。 |
| `ErrorResponseException` | 同じ | 投げたり継承したりするための `ErrorResponse`: `ErrorResponseException(status, body:, headers:, cause:)`。 |
| `ResponseStatusException` | 同じ | ステータスで失敗する最も短い方法: `throw ResponseStatusException(HttpStatus.notFound, 'No book 9')`。 |

Web サーバーは、自分のエラーに `ProblemDetail` を書きます ([Web スターターの ProblemDetail](../spring-boot-starter-web/errors/problem-detail.md) を参照)。

## マルチパートとファイル

アップロードは `multipart/form-data` として運ばれます。パートからなる一つのボディで、各パートはフォームのフィールドかファイルです。

| 型 | Spring | 内容 |
|---|---|---|
| `MultipartFile` | `MultipartFile` | アップロードされたファイル: `name`、`originalFilename`、`contentType`、`size`、`isEmpty`、`headers`、`bytes`、`openRead()`、`transferTo(path)`。 |
| `InMemoryMultipartFile` | `MockMultipartFile` (おおよそ) | メモリ上に保持される `MultipartFile`。クライアントが送るファイルなど (`InMemoryMultipartFile.fromString(name, text)`)。 |
| `MultipartParser` | `StandardServletMultipartResolver` の解析 | `multipart/*` のボディを、届くそばからパートごとに読む: `MultipartParser.boundaryOf(contentType)`、`bind(body)`。 |
| `MultipartBody`、`MultipartBodyPart` | `MultipartBodyBuilder` | `MultipartBodyPart.field`、`.file`、`.json` のパートからボディを書く。`contentType` (境界付き)、`encode()`。 |
| `MediaTypeFactory` | `MediaTypeFactory` | ファイル名のメディアタイプ: `MediaTypeFactory.getMediaType('cover.png')` は `image/png`。不明なら `null`。 |

```dart
// 素のトランスポートで、本をその表紙とともにアップロードする。
final body = MultipartBody([
  MultipartBodyPart.field('title', 'Dune'),
  MultipartBodyPart.file('cover', bytes, filename: 'dune.png'), // 名前から image/png
]);
await transport.send(HttpRequest(
  method: HttpMethod.post,
  url: Uri.parse('https://api.neon.books/books'),
  headers: HttpHeaders({HttpHeaders.contentTypeHeader: body.contentType}),
  body: body.encode(),
));
```

## Spring (Java) との対応

名前は Spring のもので、形は Dart のものです。`HttpStatus` の定数は `int` で (`name()` はない)、`HttpHeaders` の定数は `Header` で終わり (単なる名前は型付きのアクセサーです)、`MediaType` の定数は文字列で、`ResponseEntity.of` は nullable なボディを受け取ります。すべての違いは [Spring との違い](differences.md) にあります。

## 関連項目

- [サーバー側](server-side.md)
- [HTTP トランスポート](http-transport.md)
- [Web スターターのアップロード](../spring-boot-starter-web/streaming/uploads.md)
