
# HTTP クライアント

このページでは、同じ呼び出しを三通りで行います。カタログサービスから JSON で本を取得し、クラスにデコードし、トークンを送り、404 を「その本はない」として扱い、時間を制限し、接続が失敗したら再試行します。

- `spring_web_dart` の **`platformHttpTransport()`**: VM、Flutter、ブラウザーで動く小さな HTTP 層。手で使うと、素の Dart の基準になります。
- **`dio`**: オプションとインターセプターを持つ、人気のある HTTP クライアントのパッケージ。
- `spring_boot_starter_feign` の **Feign クライアント**: ジェネレーターが実装を書く、アノテーション付きのインターフェース。

素の版は、手書きの `fromJson` でデコードします。

```dart
class Book {
  const Book({required this.isbn, required this.title});

  factory Book.fromJson(Map<String, dynamic> json) =>
      Book(isbn: json['isbn'] as String, title: json['title'] as String);

  final String isbn;
  final String title;
}
```

## 取得してデコードする

**platformHttpTransport。** リクエストを組み立て、送り、ステータスをチェックし、ボディをデコードします。

```dart
final transport = platformHttpTransport();

Future<Book> find(String isbn) async {
  final response = await transport.send(HttpRequest(
    method: HttpMethod.get,
    url: Uri.parse('https://api.neon.books/books/$isbn'),
  ));
  if (!response.isSuccess) throw StateError('catalog: ${response.statusCode}');
  return Book.fromJson(jsonDecode(response.bodyText) as Map<String, dynamic>);
}
```

**dio。** ベース URL は一度だけ設定します。`data` はすでに JSON からデコードされています。2xx 以外のステータスは、デフォルトで例外を投げます。

```dart
final dio = Dio(BaseOptions(baseUrl: 'https://api.neon.books'));

Future<Book> find(String isbn) async {
  final response = await dio.get<Map<String, dynamic>>('/books/$isbn');
  return Book.fromJson(response.data!);
}
```

**Feign。** エンドポイントごとに一つのメソッドです。`Book` に `fromJson` は不要です。クライアントが返すクラスは、同じパッケージにあれば、コンストラクターから JSON 用に記述されます。

```dart
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogClient {
  @GetMapping('/books/{isbn}')
  Future<Book> find(@PathVariable() String isbn);
}

@Service()
class Shelf {
  Shelf(this.catalog); // 生成されたクライアントが注入される
  final CatalogClient catalog;
}
```

```properties
catalog.url=https://api.neon.books
```

変わること: トランスポートではすべてを自分で書きます。dio は URL の結合とデコードの手順を取り除きます。Feign はメソッドの本体を取り除きます。Feign クライアントには `build_runner` が必要で、呼び出しは注入される Spring のアプリケーションの中にしか存在しません。

## すべてのリクエストにヘッダーを付ける

**platformHttpTransport。** 組み立てる各リクエストに追加します。

```dart
headers: HttpHeaders()..setBearerAuth(tokens.accessToken),
```

**dio。** インターセプターを一度追加します。

```dart
dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) {
    options.headers['Authorization'] = 'Bearer ${tokens.accessToken}';
    handler.next(options);
  },
));
```

**Feign。** `RequestInterceptor` Bean がすべてのクライアントに適用されます。既製のものが Bearer トークンを送ります。

```dart
@Configuration()
class FeignSetup {
  @Bean()
  RequestInterceptor auth(TokenStore tokens) =>
      BearerTokenRequestInterceptor(() => tokens.accessToken);
}
```

固定のヘッダーは設定から取ることもできます: `spring.feign.client.config.catalog.default-request-headers.X-Api-Key=${CATALOG_KEY}`。

変わること: dio と Feign はどちらも一度だけ設定します。Feign のインターセプターは再試行のたびに再び実行されるので、更新されたトークンが次の試行に届き、一つのクライアントに限定することもできます。

## 見つからない本 (404)

**platformHttpTransport。** すべてのステータスは普通の応答なので、404 はチェックです。

```dart
if (response.statusCode == HttpStatus.notFound) return null;
```

**dio。** 404 は応答を持つ `DioException` を投げます。

```dart
try {
  return Book.fromJson((await dio.get<Map<String, dynamic>>('/books/$isbn')).data!);
} on DioException catch (e) {
  if (e.response?.statusCode == 404) return null;
  rethrow;
}
```

**Feign。** 404 は `FeignNotFound` を投げます。または、クライアントに `null` を返させます。

```dart
@GetMapping('/books/{isbn}')
Future<Book?> find(@PathVariable() String isbn);
```

```properties
spring.feign.client.config.catalog.dismiss404=true
```

変わること: Feign にはステータスごとに一つの例外クラス (`FeignNotFound`、`FeignConflict`、`FeignServiceUnavailable` など) があるので、`catch` は扱うケースを名前で示せます。`dismiss404` は、最もよくあるケースを設定に変えます。

## タイムアウト

