Skip to content

新增用戶端相依性 ​

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

設定存儲庫

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

  • 正式發佈版 (Production)

    Ktor 的正式發佈版本可在 Maven Central 存儲庫取得。 你可以依以下方式在組建指令碼中宣告此存儲庫:

    kotlin
    repositories {
        mavenCentral()
    }
    groovy
    repositories {
        mavenCentral()
    }

    你不需要在 pom.xml 檔案中新增 Maven Central 存儲庫,因為你的專案已繼承來自 Super POM 的 Central 存儲庫。

  • 早期體驗體計劃 (EAP)

    若要取得 Ktor 的 EAP 版本,你需要參照 Space 存儲庫:

    kotlin
    repositories {
        maven {
            url = uri("https://redirector.kotlinlang.org/maven/ktor-eap")
        }
    }
    groovy
    repositories {
        maven {
            url "https://redirector.kotlinlang.org/maven/ktor-eap"
        }
    }
    xml
    <repositories>
        <repository>
            <id>ktor-eap</id>
            <url>https://redirector.kotlinlang.org/maven/ktor-eap</url>
        </repository>
    </repositories>

    請注意,Ktor EAP 可能需要 Kotlin dev 存儲庫:

    kotlin
    repositories {
        maven {
            url = uri("https://redirector.kotlinlang.org/maven/dev")
        }
    }
    groovy
    repositories {
        maven {
            url "https://redirector.kotlinlang.org/maven/dev"
        }
    }
    xml
    <repositories>
        <repository>
            <id>ktor-eap</id>
            <url>https://redirector.kotlinlang.org/maven/dev</url>
        </repository>
    </repositories>

新增相依性 ​

對於不同的平台,Ktor 提供了帶有後綴(例如 -jvm 或 -js)的平台專屬構件,例如 ktor-client-core-jvm。請注意,Gradle 會自動解析適用於指定平台的構件,而 Maven 則不支援此功能。這代表在使用 Maven 時,你需要手動新增特定平台的後綴。

用戶端相依性 ​

主要的用戶端功能位於 ktor-client-core 構件中。根據你使用的建構系統,你可以透過以下方式新增它:

kotlin
implementation(ktorLibs.client.core)
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
groovy
implementation ktorLibs.client.core
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-core-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

多平台 ​

對於多平台專案,請在你的 settings.gradle.kts 檔案中匯入 Ktor version catalog:

kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("ktorLibs").from("io.ktor:ktor-version-catalog:3.6.1")
    }
}

接著,將 ktor-client-core 作為相依性新增至 commonMain 原始碼集中:

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

引擎相依性 ​

引擎負責處理網路請求。Ktor 為不同的平台提供了不同的用戶端引擎。

例如,你可以依以下方式新增 CIO 引擎:

kotlin
implementation(ktorLibs.client.cio)
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
groovy
implementation ktorLibs.client.cio
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-cio-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

多平台 ​

使用預設引擎 ​

對於多平台專案,你可以使用 ktor-client-engine-defaults 構件為每個目標平台提供經過精選的用戶端引擎。

將該構件相依性新增至 commonMain 原始碼集中:

kotlin
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                api(ktorLibs.client.engineDefaults)
            }
        }
    }
}
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
使用特定引擎 ​

如果你需要特定引擎,請改為將其相依性新增至對應的平台原始碼集中。例如,若要在 Android 上使用 OkHttp,請將 ktorLibs.client.okhttp 新增至 androidMain 原始碼集中:

kotlin
sourceSets {
    androidMain.dependencies {
        implementation(ktorLibs.client.okhttp)
    }
}
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。

關於各引擎所需的相依性,請參閱新增引擎相依性。

記錄相依性 ​

在 JVM 上,Ktor 使用 Simple Logging Facade for Java (SLF4J)作為記錄的抽象層。SLF4J 將記錄 API 與底層的記錄實作分離,讓你能夠整合最符合應用程式需求的記錄架構。常見選擇包括 Logback 或 Log4j。如果未提供架構,SLF4J 將預設使用無操作(NOP)實作,實質上會停用記錄功能。

若要啟用記錄,請加入包含所需 SLF4J 實作的構件,例如 Logback:

kotlin
implementation("ch.qos.logback:logback-classic:$logback_version")
groovy
implementation "ch.qos.logback:logback-classic:$logback_version"
xml
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>${logback_version}</version>
</dependency>

如需更多關於 Ktor 中記錄的資訊,請參閱 Ktor 用戶端中的記錄。

外掛程式相依性 ​

Ktor 允許你使用預設未提供的額外用戶端功能(外掛程式),例如授權(authorization)與序列化。其中部分功能是在獨立的構件中提供。你可以從所需外掛程式的主題文件中了解需要哪些相依性。

對於多平台專案,外掛程式相依性應新增至 commonMain 原始碼集中。請注意,某些外掛程式可能對特定平台有限制。

確保 Ktor 版本一致性 ​

使用 Ktor BOM 相依性

Ktor BOM 讓你能夠確保所有 Ktor 模組都使用相同且一致的版本,而無需單獨為每個相依性指定版本。

若要新增 Ktor BOM 相依性,請在組建指令碼中依以下方式宣告:

kotlin
implementation(platform("io.ktor:ktor-bom:$ktor_version"))
groovy
implementation platform "io.ktor:ktor-bom:$ktor_version"
xml
  <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-bom</artifactId>
            <version>3.6.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

使用已發佈的 version catalog

你也可以透過使用已發佈的 version catalog 來集中管理 Ktor 相依性宣告。這種方法具有以下優點:

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

若要宣告 catalog,請在 settings.gradle.kts 中以你自訂的名稱建立 version catalog:

kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("ktorLibs") {
            from("io.ktor:ktor-version-catalog:3.6.1")
        }
    }
}

接著,你就可以在模組的 build.gradle.kts 中透過參照該 catalog 名稱來新增相依性:

kotlin
dependencies {
    implementation(ktorLibs.client.core)
    // ...
}