Skip to content

添加客户端依赖项 ​

要在项目中使用 Ktor HTTP 客户端,你需要配置仓库并添加以下依赖项:

配置仓库

在添加 Ktor 依赖项之前,你需要为该项目配置仓库:

  • 正式版 (Production)

    Ktor 的正式发布版本可在 Maven 中央仓库中获取。 你可以在构建脚本中按如下方式声明此仓库:

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

    你不需要在 pom.xml 文件中添加 Maven 中央仓库,因为你的项目已从 Super POM 继承了中央仓库。

  • 抢先体验计划 (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 使用 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 Client 中的日志记录。

插件依赖项 ​

Ktor 允许你使用默认情况下不可用的附加客户端功能(插件),例如授权和序列化。其中一些功能在单独的构件中提供。你可以从所需插件的主题中了解需要哪些依赖项。

对于多平台项目,应将插件依赖项添加到 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 中使用你选择的名称创建一个版本目录:

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

然后,你可以通过引用该 catalog 名称在模块的 build.gradle.kts 中添加依赖项:

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