Skip to content

客户端引擎 ​

Ktor HTTP 客户端是多平台的,可运行在 JVM、Android、JavaScript(包括 WebAssembly)以及 Native 目标上。每个平台都需要特定的客户端引擎来处理网络请求。

Ktor 为不同的平台提供了多种引擎。例如,对于 JVM 应用程序可以使用 Apache 或 Jetty,对于 Android 可以使用 OkHttp 或 Android,对于面向 Kotlin/Native 的桌面应用程序可以使用 Curl。

每个引擎都支持不同的功能和配置选项。对于多平台项目,你可以使用 Ktor 的默认引擎,也可以为各个目标选择特定的引擎。

支持的平台 ​

下表列出了各个引擎支持的平台:

引擎平台
Apache5JVM
JavaJVM
JettyJVM
AndroidJVM、Android
OkHttpJVM、Android
DarwinNative
WinHttpNative
CurlNative
CIOJVM、Android、Native、JavaScript、WasmJs
JsJavaScript

支持的 Android/Java 版本 ​

面向 JVM 或同时面向 JVM 和 Android 的客户端引擎支持以下 Android/Java 版本:

引擎Android 版本Java 版本
Apache58+
Java11+
Jetty11+
CIO7.0+ *8+
Android1.x+8+
OkHttp5.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
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                api("io.ktor:ktor-client-engine-defaults:3.6.1")
            }
        }
    }
}

指定引擎 ​

要使用特定引擎,请将引擎类传递给 HttpClient 构造函数。以下示例创建了一个使用 CIO 引擎的客户端:

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO)

自动选择引擎 ​

如果省略引擎实参,客户端会自动从构建脚本中可用的引擎依赖项中选择引擎。

kotlin
import io.ktor.client.*

val client = HttpClient()

如果目标平台只有一个可用引擎,Ktor 会使用该引擎。如果有多个可用引擎,Ktor 会选择优先级最高的引擎。

默认情况下,CIO 的优先级最低。这意味着如果同一平台上有 CIO 和另一个受支持的引擎可用,Ktor 会选择另一个引擎。仅当没有更高优先级的引擎可用时,才会使用 CIO。

对于 Kotlin 多平台项目,ktor-client-engine-defaults 依赖项为每个目标提供了一个默认引擎。或者,你也可以向相应的平台源集中添加特定引擎的依赖项。

配置引擎 ​

要配置引擎,请使用 engine {} 函数。所有引擎都可以使用来自 HttpClientEngineConfig 的通用选项进行配置:

kotlin
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。

  1. 添加 ktor-client-apache5 依赖项:

    kotlin
    implementation(ktorLibs.client.apache5)
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    groovy
    implementation ktorLibs.client.apache5
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-apache5-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 Apache5 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.apache5.*
    
    val client = HttpClient(Apache5)
  3. 使用 engine {} 块访问并设置 Apache5EngineConfig 中的属性:

    kotlin
    import 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。要使用它,请按照以下步骤操作:

  1. 添加 ktor-client-java 依赖项:

    kotlin
    implementation(ktorLibs.client.java)
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    groovy
    implementation ktorLibs.client.java
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-java-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 Java 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.java.*
    
    val client = HttpClient(Java)
  3. 要配置引擎,请在 engine {} 块中设置来自 JavaHttpConfig 的属性:

    kotlin
    import 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,可以通过以下方式进行配置:

  1. 添加 ktor-client-jetty-jakarta 依赖项:

    kotlin
    implementation(ktorLibs.client.jetty)
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    groovy
    implementation ktorLibs.client.jetty
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-jetty-jakarta-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 Jetty 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.jetty.jakarta.*
    
    val client = HttpClient(Jetty)
  3. 要配置引擎,请在 engine {} 块中设置来自 JettyEngineConfig 的属性:

    kotlin
    import 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,可以通过以下方式进行配置:

  1. 添加 ktor-client-android 依赖项:

    kotlin
    implementation(ktorLibs.client.android)
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    groovy
    implementation ktorLibs.client.android
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-android-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 Android 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.android.*
    
    val client = HttpClient(Android)
  3. 要配置引擎,请在 engine {} 块中设置来自 AndroidEngineConfig 的属性:

    kotlin
    import 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,可以通过以下方式进行配置:

  1. 添加 ktor-client-okhttp 依赖项:

    kotlin
    implementation(ktorLibs.client.okhttp)
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    groovy
    implementation ktorLibs.client.okhttp
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-okhttp-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 OkHttp 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.okhttp.*
    
    val client = HttpClient(OkHttp)
  3. 要配置引擎,请在 engine {} 块中设置来自 OkHttpConfig 的属性:

    kotlin
    import 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 引擎,请按照以下步骤操作:

  1. 添加 ktor-client-darwin 依赖项:

    kotlin
    implementation("io.ktor:ktor-client-darwin:$ktor_version")
    groovy
    implementation "io.ktor:ktor-client-darwin:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-darwin-macosx64</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 Darwin 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.darwin.*
    
    val client = HttpClient(Darwin)
  3. 在 engine {} 块中使用 DarwinClientEngineConfig 配置引擎。例如,你可以使用 configureRequest 自定义请求,或者使用 configureSession 自定义会话:

    kotlin
    val client = HttpClient(Darwin) {
        engine {
            configureRequest {
                setAllowsCellularAccess(true)
            }
        }
    }

    有关完整示例,请参阅 client-engine-darwin。

