Skip to content
Client Plugin

超时

代码示例: client-timeout

HttpTimeout 插件允许你配置以下超时:

  • 请求超时 (request timeout) — 处理一次 HTTP 调用所需的时间:从发送请求到接收响应。
  • 连接超时 (connection timeout) — 客户端与服务器建立连接应花费的时间。
  • Socket 超时 (socket timeout) — 与服务器交换数据时,两个数据包之间的最大空闲时间。

你可以为所有请求指定这些超时,也可以仅针对特定请求进行指定。

添加依赖项 ​

HttpTimeout 仅需要 ktor-client-core 构件,不需要任何额外的特定依赖项。

安装 HttpTimeout ​

要安装 HttpTimeout,请在客户端配置块内将其传递给 install 函数:

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

配置超时 ​

要配置超时,可以使用相应的属性:

你可以在 install 块内为所有请求指定超时。下面的代码示例展示了如何使用 requestTimeoutMillis 设置请求超时:

kotlin
val client = HttpClient(CIO) {
    install(HttpTimeout) {
        requestTimeoutMillis = 1000
    }
}

如果只需要为特定请求设置超时,请使用 HttpRequestBuilder.timeout 属性:

kotlin
val response: HttpResponse = client.get("http://0.0.0.0:8080/path1") {
    timeout {
        requestTimeoutMillis = 3000
    }
}

请注意,为特定请求指定的超时会覆盖 install 块中的全局超时。

在发生超时的情况下,Ktor 会抛出 HttpRequestTimeoutException、ConnectTimeoutException 或 SocketTimeoutException。

限制 ​

HttpTimeout 对某些特定的引擎存在限制。下表显示了这些引擎支持哪些超时:

引擎请求超时连接超时Socket 超时
Darwin✅️✖️✅️
JavaScript✅✖️✖️
Curl✅✅️✖️
MockEngine✅✖️✅