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 指定重试之间的指数级延迟，该延迟使用指数退避算法计算。

您可以从 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())
    }
}