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

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

## 使う理由

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

## 例

```dart
// ない本はショップにとってエラーではないが、それ以外はエラー。
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;
  }
}
```

```dart
@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);
}
```

```properties
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 つのうち早い方で制限されるため、そのリクエストより長く生き残ることはありません。インターセプターも同じ上限のもとで実行されます。

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

## フォールバック

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

```dart
@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';
}
```

- フォールバックは、リトライの後に、404 も含めて**すべての**失敗に応答します。
- 生成されるクライアントは (`@FeignClient(primary: false)` でない限り) `@Primary` なので、`MotdApi` を注入するとフォールバックではなくクライアントが得られます。
- サーキットブレーカーと `FallbackFactory` はまだありません。

## Spring (Java) との対応

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

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

## 関連項目

- [設定](configuration.md)
- [インターセプター](interceptors.md)
- [Web スターターのタイムアウト](../spring-boot-starter-web/server/timeouts.md)
