添加客户端依赖项
要在项目中使用 Ktor HTTP 客户端,你需要配置仓库并添加以下依赖项:
ktor-client-core包含核心 Ktor 客户端功能。引擎用于处理网络请求。 请注意,特定平台可能需要特定的引擎来处理网络请求。
(可选) 日志依赖项
提供日志框架以启用结构化且灵活的日志记录功能。
(可选) 插件依赖项
插件用于通过特定功能扩展客户端。
配置仓库
在添加 Ktor 依赖项之前,你需要为该项目配置仓库:
正式版 (Production)
Ktor 的正式发布版本可在 Maven 中央仓库中获取。 你可以在构建脚本中按如下方式声明此仓库:
kotlinrepositories { mavenCentral() }groovyrepositories { mavenCentral() }你不需要在 pom.xml 文件中添加 Maven 中央仓库,因为你的项目已从 Super POM 继承了中央仓库。
抢先体验计划 (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 使用 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 Client 中的日志记录。
插件依赖项
Ktor 允许你使用默认情况下不可用的附加客户端功能(插件),例如授权和序列化。其中一些功能在单独的构件中提供。你可以从所需插件的主题中了解需要哪些依赖项。
对于多平台项目,应将插件依赖项添加到 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 中使用你选择的名称创建一个版本目录:
dependencyResolutionManagement {
versionCatalogs {
create("ktorLibs") {
from("io.ktor:ktor-version-catalog:3.6.1")
}
}
}然后,你可以通过引用该 catalog 名称在模块的 build.gradle.kts 中添加依赖项:
dependencies {
implementation(ktorLibs.client.core)
// ...
}