用戶端引擎
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 脫糖 (desugaring)。
新增引擎相依性
除了 ktor-client-core 構件外,Ktor 用戶端還需要特定引擎的相依性。
使用特定引擎
每個支援的平台都有一組可用的引擎,詳見相應章節:
Ktor 提供帶有 -jvm 或 -js 等後綴的平台專屬構件。例如 ktor-client-cio-jvm。 相依性解析因建置工具而異。Gradle 能解析適合特定平台的構件,但 Maven 不支援此功能。這表示對於 Maven,你必須手動指定平台後綴。
在多平台專案中使用預設引擎
對於大多數 Kotlin Multiplatform 專案,請使用 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 Multiplatform 專案,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相依性:kotlinimplementation(ktorLibs.client.apache5)上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。groovyimplementation ktorLibs.client.apache5上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-apache5-jvm</artifactId> <version>${ktor_version}</version> </dependency>將
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用於與連線管理器無關的設定,例如 Proxy、攔截器或日誌記錄。
- 將
Java
Java 引擎使用 Java 11 中引入的 Java HTTP Client。若要使用它,請遵循以下步驟:
新增
ktor-client-java相依性:kotlinimplementation(ktorLibs.client.java)上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。groovyimplementation ktorLibs.client.java上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-java-jvm</artifactId> <version>${ktor_version}</version> </dependency>將 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相依性:kotlinimplementation(ktorLibs.client.jetty)上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。groovyimplementation ktorLibs.client.jetty上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-jetty-jakarta-jvm</artifactId> <version>${ktor_version}</version> </dependency>將
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相依性:kotlinimplementation(ktorLibs.client.android)上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。groovyimplementation ktorLibs.client.android上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-android-jvm</artifactId> <version>${ktor_version}</version> </dependency>將
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相依性:kotlinimplementation(ktorLibs.client.okhttp)上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。groovyimplementation ktorLibs.client.okhttp上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-okhttp-jvm</artifactId> <version>${ktor_version}</version> </dependency>將
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)使用
DarwinClientEngineConfig在engine {}區塊中設定引擎。例如,你可以使用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)使用
WinHttpClientEngineConfig在engine {}區塊中設定引擎。例如,你可以使用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)使用
CurlClientEngineConfig在engine {}區塊中設定引擎。例如,出於測試目的停用 SSL 驗證:kotlinval client = HttpClient(Curl) { engine { sslVerify = false } }完整範例請參閱 client-engine-curl。
JVM、Android、Native、JS 與 WasmJs
CIO
CIO 引擎是一個完全非同步、基於協同程式(coroutine)的引擎,適用於 JVM、Android、Native、JavaScript 以及 WebAssembly JavaScript (WasmJs) 平台。目前它僅支援 HTTP/1.x。若要使用它,請遵循以下步驟:
新增
ktor-client-cio相依性:kotlinimplementation(ktorLibs.client.cio)上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。groovyimplementation ktorLibs.client.cio上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-cio-jvm</artifactId> <version>${ktor_version}</version> </dependency>將
CIO類別作為引數傳遞給HttpClient建構函式:kotlinimport io.ktor.client.* import io.ktor.client.engine.cio.* val client = HttpClient(CIO)使用
CIOEngineConfig在engine {}區塊中設定引擎: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 設定選項。
Proxy 支援
部分引擎不支援 Proxy。完整清單請參閱 Proxy 文件。
記錄 (Logging)
Logging 外掛程式會根據目標平台提供不同的記錄器型別。
逾時 (Timeout)
HttpTimeout 外掛程式在某些引擎上存在一些限制。完整清單請參閱逾時限制。
範例:如何在多平台行動專案中設定引擎
在建置多平台專案時,你可以使用預期宣告與實際宣告 (expected and actual declarations) 來為各個目標平台選取並設定引擎。這讓你在共用程式碼中共享大部分用戶端設定時,仍可在平台專屬程式碼中套用引擎專屬的選項。 我們將使用在建立跨平台行動應用程式教學中所建立的專案來示範如何實現這一點:
開啟 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()函式的實際宣告: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()函式的實際宣告: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()
