客户端引擎
Ktor HTTP 客户端是多平台的,可运行在 JVM、Android、JavaScript(包括 WebAssembly)以及 Native 目标上。每个平台都需要特定的客户端引擎来处理网络请求。
Ktor 为不同的平台提供了多种引擎。例如,对于 JVM 应用程序可以使用 Apache 或 Jetty,对于 Android 可以使用 OkHttp 或 Android,对于面向 Kotlin/Native 的桌面应用程序可以使用 Curl。
每个引擎都支持不同的功能和配置选项。对于多平台项目,你可以使用 Ktor 的默认引擎,也可以为各个目标选择特定的引擎。
支持的平台
下表列出了各个引擎支持的平台:
| 引擎 | 平台 |
|---|---|
Apache5 | JVM |
Java | JVM |
Jetty | JVM |
Android | JVM、Android |
OkHttp | JVM、Android |
Darwin | Native |
WinHttp | Native |
Curl | Native |
CIO | JVM、Android、Native、JavaScript、WasmJs |
Js | JavaScript |
支持的 Android/Java 版本
面向 JVM 或同时面向 JVM 和 Android 的客户端引擎支持以下 Android/Java 版本:
| 引擎 | Android 版本 | Java 版本 |
|---|---|---|
Apache5 | 8+ | |
Java | 11+ | |
Jetty | 11+ | |
CIO | 7.0+ * | 8+ |
Android | 1.x+ | 8+ |
OkHttp | 5.0+ | 8+ |
* 要在较早的 Android 版本上使用 CIO 引擎,你需要启用 Java 8 API 脱糖。
添加引擎依赖项
除了 ktor-client-core 构件外,Ktor 客户端还需要特定引擎的依赖项。
使用特定引擎
每个受支持的平台都有一组可用的引擎,在相应小节中进行了介绍:
Ktor 提供了带有后缀(例如 -jvm 或 -js)的平台专属构件。例如 ktor-client-cio-jvm。 依赖项解析因构建工具而异。Gradle 能够解析适用于给定平台的构件,而 Maven 则不支持此功能。这意味着对于 Maven,你需要手动指定平台后缀。
在多平台项目中使用默认引擎
对于大多数 Kotlin 多平台项目,请使用 ktor-client-engine-defaults 构件。它为每个目标平台提供了精选的客户端引擎,因此你无需在特定于平台的源集中声明单独的引擎依赖项。
将 ktor-client-engine-defaults 构件添加到你的 commonMain 源集中:
kotlin {
sourceSets {
commonMain {
dependencies {
api("io.ktor:ktor-client-engine-defaults:3.6.1")
}
}
}
}指定引擎
要使用特定引擎,请将引擎类传递给 HttpClient 构造函数。以下示例创建了一个使用 CIO 引擎的客户端:
import io.ktor.client.*
import io.ktor.client.engine.cio.*
val client = HttpClient(CIO)自动选择引擎
如果省略引擎实参,客户端会自动从构建脚本中可用的引擎依赖项中选择引擎。
import io.ktor.client.*
val client = HttpClient()如果目标平台只有一个可用引擎,Ktor 会使用该引擎。如果有多个可用引擎,Ktor 会选择优先级最高的引擎。
默认情况下,CIO 的优先级最低。这意味着如果同一平台上有 CIO 和另一个受支持的引擎可用,Ktor 会选择另一个引擎。仅当没有更高优先级的引擎可用时,才会使用 CIO。
对于 Kotlin 多平台项目,ktor-client-engine-defaults 依赖项为每个目标提供了一个默认引擎。或者,你也可以向相应的平台源集中添加特定引擎的依赖项。
配置引擎
要配置引擎,请使用 engine {} 函数。所有引擎都可以使用来自 HttpClientEngineConfig 的通用选项进行配置:
HttpClient() {
engine {
// this: HttpClientEngineConfig
threadsCount = 4
pipelining = true
}
}在接下来的各节中,你可以了解如何针对不同平台配置特定引擎。
JVM
JVM 目标支持 Apache5、Java 和 Jetty 引擎。
Apache5
Apache5 引擎同时支持 HTTP/1.1 和 HTTP/2,其中 HTTP/2 默认启用。对于新项目,推荐使用该基于 Apache 的引擎。
较旧的 Apache 引擎依赖于已弃用的 Apache HttpClient 4。 保留它仅为了向后兼容。对于所有新项目,请使用 Apache5。
添加
ktor-client-apache5依赖项:将
Apache5类作为实参传递给HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.apache5.* val client = HttpClient(Apache5)使用
engine {}块访问并设置Apache5EngineConfig中的属性:kotlinimport io.ktor.client.* import io.ktor.client.engine.apache5.* import org.apache.hc.core5.http.* val client = HttpClient(Apache5) { engine { // this: Apache5EngineConfig followRedirects = true socketTimeout = 10_000 connectTimeout = 10_000 connectionRequestTimeout = 20_000 // 配置 Apache5 ConnectionManager configureConnectionManager { setMaxConnPerRoute(1_000) setMaxConnTotal(2_000) } // 自定义底层 Apache 客户端以配置其他设置 customizeClient { // this: HttpAsyncClientBuilder setProxy(HttpHost("127.0.0.1", 8080)) // ... } // 自定义针对单次请求的设置 customizeRequest { // this: RequestConfig.Builder } } }- 将
configureConnectionManager用于连接管理器设置,例如最大连接数。这可以保留 Ktor 管理的引擎行为。 - 仅将
customizeClient用于与连接管理器无关的设置,例如代理、拦截器或日志记录。
- 将
Java
Java 引擎使用 Java 11 中引入的 Java HTTP Client。要使用它,请按照以下步骤操作:
添加
ktor-client-java依赖项:将 Java 类作为实参传递给
HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.java.* val client = HttpClient(Java)要配置引擎,请在
engine {}块中设置来自JavaHttpConfig的属性:kotlinimport io.ktor.client.* import io.ktor.client.engine.* import io.ktor.client.engine.java.* val client = HttpClient(Java) { engine { // this: JavaHttpConfig threadsCount = 8 pipelining = true proxy = ProxyBuilder.http("http://proxy-server.com/") protocolVersion = java.net.http.HttpClient.Version.HTTP_2 } }
Jetty
Jetty 引擎仅支持 HTTP/2,可以通过以下方式进行配置:
添加
ktor-client-jetty-jakarta依赖项:将
Jetty类作为实参传递给HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.jetty.jakarta.* val client = HttpClient(Jetty)要配置引擎,请在
engine {}块中设置来自JettyEngineConfig的属性:kotlinimport io.ktor.client.* import io.ktor.client.engine.jetty.jakarta.* import org.eclipse.jetty.util.ssl.SslContextFactory val client = HttpClient(Jetty) { engine { // this: JettyEngineConfig sslContextFactory = SslContextFactory.Client() clientCacheSize = 12 } }
JVM 和 Android
在本节中,我们将介绍适用于 JVM/Android 的引擎及其配置。
Android
Android 引擎面向 Android,可以通过以下方式进行配置:
添加
ktor-client-android依赖项:将
Android类作为实参传递给HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.android.* val client = HttpClient(Android)要配置引擎,请在
engine {}块中设置来自AndroidEngineConfig的属性:kotlinimport io.ktor.client.* import io.ktor.client.engine.android.* import java.net.Proxy import java.net.InetSocketAddress val client = HttpClient(Android) { engine { // this: AndroidEngineConfig connectTimeout = 100_000 socketTimeout = 100_000 proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("localhost", 8080)) } }
OkHttp
OkHttp 引擎基于 OkHttp,可以通过以下方式进行配置:
添加
ktor-client-okhttp依赖项:将
OkHttp类作为实参传递给HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.okhttp.* val client = HttpClient(OkHttp)要配置引擎,请在
engine {}块中设置来自OkHttpConfig的属性:kotlinimport io.ktor.client.* import io.ktor.client.engine.okhttp.* val client = HttpClient(OkHttp) { engine { // this: OkHttpConfig config { // this: OkHttpClient.Builder followRedirects(true) // ... } addInterceptor(interceptor) addNetworkInterceptor(interceptor) preconfigured = okHttpClientInstance duplexStreamingEnabled = true // 仅适用于 HTTP/2 连接 } }
Native
Ktor 为 Kotlin/Native 目标提供了 Darwin、WinHttp 和 Curl 引擎。
在 Kotlin/Native 项目中使用 Ktor 需要新的内存管理器,从 Kotlin 1.7.20 开始默认启用该管理器。
Darwin
Darwin 引擎面向基于 Darwin 的操作系统,例如 macOS、iOS、tvOS 和 watchOS。其底层使用 NSURLSession。要使用 Darwin 引擎,请按照以下步骤操作:
添加
ktor-client-darwin依赖项:kotlinimplementation("io.ktor:ktor-client-darwin:$ktor_version")groovyimplementation "io.ktor:ktor-client-darwin:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-darwin-macosx64</artifactId> <version>${ktor_version}</version> </dependency>将
Darwin类作为实参传递给HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.darwin.* val client = HttpClient(Darwin)在
engine {}块中使用DarwinClientEngineConfig配置引擎。例如,你可以使用configureRequest自定义请求,或者使用configureSession自定义会话:kotlinval client = HttpClient(Darwin) { engine { configureRequest { setAllowsCellularAccess(true) } } }有关完整示例,请参阅 client-engine-darwin。
WinHttp
WinHttp 引擎面向基于 Windows 的操作系统。要使用 WinHttp 引擎,请按照以下步骤操作:
添加
ktor-client-winhttp依赖项:kotlinimplementation("io.ktor:ktor-client-winhttp:$ktor_version")groovyimplementation "io.ktor:ktor-client-winhttp:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-winhttp-mingwx64</artifactId> <version>${ktor_version}</version> </dependency>将
WinHttp类作为实参传递给HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.winhttp.* val client = HttpClient(WinHttp)在
engine {}块中使用WinHttpClientEngineConfig配置引擎。例如,你可以使用protocolVersion属性来更改 HTTP 版本:kotlinval client = HttpClient(WinHttp) { engine { protocolVersion = HttpProtocolVersion.HTTP_1_1 } }有关完整示例,请参阅 client-engine-winhttp.
Curl
对于桌面平台,Ktor 提供了 Curl 引擎。它在 linuxX64、linuxArm64、macosX64、macosArm64 和 mingwX64 上受支持。要使用 Curl 引擎,请按照以下步骤操作:
添加
ktor-client-curl依赖项:kotlinimplementation("io.ktor:ktor-client-curl:$ktor_version")groovyimplementation "io.ktor:ktor-client-curl:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-curl-macosx64</artifactId> <version>${ktor_version}</version> </dependency>将
Curl类作为实参传递给HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.curl.* val client = HttpClient(Curl)在
engine {}块中使用CurlClientEngineConfig配置引擎。例如,出于测试目的禁用 SSL 验证:kotlinval client = HttpClient(Curl) { engine { sslVerify = false } }有关完整示例,请参阅 client-engine-curl。
JVM、Android、Native、JS 和 WasmJs
CIO
CIO 引擎是一个完全异步、基于协程的引擎,可在 JVM、Android、Native、JavaScript 和 WebAssembly JavaScript (WasmJs) 平台上使用。它目前仅支持 HTTP/1.x。要使用它,请按照以下步骤操作:
添加
ktor-client-cio依赖项:将
CIO类作为实参传递给HttpClient构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.cio.* val client = HttpClient(CIO)在
engine {}块中使用CIOEngineConfig配置引擎:kotlinimport io.ktor.client.* import io.ktor.client.engine.cio.* import io.ktor.network.tls.* val client = HttpClient(CIO) { engine { // this: CIOEngineConfig maxConnectionsCount = 1000 endpoint { // this: EndpointConfig maxConnectionsPerRoute = 100 pipelineMaxSize = 20 keepAliveTime = 5000 connectTimeout = 5000 connectAttempts = 5 } https { // this: TLSConfigBuilder serverName = "api.ktor.io" cipherSuites = CIOCipherSuites.SupportedSuites trustManager = myCustomTrustManager random = mySecureRandom addKeyStore(myKeyStore, myKeyStorePassword) } dnsResolver = CioDnsResolver( server = "1.1.1.1", timeout = 3.seconds ) } }
JavaScript
Js 引擎可用于 Kotlin/JS 项目。它在浏览器应用程序中使用 Fetch API,在 Node.js 中使用 node-fetch。
要使用 Js 引擎,请按照以下步骤操作:
添加
ktor-client-js依赖项:kotlinimplementation("io.ktor:ktor-client-js:$ktor_version")groovyimplementation "io.ktor:ktor-client-js:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-js-macosx64</artifactId> <version>${ktor_version}</version> </dependency>将
Js类作为实参传递给HttpClient()构造函数:kotlinimport io.ktor.client.* import io.ktor.client.engine.js.* val client = HttpClient(Js)或者,调用
JsClient()函数以获取Js引擎单例:kotlinimport io.ktor.client.engine.js.* val client = JsClient()有关完整示例,请参阅 client-engine-js。
重写 fetch
默认情况下,Js 引擎使用全局 fetch() 函数。要使用自定义实现,请在引擎配置中设置 fetch 属性:
val client = HttpClient(Js) {
engine {
fetch = { url, init ->
Promise.reject(IllegalStateException("Networking not available"))
}
}
}在与提供自定义 fetch() 实现或包装器的 JavaScript 库集成时,这非常有用。
局限性
HTTP/2 与 WebSockets
并非所有引擎都支持 HTTP/2 协议。如果某个引擎支持 HTTP/2,你可以在该引擎的配置中启用它。例如 Java 引擎。
下表展示了特定引擎是否支持 HTTP/2 和 WebSockets:
| 引擎 | HTTP/2 | WebSockets |
|---|---|---|
Apache5 | ✅️ | ✖️ |
Java | ✅ | ✅️ |
Jetty | ✅ | ✖️ |
CIO | ✖️ | ✅ |
Android | ✖️ | ✖️ |
OkHttp | ✅ | ✅ |
Js | ✅ | ✅ |
Darwin | ✅ | ✅ |
WinHttp | ✅ | ✅ |
Curl | ✅ | ✅ |
安全性
SSL 必须按引擎分别配置。每个引擎都提供了各自的 SSL 配置选项。
代理支持
某些引擎不支持代理。完整列表请参阅代理文档。
日志记录
Logging 插件根据目标平台提供不同的记录器类型。
超时
HttpTimeout 插件在某些引擎上存在一些局限性。完整列表请参阅超时局限性。
示例:如何在多平台移动端项目中配置引擎
在构建多平台项目时,你可以使用 expect 与 actual 声明为每个目标平台选择并配置引擎。这样你就可以在公共代码中共享大部分客户端配置,同时在平台代码中应用特定于引擎的选项。 我们将演示如何使用在创建跨平台移动应用程序教程中创建的项目来实现这一点:
打开 shared/src/commonMain/kotlin/com/example/kmpktor/Platform.kt 文件,并添加一个接受配置块并返回
HttpClient的顶层httpClient()函数:kotlinexpect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClient打开 shared/src/androidMain/kotlin/com/example/kmpktor/Platform.kt,并为 Android 模块添加
httpClient()函数的 actual 声明:kotlinimport io.ktor.client.* import io.ktor.client.engine.okhttp.* import java.util.concurrent.TimeUnit actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(OkHttp) { config(this) engine { config { retryOnConnectionFailure(true) connectTimeout(0, TimeUnit.SECONDS) } } }本示例演示了如何配置
OkHttp引擎,但你也可以使用针对 Android 受支持的其他引擎。打开 shared/src/iosMain/kotlin/com/example/kmpktor/Platform.kt,并为 iOS 模块添加
httpClient()函数的 actual 声明:kotlinimport io.ktor.client.* import io.ktor.client.engine.darwin.* actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(Darwin) { config(this) engine { configureRequest { setAllowsCellularAccess(true) } } }现在你可以在共享代码中调用
httpClient(),而无需关心使用的是哪个引擎。要在共享代码中使用该客户端,请打开 shared/src/commonMain/kotlin/com/example/kmpktor/Greeting.kt,并将
HttpClient()构造函数替换为httpClient()函数调用:kotlinprivate val client = httpClient()
