Skip to content

新增客戶端依賴

要在專案中使用 Ktor HTTP 客戶端,您需要設定儲存庫並新增以下依賴:

  • ktor-client-core

    ktor-client-core 包含 Ktor 客戶端的核心功能。

  • 引擎依賴

    引擎用於處理網路請求。 請注意,特定平台可能需要特定的引擎來處理網路請求。

  • (可選) 日誌依賴

    提供日誌框架以啟用結構化且靈活的日誌功能。

  • (可選) 外掛程式依賴

    外掛程式用於擴展客戶端的特定功能。

在新增 Ktor 依賴之前,您需要為此專案設定儲存庫:

  • 生產版本

    Ktor 的生產版本可在 Maven Central 儲存庫中取得。 您可以在建構腳本中宣告此儲存庫,如下所示:

    Kotlin
    Groovy

    NOTE

    您不需要在 pom.xml 檔案中新增 Maven Central 儲存庫,因為您的專案會從 Super POM 繼承中央儲存庫。

  • 搶先體驗計畫 (EAP)

    要存取 Ktor 的 EAP 版本,您需要引用 Space 儲存庫

    Kotlin
    Groovy
    XML

    請注意,Ktor EAP 可能需要 Kotlin 開發儲存庫

    Kotlin
    Groovy
    XML

新增依賴

對於不同平台,Ktor 提供帶有後綴的特定平台構件,例如 -jvm-js,例如 ktor-client-core-jvm。請注意,Gradle 會自動解析適用於給定平台的構件,而 Maven 不支援此功能。這表示對於 Maven,您需要手動新增特定平台的後綴。

客戶端依賴

主要的客戶端功能在 ktor-client-core 構件中提供。根據您的建構系統,您可以透過以下方式新增它:

Kotlin
Groovy
XML

您可以將 $ktor_version 替換為所需的 Ktor 版本,例如 3.2.3

多平台

對於多平台專案,您可以在 gradle/libs.versions.toml 檔案中定義 Ktor 版本和 ktor-client-core 構件:

kotlin
[versions]
ktor = "3.2.3"
[libraries]
kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }

然後,將 ktor-client-core 作為依賴新增到 commonMain 原始碼集:

kotlin
sourceSets {
    commonMain.dependencies {
        implementation(libs.ktor.client.core)
    }
}

引擎依賴

引擎負責處理網路請求。有適用於各種平台的不同客戶端引擎,例如 Apache、CIO、Android、iOS 等。例如,您可以如下新增 CIO 引擎依賴:

Kotlin
Groovy
XML

多平台

對於多平台專案,您需要將所需引擎的依賴新增到對應的原始碼集。

例如,要為 Android 新增 OkHttp 引擎依賴,您可以先在 gradle/libs.versions.toml 檔案中定義 Ktor 版本和 ktor-client-okhttp 構件:

kotlin
[versions]
ktor = "3.2.3"
[libraries]
kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" }

然後,將 ktor-client-okhttp 作為依賴新增到 androidMain 原始碼集:

kotlin
sourceSets {
    androidMain.dependencies {
        implementation(libs.ktor.client.okhttp)
    }
}

有關特定引擎所需依賴的完整列表,請參閱新增引擎依賴

日誌依賴

JVM 上,Ktor 使用 Simple Logging Facade for Java (SLF4J) 作為日誌記錄的抽象層。SLF4J 將日誌 API 與底層日誌實作分離, 讓您可以整合最適合您應用程式需求的日誌框架。 常見的選擇包括 LogbackLog4j。如果未提供框架,SLF4J 將預設為無操作 (NOP) 實作,這基本上會禁用 日誌記錄。

要啟用日誌記錄,請包含一個帶有所需 SLF4J 實作的構件,例如 Logback

Kotlin
Groovy
XML

有關 Ktor 客戶端中日誌記錄的更多資訊,請參閱Ktor 客戶端中的日誌記錄

外掛程式依賴

Ktor 讓您可以使用預設不提供的額外客戶端功能(外掛程式),例如授權和序列化。其中一些在單獨的構件中提供。您可以從所需外掛程式的主題中了解您需要哪些依賴。

對於多平台專案,外掛程式依賴應新增到 commonMain 原始碼集。請注意,某些外掛程式對於特定平台可能存在限制

確保 Ktor 版本一致性

使用 Ktor BOM 依賴

Ktor BOM 讓您可以確保所有 Ktor 模組使用相同且一致的版本,而無需單獨指定每個依賴的版本。

要新增 Ktor BOM 依賴,請在您的建構腳本中宣告它,如下所示:

Kotlin
Groovy
XML

您也可以透過使用已發布的版本目錄來集中 Ktor 依賴宣告。 此方法提供以下優點:

  • 無需在您自己的目錄中手動宣告 Ktor 版本。
  • 在單一命名空間下公開每個 Ktor 模組。

要在 settings.gradle.kts 中宣告目錄,請使用您選擇的名稱建立一個版本目錄:

kotlin

然後,您可以透過引用目錄名稱,在模組的 build.gradle.kts 中新增依賴:

kotlin