Skip to content

创建客户端应用程序

Ktor 包含一个多平台异步 HTTP 客户端,允许您发起请求了解如何发起请求并指定各种请求参数:请求 URL、HTTP 方法、标头以及请求体。和处理响应了解如何接收响应、获取响应体以及获取响应参数。,并通过插件了解如何使用客户端插件添加通用功能,例如日志记录、序列化与授权。扩展其功能,例如身份验证Auth 插件用于处理客户端应用程序中的身份验证与授权。、JSON 序列化ContentNegotiation 插件主要有两个用途:在客户端与服务器之间协商媒体类型,以及在发送请求和接收响应时按特定格式序列化/反序列化内容。等。

在本教程中,我们将向您展示如何创建首个用于发送请求并输出响应的 Ktor 客户端应用程序。

前提条件

在开始本教程之前,请安装 IntelliJ IDEA Community 或 Ultimate。

创建新项目

您可以手动在现有项目中创建并配置了解如何创建和配置 Ktor 客户端。 Ktor 客户端,不过从零开始的一个便捷方式是使用 IntelliJ IDEA 捆绑的 Kotlin 插件生成一个新项目。

要创建新的 Kotlin 项目,请打开 IntelliJ IDEA 并按照以下步骤操作:

  1. 在欢迎屏幕上,点击 New Project。

    或者,从主菜单中选择 File | New | Project。

  2. 在 New Project 向导中,从左侧列表中选择 Kotlin。

  3. 在右侧窗格中,指定以下设置:

    IntelliJ IDEA 中的新建 Kotlin 项目窗口
    • Name :指定项目名称。

    • Location :指定项目的目录。

    • Build system :确保已选中 Gradle。

    • Gradle DSL :选择 Kotlin。

    • Add sample code :选中此选项以在生成的项目中包含示例代码。

  4. 点击 Create 并等待 IntelliJ IDEA 生成项目并安装依赖项。

添加依赖项

下面添加 Ktor 客户端所需的依赖项。

  1. 打开 gradle.properties 文件并添加以下行以指定 Ktor 版本:

    kotlin
    ktor_version=3.6.1

    要使用 Ktor 的 EAP 版本,您需要添加 Space 仓库。

  2. 打开 build.gradle.kts 文件并将以下构件添加到 dependencies 块中:

    kotlin
    dependencies {
        implementation(ktorLibs.client.core)
        implementation(ktorLibs.client.cio)
        implementation(libs.logback.classic)
    }
    • ktor-client-core(ktorLibs.client.core)是提供客户端核心功能的核心依赖项,
    • ktor-client-cio(ktorLibs.client.cio)是处理网络请求的引擎了解处理网络请求的引擎。依赖项。
  3. 点击 build.gradle.kts 文件右上角的 Load Gradle Changes 图标以安装新添加的依赖项。

    Load Gradle Changes

创建客户端

要添加客户端实现,请转到 src/main/kotlin 并按照以下步骤操作:

  1. 打开 Main.kt 文件并将现有代码替换为以下实现:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.cio.*
    
    fun main() {
        val client = HttpClient(CIO)
    }

    在 Ktor 中,客户端由 HttpClient 类表示。

  2. 使用 HttpClient.get() 方法发起 GET 请求了解如何发起请求并指定各种请求参数:请求 URL、HTTP 方法、标头以及请求体。。响应了解如何接收响应、获取响应体以及获取响应参数。将作为 HttpResponse 类对象被接收。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.cio.*
    import io.ktor.client.request.*
    import io.ktor.client.statement.*
    
    fun main() {
        val client = HttpClient(CIO)
        val response: HttpResponse = client.get("https://ktor.io/")
    }

    添加上述代码后,IDE 会对 get() 函数显示以下错误: Suspend function 'get' should be called only from a coroutine or another suspend function 。

    Suspend 函数错误

    要解决此问题,您需要将 main() 函数设为挂起函数(suspend function)。

    要详细了解如何调用 suspend 函数,请参阅协程基础知识。
  3. 在 IntelliJ IDEA 中,点击定义旁边的红色灯泡图标并选择 Make main suspend。

    Make main suspend
  4. 使用 println() 函数输出服务器返回的状态码,并使用 close() 函数关闭流并释放与其关联的所有资源。 Main.kt 文件应如下所示:

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.cio.*
    import io.ktor.client.request.*
    import io.ktor.client.statement.*
    
    suspend fun main() {
        val client = HttpClient(CIO)
        val response: HttpResponse = client.get("https://ktor.io/")
        println(response.status)
        client.close()
    }

运行应用程序

要运行您的应用程序,请转到 Main.kt 文件并按照以下步骤操作:

  1. 在 IntelliJ IDEA 中,点击 main() 函数旁边的装订区域图标并选择 Run 'MainKt'。

    运行应用
  2. 等待 IntelliJ IDEA 运行应用程序。
  3. 您将在 IDE 底部的 Run 窗格中看到显示的输出。

    服务器响应

    尽管服务器返回了 200 OK 消息,但您还会看到一条错误消息,指出 SLF4J 未能找到 StaticLoggerBinder 类,已默认回退为无操作(NOP)日志记录器实现。这实际上意味着日志记录功能已被禁用。

    现在您已拥有一个可以正常工作的客户端应用程序。不过,若要消除此警告并通过日志调试 HTTP 调用,还需要执行额外的步骤。

启用日志记录

由于 Ktor 在 JVM 上使用 SLF4J 抽象层进行日志记录,因此若要启用日志记录,您需要提供一个日志记录框架,例如 Logback。

  1. 在 gradle.properties 文件中,指定日志记录框架的版本:

    kotlin
    logback_version=1.6.3
  2. 打开 build.gradle.kts 文件并将以下构件添加到 dependencies 块中:

    kotlin
    //...
    val logback_version: String by project
    
    dependencies {
        //...
        implementation("ch.qos.logback:logback-classic:$logback_version")
    }
  3. 点击 Load Gradle Changes 图标以安装新添加的依赖项。
  4. 在 IntelliJ IDEA 中,点击重新运行按钮(IntelliJ IDEA 重新运行图标)以重新启动应用程序。

  5. 此时应该不再出现该错误,并且在 IDE 底部的 Run 窗格中仍会显示相同的 200 OK 消息。

    服务器响应

    至此,您已启用了日志记录。若要开始查看日志,需要添加日志配置。

  6. 转到 src/main/resources 并创建具有以下实现的新 logback.xml 文件:

    xml
    <configuration>
        <appender name="APPENDER" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
            </encoder>
        </appender>
        <root level="trace">
            <appender-ref ref="APPENDER"/>
        </root>
    </configuration>
  7. 在 IntelliJ IDEA 中,点击重新运行按钮(IntelliJ IDEA 重新运行图标)以重新启动应用程序。

  8. 现在,您应该可以在 Run 窗格中打印出的响应上方看到跟踪(trace)日志:

    服务器响应
Ktor 提供了通过 Logging所需依赖项:io.ktor:ktor-client-logging 插件为 HTTP 调用添加日志的简便直观的方式,而添加配置文件则允许您在复杂的应用程序中微调日志记录行为。

后续步骤

若要更好地理解并扩展此配置,请了解如何创建并配置 Ktor 客户端了解如何创建和配置 Ktor 客户端。。