
# HTTP トランスポート

`HttpTransport` は一つの `HttpRequest` を送り、ステータス、ヘッダー、ボディのバイトを持つ `HttpResponse` を返します。Feign クライアントと OAuth2 のトークンクライアントの下にある層で、置き換えることもできます。テストではモックに、あるいは Dio や `package:http` の上に作った独自のものにです。

## 使う理由

Dart には 2 つの HTTP スタックがあります。`dart:io` の `HttpClient` と、ブラウザーの `fetch` です。サーバー、Flutter アプリ、Web のどこでも動かなければならないコードには、同じタイムアウトとエラーを持つ、両者を覆う一つのインターフェースが必要です。`platformHttpTransport()` は適切な方を選びます。

## 例

```dart
final transport = platformHttpTransport(connectTimeout: const Duration(seconds: 3));
final response = await transport.send(
  HttpRequest(
    method: HttpMethod.post,
    url: Uri.parse('https://api.neon.books/books'),
    headers: HttpHeaders({HttpHeaders.contentTypeHeader: MediaType.applicationJson}),
    body: utf8.encode('{"isbn":"1"}'),
    readTimeout: const Duration(seconds: 60), // 遅いレポート: データをより長く待つ
  ),
);
if (response.statusCode.is2xxSuccessful) log.info(response.bodyText);
transport.close();
```

## トランスポート

| トランスポート | プラットフォーム | インポート |
|---|---|---|
| `platformHttpTransport()` | 下の 2 つのどちらかを選ぶ | `package:spring_web_dart/spring_web_dart.dart` |
| `IoHttpTransport` | VM、Android・iOS・デスクトップの Flutter (`dart:io` の `HttpClient`) | `package:spring_web_dart/io.dart` |
| `FetchHttpTransport` | Web、Flutter Web (`dart:js_interop` を通した `fetch`) | `package:spring_web_dart/browser.dart` |
| `MockHttpTransport` | テスト | `package:spring_web_dart/testing.dart`、または `spring_boot_starter_test` |
| 独自のもの | たとえば Dio や `package:http` の上に | `HttpTransport` (`send`、`stream`、`close`) を実装する |

## HttpRequest

| フィールド | 意味 |
|---|---|
| `method`、`url` | 必須。 |
| `headers` | `HttpHeaders`。デフォルトは空の書き込み可能なもの。 |
| `body` | バイト。 |
| `readTimeout` | データを待つ最長時間: まずレスポンスを、次にボディの 2 つのチャンクの間を。Spring と Feign の読み取りタイムアウト。 |
| `timeout` | やり取り全体の期限。Spring のリクエストファクトリーにはないもの。 |
| `followRedirects` | デフォルトは `true`。`false` では、`3xx` のレスポンスはたどられずに返される。 |

どちらのタイムアウトもデフォルトは `null` (上限なし) です。どちらかが切れると、リクエストは `isTimeout` が `true` の `HttpTransportException` で中止されます。

## レスポンスとエラー

- 404 や 500 を含め、どのステータスコードも通常のレスポンスです。`response.statusCode` を確認してください。
- `HttpTransportException` を投げるのは、ネットワークの失敗とタイムアウトだけです (`isTimeout` でどちらか分かります)。
- `HttpResponse` は、`statusCode` (`HttpStatusCode`)、`headers`、`body` (バイト)、`bodyText` (コンテンツタイプの `charset`、なければ UTF-8 でデコードしたもの)、`request` を持ちます。

## platformHttpTransport のオプション

| オプション | デフォルト | 意味 |
|---|---|---|
| `connectTimeout` | なし | 接続を開くのにかけてよい時間。ブラウザーでは無視される (`fetch` にはそうした設定がない)。 |
| `credentials` | `FetchCredentials.sameOrigin` | ブラウザーのみ: `fetch` がサーバーに Cookie を送るかどうか。 |
| `allowBadCertificates` | `false` | `dart:io` のみ: 期限切れ、自己署名、別のホストの証明書を受け入れる。`spring.remote.allow-insecure` の設定のダウンロード専用で、API には決して使わない。 |

`dart:io` も `dart:js_interop` もないプラットフォームでは `UnsupportedError` を投げます。そこでは独自のトランスポートを渡してください。

## プラットフォームごとの動作

- `IoHttpTransport` は `HttpClient` がたどる範囲でリダイレクトをたどり (`GET` と `HEAD`、および `POST` の後の `303`)、タイムアウトが切れるとリクエストを中止します。`connectTimeout` は各接続を制限します。
- `FetchHttpTransport` はリダイレクトをたどり (`followRedirects: false` ではブラウザーの不透明なリダイレクト、ステータス 0 になります)、`AbortController` を通して中止します。サーバーは CORS ヘッダーでリクエストを許可しなければなりません。ブロックされたリクエストは `HttpTransportException` になります。

## ストリーミングのレスポンス

大きなダウンロードや終わりのないレスポンスには、`transport.stream(request)` がステータスとヘッダーが届いた時点で戻り、ボディはバイトのチャンクとして来ます (`StreamedHttpResponse.body`)。リクエストの `timeout` と `readTimeout` は、ヘッダーを待つ間だけを対象にします。購読をキャンセルすると接続が閉じます。

```dart
final response = await transport.stream(request);
// エラーの応答は短い: メッセージのために丸ごと読む。
if (!response.isSuccess) throw StateError((await response.read()).bodyText);
await for (final chunk in response.body) {
  sink.add(chunk);
}
```

## アプリケーションで

Feign スターターは `HttpTransport` の Bean (独自に宣言しなければ `platformHttpTransport()`) を通して送り、その `connect-timeout` がデフォルトのものを設定します。すべてのクライアントのためにそれを置き換えるには、`HttpTransport` の Bean を宣言してください。テストでは `BeanOverride<HttpTransport>(MockHttpTransport())` がそうします。

## Spring (Java) との対応

```java
RestClient client = RestClient.builder().requestFactory(new JdkClientHttpRequestFactory()).build();
```

`HttpTransport` は、`RestClient` より低いレベルで、Spring の `ClientHttpRequestFactory` / `ClientHttpRequest` の役割を果たします。`timeout` の期限は追加されたものです。

## 関連項目

- [サーバー送信イベント](server-sent-events.md)
- [テスト](testing.md)
- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md)
