Client Plugin

失敗したリクエストの再試行

コード例: client-retry

デフォルトでは、Ktor クライアントは、ネットワークやサーバーのエラーにより失敗したリクエストを再試行しません。 HttpRequestRetry プラグインを使用すると、再試行回数の指定、リクエストを再試行するための条件設定、再試行前のリクエストの変更など、失敗したリクエストに対する再試行ポリシーをさまざまな方法で構成できます。

依存関係の追加

HttpRequestRetry は ktor-client-core アーティファクトのみを必要とし、特定の依存関係は必要ありません。

HttpRequestRetry のインストール

HttpRequestRetry をインストールするには、クライアント設定ブロック内で install 関数に渡します。

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    install(HttpRequestRetry)
}

HttpTimeout プラグインがインストールされている場合、タイムアウトに対する再試行を構成できるようにするために、HttpRequestRetry を先にインストールする必要があります。

val client = HttpClient(CIO) {
    install(HttpRequestRetry) // HttpTimeout よりも前にインストールする必要があります
    install(HttpTimeout) {
       // ...
     }
}

HttpRequestRetry の構成

基本的な再試行設定

以下の実行可能な例は、基本的な再試行ポリシーの構成方法を示しています。

val client = HttpClient(CIO) {
    install(HttpRequestRetry) {
        retryOnServerErrors(maxRetries = 5)
        exponentialDelay()
    }
}

• retryOnServerErrors 関数は、サーバーから 5xx レスポンスを受信した場合にリクエストの再試行を有効にし、再試行回数を指定します。
• exponentialDelay は、再試行間の指数関数的な遅延を指定します。これはエクスポネンシャル・バックオフ（Exponential backoff）アルゴリズムを使用して計算されます。

サポートされている構成オプションの詳細については、HttpRequestRetryConfig を参照してください。

再試行条件の構成

リクエストを再試行する条件を構成したり、遅延ロジックを指定したりできる構成設定もあります。

install(HttpRequestRetry) {
    maxRetries = 5
    retryIf { request, response ->
        !response.status.isSuccess()
    }
    retryOnExceptionIf { request, cause -> 
        cause is NetworkError 
    }
    delayMillis { retry -> 
        retry * 3000L 
    } // 3秒、6秒、9秒などの間隔で再試行
}

再試行前のリクエストの変更

再試行する前にリクエストを変更する必要がある場合は、modifyRequest を使用します。

install(HttpRequestRetry) {
    // 再試行条件
    modifyRequest { request ->
        request.headers.append("x-retry-count", retryCount.toString())
    }
}