エラー、リトライ、タイムアウト

400 以上のステータスのレスポンスは FeignException のサブクラスを投げるため、呼び出し元は自分が扱うケースだけを正確に捕まえられます。Retryer は後で成功するかもしれないもの (接続エラー、タイムアウト、Retry-After) を再試行し、call-timeout は呼び出し全体を制限し、すべてが失敗したときは fallback が応答します。

使う理由

リモートの呼び出しは、ローカルの呼び出しにはない形で失敗します。サービスがダウンしている、遅い、過負荷である、あるいはエラーで応答する、などです。それぞれのケースをすべての呼び出しの周りで手で扱うコードは長く、一貫しません。型付きの例外、クライアントごとのリトライのポリシー、時間の厳格な上限があれば、呼び出しの周りのコードは一つの try で済みます。

例

// ない本はショップにとってエラーではないが、それ以外はエラー。
Future<Book?> find(String isbn) async {
  try {
    return await catalog.find(isbn);
  } on FeignNotFound {
    return null;
  } on FeignException catch (error) {
    log.warning('catalog failed: ${error.status} ${error.responseBody}');
    rethrow;
  }
}
@Configuration()
class FeignSetup {
  // 呼び出しごとに最大 3 回の試行: 150 ms、次に 225 ms の待機。
  @Bean()
  Retryer retryer() => const DefaultRetryer(maxAttempts: 3);

  // カタログの 404 はショップ自身の例外になる。
  @Bean()
  ErrorDecoder errorDecoder() => ShopErrors();
}

final class ShopErrors implements ErrorDecoder {
  @override
  Exception decode(String methodKey, HttpResponse response) =>
      response.statusCode == 404
          ? BookNotFound(response.request!.url.path)
          : const DefaultErrorDecoder().decode(methodKey, response);
}
spring.feign.client.config.catalog.call-timeout=5s

例外

状況 例外
400、401、403、404、405、406、409、410、415、422、429 FeignBadRequest、FeignUnauthorized、FeignForbidden、FeignNotFound、FeignMethodNotAllowed、FeignNotAcceptable、FeignConflict、FeignGone、FeignUnsupportedMediaType、FeignUnprocessableEntity、FeignTooManyRequests (すべて FeignClientException)
その他の 4xx FeignClientException
500、501、502、503、504 FeignInternalServerError、FeignNotImplemented、FeignBadGateway、FeignServiceUnavailable、FeignGatewayTimeout (すべて FeignServerException)
その他の 5xx FeignServerException
Retry-After ヘッダーのあるレスポンス レスポンスのステータスを持つ RetryableException
レスポンスがない (接続の失敗、タイムアウト) ステータス -1 の RetryableException
call-timeout または呼び出し元の期限が過ぎた FeignCallTimeoutException、ステータス -1
戻り値の型に合わないボディ DecodeException
リクエストに書き込めない引数 何かが送られる前に EncodeException

FeignException は status、message、request、responseBody、responseHeaders、cause を持ちます。dismiss404 では、404 は代わりに null (または ResponseEntity) を返します。void メソッドは引き続き例外を投げます。

ErrorDecoder

ErrorDecoder の Bean (または error-decoder プロパティ、またはクライアントの構成クラスの Bean) は、レスポンスを例外に変えます。無視された 404 と HttpResponse を返すメソッドを除き、2xx 以外のすべてのステータスで呼ばれます。応答をリトライ可能にするには、たとえばすべての 503 について、RetryableException を返してください。

リトライ

Spring Cloud OpenFeign と同じく、デフォルトでは何もリトライされません。Retryer の Bean は RetryableException だけをリトライします。接続エラー、タイムアウト、そして Retry-After ヘッダー (秒または HTTP の日付で) を持つレスポンスです。エラーのステータスだけではリトライされません。各試行は引数から作り直され、インターセプターを通るため、その間に更新されたトークンはリトライに届きます。

DefaultRetryer は Feign の Retryer.Default と同じく動きます。

パラメーター デフォルト 意味
maxAttempts 5 最初のものを含めた試行の総数。
period 100ms 基本の待機。試行 n の後の待機は period × 1.5ⁿ (150 ms、225 ms、338 ms...)。
maxPeriod 1s 最長の待機。サーバーが Retry-After を送った場合は、代わりにその時刻まで待つ。それでも最大 maxPeriod。

独自の Retryer は nextDelay(attempt, error) を実装します。次の試行の前の待機、またはあきらめるなら null です。Retryer.never は決してリトライしません。

タイムアウト

設定 制限するもの
connect-timeout (10s、default の下でのみ) 各接続。
read-timeout (60s) データの各待機: レスポンスを、次にボディの 2 つのチャンクの間を。呼び出し全体ではない。
call-timeout (なし) 呼び出し全体: すべての試行、Retryer の待機、応答の待機。

call-timeout

read-timeout は各待機を制限し、Retryer は試行を増やすため、一回の呼び出しはどのタイムアウトが示すよりずっと長くかかることがあります。call-timeout は、呼び出しが全体でかけてよい時間です。

それが過ぎると、呼び出しは FeignCallTimeoutException (attempts の数と、上限が呼び出し元の期限だったかどうかを持つ) を投げます。時間はもう残っていないため、決してリトライされません。上限を超えて終わるはずの待機は、呼び出しをすぐに終わらせます。それでも fallback は応答します。各試行の接続と読み取りのタイムアウトは残り時間で制限されるため、60 秒の read-timeout が 5 秒の call-timeout より長く続くことはありません。

呼び出し元の期限

Web のリクエストを処理している間 (Web スターターの server.request-timeout)、または RequestDeadline.run(...) の中で行われた呼び出しには、2 つ目の上限があります。それを行うコードの期限です。呼び出しは 2 つのうち早い方で制限されるため、そのリクエストより長く生き残ることはありません。インターセプターも同じ上限のもとで実行されます。

// クライアントが何をしようと、チェックアウト全体で最大 2 秒。
final order = await RequestDeadline.run(const Duration(seconds: 2), () async {
  final stock = await warehouse.reserve(basket);
  return payments.charge(basket, stock);
});

フォールバック

フォールバックは、呼び出しが失敗したときにリモートのサービスの代わりに応答します。たとえばキャッシュしたデータや代替のデータで応答します。同じインターフェースを実装する Bean のクラスです。

@FeignClient('motd', url: r'${motd.url}', fallback: OfflineMotd)
abstract interface class MotdApi {
  @GetMapping('/motd')
  Future<String> messageOfTheDay();
}

// サービスに到達できない間にアプリが表示するもの。
@Component()
class OfflineMotd implements MotdApi {
  @override
  Future<String> messageOfTheDay() async => 'offline, try later';
}

Spring (Java) との対応

@Bean
Retryer retryer() { return new Retryer.Default(100, 1000, 3); }

例外、ErrorDecoder、Retryer.Default は Feign と同じく動作します。call-timeout と呼び出し元の期限は追加されたものです。Spring Cloud OpenFeign は、各試行の接続と読み取りだけを制限します。

関連項目