**platformHttpTransport。** トランスポートに接続のタイムアウトを、リクエストに読み取りのタイムアウト (データを待つたびの) と交換全体の期限を設定します。タイムアウトは `isTimeout` が設定された `HttpTransportException` を投げます。

```dart
final transport = platformHttpTransport(connectTimeout: const Duration(seconds: 3));

HttpRequest(
  method: HttpMethod.get,
  url: url,
  readTimeout: const Duration(seconds: 10),
  timeout: const Duration(seconds: 15),
);
```

**dio。** オプションに設定します。タイムアウトは、型が `connectionTimeout` または `receiveTimeout` の `DioException` です。

```dart
final dio = Dio(BaseOptions(
  baseUrl: 'https://api.neon.books',
  connectTimeout: const Duration(seconds: 3),
  receiveTimeout: const Duration(seconds: 10),
));
```

**Feign。** 設定で、クライアントごと、またはすべてに対して設定します。

```properties
spring.feign.client.config.default.connect-timeout=3s
spring.feign.client.config.catalog.read-timeout=10s
spring.feign.client.config.catalog.call-timeout=15s
```

変わること: 値がコードからファイルに移るので、テストやプロファイルがそれを変えられます。`call-timeout` は、すべての再試行と待ち時間を含む呼び出し全体を制限し、`FeignCallTimeoutException` を投げます。Web のリクエストを処理している間に行われる Feign の呼び出しは、そのリクエストの期限にも制限されます。

## 再試行

**platformHttpTransport。** 自分で書くループです。

```dart
for (var attempt = 1; ; attempt++) {
  try {
    return await send();
  } on HttpTransportException {
    if (attempt == 3) rethrow;
    await Future<void>.delayed(Duration(milliseconds: 150 * attempt));
  }
}
```

**dio。** 組み込みではありません。`dio_smart_retry` パッケージがインターセプターを追加します。

```dart
dio.interceptors.add(RetryInterceptor(
  dio: dio,
  retries: 2,
  retryDelays: const [Duration(milliseconds: 150), Duration(milliseconds: 225)],
));
```

**Feign。** すべてのクライアントに、または `retryer` プロパティで一つのクライアントに、`Retryer` Bean を使います。

```dart
@Bean()
Retryer retryer() => const DefaultRetryer(maxAttempts: 3); // 150 ms、次に 225 ms の待ち時間
```

変わること: Feign が再試行するのは、後で成功しうるものだけです。接続のエラー、タイムアウト、`Retry-After` を持つ応答です。素の 503 のようなエラーのステータスだけでは、`ErrorDecoder` がそれに対して `RetryableException` を返さない限り再試行されません。`Retryer` が宣言されるまで、何も再試行されません。

## まとめ

| タスク | `platformHttpTransport()` | `dio` | Feign クライアント |
|---|---|---|---|
| ベース URL | 手で | `BaseOptions(baseUrl:)` | `@FeignClient(url:)`、設定から |
| JSON | `jsonDecode` + `fromJson` | デコードされた `data` + `fromJson` | 戻り値の型について自動 |
| すべての呼び出しにヘッダー | リクエストごと | インターセプター | `RequestInterceptor` Bean、またはプロパティ |
| 404 | ステータスのチェック | `DioException`、`response?.statusCode` をチェック | `FeignNotFound`、または `dismiss404` で `null` |
| タイムアウト | コードの `connectTimeout`、`readTimeout`、`timeout` | コードの `connectTimeout`、`receiveTimeout` | 設定の `connect-`、`read-`、`call-timeout` |
| 再試行 | ループ | `dio_smart_retry` | `Retryer` Bean |
| すべてが失敗したときのフォールバック | `catch` | `catch` | `@FeignClient(fallback:)` |
| プラットフォーム | VM、Flutter、Web | VM、Flutter、Web | VM、Flutter、Web (トランスポート上で) |
| テスト | `MockHttpTransport` | アダプターまたはモックのライブラリ | `BeanOverride<HttpTransport>(MockHttpTransport())` |
| ビルドの手順 | なし | なし | `build_runner` |

小さなアプリでの一つか二つの呼び出しなら、トランスポートや dio のほうが学ぶことが少なく、ビルドの手順も不要です。Feign クライアントは、アプリが多くのエンドポイントを呼ぶ場合、タイムアウト、ヘッダー、再試行を環境ごとに設定すべき場合、またはアプリがすでに Spring for Dart で動いている場合に元が取れます。二つは組み合わせられます。Feign のスターターは `HttpTransport` Bean を通して送るので、dio の上に組み立てたトランスポートが Feign の呼び出しを運ぶこともできます。

## 関連項目

- [HTTP トランスポート](../components/spring-web-dart/http-transport.md)
- [spring_boot_starter_feign](../components/spring-boot-starter-feign/index.md)
- [エラー、再試行、タイムアウト](../components/spring-boot-starter-feign/errors-and-retries.md)
- [インターセプター](../components/spring-boot-starter-feign/interceptors.md)
- [設定](../components/spring-boot-starter-feign/configuration.md)
- [Feign クライアントのテスト](../components/spring-boot-starter-feign/testing.md)
