新增用戶端相依性
若要在專案中使用 Ktor HTTP 用戶端,你需要設定存儲庫並新增以下相依性:
ktor-client-core包含 Ktor 用戶端核心功能。引擎用於處理網路請求。 請注意,特定平台可能需要特定的引擎來處理網路請求。
(選填) 記錄相依性
提供記錄架構以啟用結構化且彈性的記錄功能。
(選填) 外掛程式相依性
外掛程式用於為用戶端擴充特定功能。
設定存儲庫
在新增 Ktor 相依性之前,你需要為此專案設定存儲庫:
正式發佈版 (Production)
Ktor 的正式發佈版本可在 Maven Central 存儲庫取得。 你可以依以下方式在組建指令碼中宣告此存儲庫:
kotlinrepositories { mavenCentral() }groovyrepositories { mavenCentral() }你不需要在 pom.xml 檔案中新增 Maven Central 存儲庫,因為你的專案已繼承來自 Super POM 的 Central 存儲庫。
早期體驗體計劃 (EAP)
若要取得 Ktor 的 EAP 版本,你需要參照 Space 存儲庫:
kotlinrepositories { maven { url = uri("https://redirector.kotlinlang.org/maven/ktor-eap") } }groovyrepositories { 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 存儲庫:
kotlinrepositories { maven { url = uri("https://redirector.kotlinlang.org/maven/dev") } }groovyrepositories { 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 構件中。根據你使用的建構系統,你可以透過以下方式新增它:
implementation(ktorLibs.client.core)implementation ktorLibs.client.core<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-core-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>多平台
對於多平台專案,請在你的 settings.gradle.kts 檔案中匯入 Ktor version catalog:
dependencyResolutionManagement {
versionCatalogs {
create("ktorLibs").from("io.ktor:ktor-version-catalog:3.6.1")
}
}接著,將 ktor-client-core 作為相依性新增至 commonMain 原始碼集中:
kotlin {
sourceSets {
commonMain {
dependencies {
implementation(ktorLibs.client.core)
}
}
}
}引擎相依性
引擎負責處理網路請求。Ktor 為不同的平台提供了不同的用戶端引擎。
例如,你可以依以下方式新增 CIO 引擎:
implementation(ktorLibs.client.cio)implementation ktorLibs.client.cio<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-cio-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>多平台
使用預設引擎
對於多平台專案,你可以使用 ktor-client-engine-defaults 構件為每個目標平台提供經過精選的用戶端引擎。
將該構件相依性新增至 commonMain 原始碼集中:
kotlin {
sourceSets {
commonMain {
dependencies {
api(ktorLibs.client.engineDefaults)
}
}
}
}使用特定引擎
如果你需要特定引擎,請改為將其相依性新增至對應的平台原始碼集中。例如,若要在 Android 上使用 OkHttp,請將 ktorLibs.client.okhttp 新增至 androidMain 原始碼集中:
sourceSets {
androidMain.dependencies {
implementation(ktorLibs.client.okhttp)
}
}關於各引擎所需的相依性,請參閱新增引擎相依性。
記錄相依性
在 JVM 上,Ktor 使用 Simple Logging Facade for Java (SLF4J)作為記錄的抽象層。SLF4J 將記錄 API 與底層的記錄實作分離,讓你能夠整合最符合應用程式需求的記錄架構。常見選擇包括 Logback 或 Log4j。如果未提供架構,SLF4J 將預設使用無操作(NOP)實作,實質上會停用記錄功能。
若要啟用記錄,請加入包含所需 SLF4J 實作的構件,例如 Logback:
implementation("ch.qos.logback:logback-classic:$logback_version")implementation "ch.qos.logback:logback-classic:$logback_version"<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 相依性,請在組建指令碼中依以下方式宣告:
implementation(platform("io.ktor:ktor-bom:$ktor_version"))implementation platform "io.ktor:ktor-bom:$ktor_version" <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:
dependencyResolutionManagement {
versionCatalogs {
create("ktorLibs") {
from("io.ktor:ktor-version-catalog:3.6.1")
}
}
}接著,你就可以在模組的 build.gradle.kts 中透過參照該 catalog 名稱來新增相依性:
dependencies {
implementation(ktorLibs.client.core)
// ...
}