WinHttp ​

WinHttp 引擎面向基于 Windows 的操作系统。要使用 WinHttp 引擎,请按照以下步骤操作:

  1. 添加 ktor-client-winhttp 依赖项:

    kotlin
    implementation("io.ktor:ktor-client-winhttp:$ktor_version")
    groovy
    implementation "io.ktor:ktor-client-winhttp:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-winhttp-mingwx64</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 WinHttp 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.winhttp.*
    
    val client = HttpClient(WinHttp)
  3. 在 engine {} 块中使用 WinHttpClientEngineConfig 配置引擎。例如,你可以使用 protocolVersion 属性来更改 HTTP 版本:

    kotlin
    val client = HttpClient(WinHttp) {
        engine {
            protocolVersion = HttpProtocolVersion.HTTP_1_1
        }
    }

    有关完整示例,请参阅 client-engine-winhttp.

Curl ​

对于桌面平台,Ktor 提供了 Curl 引擎。它在 linuxX64、linuxArm64、macosX64、macosArm64 和 mingwX64 上受支持。要使用 Curl 引擎,请按照以下步骤操作:

  1. 添加 ktor-client-curl 依赖项:

    kotlin
    implementation("io.ktor:ktor-client-curl:$ktor_version")
    groovy
    implementation "io.ktor:ktor-client-curl:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-curl-macosx64</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 Curl 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.curl.*
    
    val client = HttpClient(Curl)
  3. 在 engine {} 块中使用 CurlClientEngineConfig 配置引擎。例如,出于测试目的禁用 SSL 验证:

    kotlin
    val 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。要使用它,请按照以下步骤操作:

  1. 添加 ktor-client-cio 依赖项:

    kotlin
    implementation(ktorLibs.client.cio)
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    groovy
    implementation ktorLibs.client.cio
    上述代码片段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-cio-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 CIO 类作为实参传递给 HttpClient 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.cio.*
    
    val client = HttpClient(CIO)
  3. 在 engine {} 块中使用 CIOEngineConfig 配置引擎:

    kotlin
    import 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 引擎,请按照以下步骤操作:

  1. 添加 ktor-client-js 依赖项:

    kotlin
    implementation("io.ktor:ktor-client-js:$ktor_version")
    groovy
    implementation "io.ktor:ktor-client-js:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-js-macosx64</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. 将 Js 类作为实参传递给 HttpClient() 构造函数:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.js.*
    
    val client = HttpClient(Js)

    或者,调用 JsClient() 函数以获取 Js 引擎单例:

    kotlin
    import io.ktor.client.engine.js.*
    
    val client = JsClient()

    有关完整示例,请参阅 client-engine-js。

重写 fetch ​

默认情况下,Js 引擎使用全局 fetch() 函数。要使用自定义实现,请在引擎配置中设置 fetch 属性:

kotlin
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/2WebSockets
Apache5✅️✖️
Java✅✅️
Jetty✅✖️
CIO✖️✅
Android✖️✖️
OkHttp✅✅
Js✅✅
Darwin✅✅
WinHttp✅✅
Curl✅✅

安全性 ​

SSL 必须按引擎分别配置。每个引擎都提供了各自的 SSL 配置选项。

代理支持 ​

某些引擎不支持代理。完整列表请参阅代理文档。

日志记录 ​

Logging 插件根据目标平台提供不同的记录器类型。

超时 ​

HttpTimeout 插件在某些引擎上存在一些局限性。完整列表请参阅超时局限性。

示例:如何在多平台移动端项目中配置引擎 ​

在构建多平台项目时,你可以使用 expect 与 actual 声明为每个目标平台选择并配置引擎。这样你就可以在公共代码中共享大部分客户端配置,同时在平台代码中应用特定于引擎的选项。 我们将演示如何使用在创建跨平台移动应用程序教程中创建的项目来实现这一点:

    1. 打开 shared/src/commonMain/kotlin/com/example/kmpktor/Platform.kt 文件,并添加一个接受配置块并返回 HttpClient 的顶层 httpClient() 函数:

      kotlin
      expect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClient
    2. 打开 shared/src/androidMain/kotlin/com/example/kmpktor/Platform.kt,并为 Android 模块添加 httpClient() 函数的 actual 声明:

      kotlin
      import 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 受支持的其他引擎。

    3. 打开 shared/src/iosMain/kotlin/com/example/kmpktor/Platform.kt,并为 iOS 模块添加 httpClient() 函数的 actual 声明:

      kotlin
      import io.ktor.client.*
      import io.ktor.client.engine.darwin.*
      
      actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(Darwin) {
         config(this)
         engine {
            configureRequest {
               setAllowsCellularAccess(true)
            }
         }
      }

      现在你可以在共享代码中调用 httpClient(),而无需关心使用的是哪个引擎。

    4. 要在共享代码中使用该客户端,请打开 shared/src/commonMain/kotlin/com/example/kmpktor/Greeting.kt,并将 HttpClient() 构造函数替换为 httpClient() 函数调用:

      kotlin
      private val client = httpClient()