Skip to content

新增用戶端相依性

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

在新增 Ktor 相依性之前,您需要為此專案配置存儲庫:

  • 正式版 (Production)

    Ktor 的正式版本可在 Maven 中央存儲庫中取得。 您可以在建置指令碼中宣告此存儲庫,如下所示:

    Kotlin
    Groovy

    NOTE

    您不需要在 pom.xml 檔案中新增 Maven 中央存儲庫,因為您的專案會從 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.3.3

多平台

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

kotlin
[versions]
ktor = "3.4.0"

[libraries]
ktor-client-core = { module = "io.ktor:ktor-client-core", 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.4.0"

[libraries]
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", 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

您還可以透過使用發佈的版本目錄 (version catalog) 來集中管理 Ktor 相依性宣告。 這種方法提供以下好處:

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

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

kotlin

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

kotlin