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 圖示,以安裝新新增的相依性。

    載入 Gradle 變更

建立用戶端

若要新增用戶端實作,請瀏覽至 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() 函式設為 suspending。

    若要進一步了解呼叫 suspend 函式,請參閱 協同程式基礎 (Coroutines basics)。
  3. 在 IntelliJ IDEA 中,點擊定義旁邊的紅色燈泡並選擇 Make main suspend。

    將 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 窗格中印出的回應上方看到追蹤記錄:

    伺服器回應
Ktor 透過 Logging必要相依性:io.ktor:ktor-client-logging 外掛程式提供了一種簡單明瞭的方式來為 HTTP 呼叫新增記錄,而新增配置檔案則可讓你微調複雜應用程式中的記錄行為。

後續步驟

若要更好地理解並擴充此配置,請探索如何建立並配置 Ktor 用戶端了解如何建立與配置 Ktor 用戶端。。