HTTP クライアント

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

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

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。 リクエストを組み立て、送り、ステータスをチェックし、ボディをデコードします。

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 以外のステータスは、デフォルトで例外を投げます。

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 用に記述されます。

@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;
}
catalog.url=https://api.neon.books

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

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

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

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

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

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

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

@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 はチェックです。

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

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

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 を返させます。

@GetMapping('/books/{isbn}')
Future<Book?> find(@PathVariable() String isbn);
spring.feign.client.config.catalog.dismiss404=true

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

タイムアウト

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

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 です。

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

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

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。 自分で書くループです。

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 パッケージがインターセプターを追加します。

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

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

@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 の呼び出しを運ぶこともできます。

関連項目