spring_boot_starter_feign
spring_boot_starter_feign は Spring for Dart に宣言的な HTTP クライアントを提供します。Spring Cloud OpenFeign に当たる Dart のものです。リモートの API を、エンドポイントごとに一つのメソッドを持ち、コントローラーと同じマッピングのアノテーションを使う抽象クラスとして記述します。他の Bean と同じようにそれを注入し、メソッドを呼べばリクエストが送られ、デコードされた応答が得られます。
使う理由
別のサービスを手で呼ぶには、エンドポイントごとに、URL を組み立て、JSON をエンコードし、リクエストを送り、ステータスを確認し、応答をデコードする必要があります。スターターがその部分を行います。
- ジェネレーターが、リフレクションなしに、ビルド時に実装を書きます。
- JSON は
spring_core_dartのObjectMapperを通ります。 - エラーのステータスは、捕まえられる例外 (
FeignNotFound、FeignServiceUnavailable...) になります。 - タイムアウト、呼び出し全体の上限、ロギング、リトライ、リクエストのインターセプター、フォールバックはクライアントごとに設定します。
- マルチパートのアップロード、フォームのボディ、再接続付きのサーバー送信イベントに対応しています。
他のサービスを呼ぶサーバーや、バックエンドを呼ぶ Flutter アプリで使います。トランスポートは、VM と Flutter では dart:io、Web では fetch です。
セットアップ
# pubspec.yaml
dependencies:
spring_boot_starter_feign: ^0.9.0
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0 # 必須: クライアントの実装を書く
spring_boot_starter_test: ^0.9.0 # テストのための MockHttpTransport
test: ^1.33.0
インポートは一つで足ります。package:spring_boot_starter_feign/spring_boot_starter_feign.dart は spring_boot_dart、spring_web_dart (マッピングのアノテーション)、spring_boot_starter_logging を再エクスポートします。
例
import 'package:spring_boot_starter_feign/spring_boot_starter_feign.dart';
import 'spring_gen/main.spring.dart';
// ショップが呼ぶ、カタログサービスの API。
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogClient {
@GetMapping('/books/{isbn}')
Future<Book> find(@PathVariable() String isbn);
// GET /books?q=dune&page=2。page が null なら省かれる。
@GetMapping('/books')
Future<List<Book>> search(@RequestParam('q') String query, {@RequestParam() int? page});
// 本は JSON として送られる。応答はステータスとヘッダーも返す。
@PostMapping('/books')
Future<ResponseEntity<Book>> create(@RequestBody() Book book);
@DeleteMapping('/books/{isbn}')
Future<void> delete(@PathVariable() String isbn);
}
class Book {
const Book({required this.isbn, required this.title});
final String isbn;
final String title;
}
@Service()
class Shop {
Shop(this.catalog); // 生成されたクライアント。他の Bean と同じく注入される
final CatalogClient catalog;
Future<String?> title(String isbn) async {
try {
return (await catalog.find(isbn)).title;
} on FeignNotFound {
return null; // ない本はショップにとってエラーではない
}
}
}
@SpringBootApplication()
void main(List<String> args) => runApplication(args);
# lib/resources/application.properties
catalog.url=https://api.neon.books
spring.feign.client.config.default.read-timeout=10s
spring.feign.client.config.catalog.logger-level=basic
クライアントのメソッドが受け取ったり返したりするクラスは、クライアントと同じパッケージにあれば、JSON のために自動的に記述されます。応答はそのコンストラクターとセッターで、引数はそのゲッターで記述されます。クラスに @Introspected() を付けると、すべてが記述されます。
起動するもの
@EnableFeignClientsはありません。 スキャンされたパッケージの、@FeignClientを持つすべての抽象クラスが、インターフェースにちなんだ名前 (CatalogClient→catalogClient) の Bean になり、デフォルトで@Primaryです。- すべてのクライアントは起動時にチェックされます。 パラメーターのないパス変数、マッピングのないメソッド、クエリの値としてのオブジェクト、URL のないクライアントは、理由とともにアプリケーションを止めます。
- トランスポートは共有されます。 すべてのクライアントは
HttpTransportの Bean (独自に宣言しなければplatformHttpTransport()) を通して送ります。
内容
- メソッド: マッピングのアノテーション、パラメーター、結果、フォームのボディ、起動時のチェック。
- ファイルとマルチパート:
@RequestPartのアップロード。 - サーバー送信イベント: 再接続付きの
EventStream<T>。 - 設定:
spring.feign.client.config.<name>.*、@FeignClientの属性、クライアントごとの Bean。 - エラー、リトライ、タイムアウト: 例外、
ErrorDecoder、Retryer、call-timeout、フォールバック。 - インターセプター: すべてのリクエストのヘッダーとトークン。
- ロギング:
logger-levelとマスクされるヘッダー。 - テスト:
MockHttpTransportとトランスポート。 - すべてのプロパティ: スターターのすべてのキー。
- Spring との違い: Spring Cloud OpenFeign と動作が異なる点。
Spring (Java) との対応
@EnableFeignClients
@SpringBootApplication
class ShopApplication { ... }
@FeignClient(name = "catalog", url = "${catalog.url}")
interface CatalogClient {
@GetMapping("/books/{isbn}")
Book find(@PathVariable String isbn);
}
重要な違い:
- メソッドは
Futureを返します。@EnableFeignClientsはありません。 - プロパティは
spring.cloud.openfeign.*ではなくspring.feign.*です。 - サービスディスカバリーはありません。すべてのクライアントに URL が必要です。
- すべての違いは Spring との違い にあります。