HTTP クライアント
このページでは、同じ呼び出しを三通りで行います。カタログサービスから JSON で本を取得し、クラスにデコードし、トークンを送り、404 を「その本はない」として扱い、時間を制限し、接続が失敗したら再試行します。
spring_web_dartのplatformHttpTransport(): VM、Flutter、ブラウザーで動く小さな HTTP 層。手で使うと、素の Dart の基準になります。dio: オプションとインターセプターを持つ、人気のある HTTP クライアントのパッケージ。spring_boot_starter_feignの Feign クライアント: ジェネレーターが実装を書く、アノテーション付きのインターフェース。
素の版は、手書きの 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 の呼び出しを運ぶこともできます。