Skip to content

建立、開啟與執行新的 Ktor 專案

在本教學中,你將學習如何建立、開啟和執行你的第一個 Ktor 伺服器專案。啟動並順利執行後,你可以完成一系列任務以熟悉 Ktor。

這是幫助你開始使用 Ktor 建置伺服器應用程式系列教學的第一篇。你可以獨立完成每個教學,但我們強烈建議你遵循建議的順序:

  1. 建立、開啟與執行新的 Ktor 專案。
  2. 處理請求並產生回應透過建置任務管理器應用程式,學習在 Kotlin 中使用 Ktor 進行路由、處理請求與參數的基本概念。。
  3. 建立產生 JSON 的 RESTful API了解如何使用 Kotlin 和 Ktor 建置後端服務,其中包含一個產生 JSON 檔案的 RESTful API 範例。。
  4. 使用 Thymeleaf 範本建立網站了解如何使用 Ktor 和 Thymeleaf 範本在 Kotlin 中建置網站。。
  5. 建立 WebSocket 應用程式了解如何利用 WebSockets 的強大功能來傳送與接收內容。。
  6. 使用 Exposed 整合資料庫了解使用 Exposed SQL 程式庫將 Ktor 服務連接到資料庫存儲庫的過程。。

建立新的 Ktor 專案

建立新 Ktor 專案最快的方法之一是使用基於 Web 的 Ktor 專案產生器。

或者,你也可以使用 IntelliJ IDEA Ultimate 專用的 Ktor 外掛程式或 Ktor CLI 工具來產生專案。

使用 Ktor 專案產生器

若要使用 Ktor 專案產生器建立新專案,請遵循以下步驟:

  1. 前往 Ktor 專案產生器。

  2. 在 Project artifact 欄位中,輸入 com.example.ktor-sample 作為專案構件的名稱。 Ktor 專案產生器,專案構件名稱為 com.example.ktor-sample

  3. 點擊 Configure 以開啟設定下拉式功能表: Ktor 專案設定的展開檢視

    提供以下設定:

    • Build System : 選擇所需的建置系統了解如何將 Ktor Server 相依性新增至現有的 Gradle/Maven 專案。。 可以是 Gradle Kotlin、 Gradle Groovy、 Maven 或 Amper。

    • Engine : 選取用於執行伺服器的引擎了解處理網路請求的引擎。。

    • Configuration : 選擇是在 YAML 或 HOCON 檔案中了解如何在組態檔案中配置各種伺服器參數。,還是在程式碼中了解如何在程式碼中配置各種伺服器參數。指定伺服器參數。

      基於 Maven 的 Ktor 專案目前不支援 YAML 配置。

    在本教學中,你可以為這些設定保留預設值。

  4. 點擊 Done 儲存配置並關閉功能表。

  5. 在下方你會看到一組可以新增到專案中的外掛程式外掛程式提供常見的功能性,例如序列化、內容編碼、壓縮等。。外掛程式是提供 Ktor 應用程式中常見功能的建置組塊,例如身分驗證、序列化與內容編碼、壓縮、Cookie 支援等。

    就本教學而言,你現階段不需要新增任何外掛程式。

  6. 點擊 Download 按鈕以產生並下載你的 Ktor 專案。 Ktor 專案產生器下載按鈕

  7. 你的下載應該會自動開始。

產生新專案後,繼續進行解包並執行你的 Ktor 專案。

使用適用於 IntelliJ IDEA Ultimate 的 Ktor 外掛程式

本節介紹使用適用於 IntelliJ IDEA Ultimate 的 Ktor 外掛程式進行專案設定。

若要建立新的 Ktor 專案,請開啟 IntelliJ IDEA 並遵循以下步驟:

  1. 在歡迎畫面中,點擊 New Project。

    或者從主功能表中選取 File | New | Project。

  2. 在 New Project 精靈中,從左側清單中選擇 Ktor。

  3. 在右側窗格中,你可以指定以下設定:

    Ktor 專案設定
    • Name:指定專案名稱。輸入 ktor-sample 作為專案的名稱。

    • Location:指定專案的目錄。

    • Website : 指定用於產生套件名稱的網域。

    • Artifact : 此欄位顯示產生的構件名稱。

    • Engine : 選取用於執行伺服器的引擎了解處理網路請求的引擎。。

    • Include samples : 保持啟用此選項以新增外掛程式的範例程式碼。

  4. 點擊 Advanced Settings 以展開其他設定功能表:

    Ktor 專案進階設定

    提供以下設定:

    • Build System : 選擇所需的建置系統了解如何將 Ktor Server 相依性新增至現有的 Gradle/Maven 專案。。 可以是 Gradle Kotlin、 Gradle Groovy、 Maven 或 Amper。

    • Ktor version : 選擇所需的 Ktor 版本。

    • Configuration : 選擇是在 YAML 或 HOCON 檔案中了解如何在組態檔案中配置各種伺服器參數。,還是在程式碼中了解如何在程式碼中配置各種伺服器參數。指定伺服器參數。

      基於 Maven 的 Ktor 專案目前不支援 YAML 配置。

    就本教學而言,你可以保留這些設定的預設值。

  5. 點擊 Next 進入下一頁。

    Ktor 外掛程式

    在此頁面上,你可以選擇一組外掛程式外掛程式提供常見的功能性,例如序列化、內容編碼、壓縮等。——提供 Ktor 應用程式常見功能的建置組塊,例如身分驗證、序列化與內容編碼、壓縮、Cookie 支援等。

    就本教學而言,你現階段不需要新增任何外掛程式。

  6. 點擊 Create 並等待 IntelliJ IDEA 產生專案並安裝相依性。

建立新專案後,繼續學習如何開啟、瀏覽與執行該應用程式。

使用 Ktor CLI 工具

本節介紹使用 Ktor CLI 工具進行專案設定。

若要建立新的 Ktor 專案,請開啟你慣用的終端並遵循以下步驟:

  1. 使用下列其中一個指令安裝 Ktor CLI 工具:
    console
    brew install ktor
    console
    winget install JetBrains.KtorCLI
  2. 若要在互動模式下產生新專案,請使用以下指令:
    console
    ktor new
  3. 輸入 ktor-sample 作為專案的名稱: 在互動模式下使用 Ktor CLI 工具

    (選填)你也可以透過編輯專案名稱下方的 Location 路徑來變更專案的儲存位置。

  4. 按下 Enter 鍵 以繼續。
  5. 在下一步中,你可以搜尋並新增外掛程式外掛程式提供常見的功能性,例如序列化、內容編碼、壓縮等。至專案中。外掛程式是提供 Ktor 應用程式中常見功能的建置組塊,例如身分驗證、序列化與內容編碼、壓縮、Cookie 支援等。 使用 Ktor CLI 工具新增外掛程式至專案

    就本教學而言,你現階段不需要新增任何外掛程式。

  6. 按下 CTRL+G 以產生專案。

    或者,你也可以透過選取 CREATE PROJECT (CTRL+G) 並按下 Enter 鍵 來產生專案。

解包並執行你的 Ktor 專案

在本節中,你將學習如何從命令列解包、建置和執行專案。以下步驟假設:

  1. 你已建立並下載名為 ktor-sample 的 Gradle 專案。
  2. 此專案位於家目錄中名為 myprojects 的資料夾內。

如有必要,請修改名稱和路徑以符合你自己的設定。

開啟你慣用的命令列工具並遵循以下步驟:

  1. 在終端視窗中,瀏覽至你下載專案的資料夾:

    console
    cd ~/myprojects
  2. 將 ZIP 壓縮檔解包至同名資料夾中:

    console
    unzip ktor-sample.zip -d ktor-sample
    console
    tar -xf ktor-sample.zip

    現在你的目錄將包含 ZIP 壓縮檔和解包後的資料夾。

  3. 從該目錄瀏覽至新建立的資料夾:

    console
    cd ktor-sample
  4. 在 macOS 和 UNIX 系統上,你必須使 Gradle 幫助程式指令碼具備可執行權限,以便系統將其識別為可執行的指令。為此,請使用 chmod 指令:

    console
    chmod +x ./gradlew
  5. 若要建置專案,請使用以下指令:

    console
    ./gradlew build
    console
    gradlew build

    建置成功後,繼續執行下一步以執行專案。

  6. 若要執行專案,請使用以下指令:

    console
    ./gradlew run
    console
    gradlew run
  7. 若要驗證專案正在執行,請在終端輸出中顯示的 URL(http://0.0.0.0:8080)開啟瀏覽器。 你應該會在瀏覽器中看到顯示的訊息「Hello World!」:

    產生的 Ktor 專案的輸出

恭喜!你已成功啟動 Ktor 專案。

請注意,命令列沒有回應是因為底層行程正忙於執行 Ktor 應用程式。你可以按下 CTRL+C 來終止應用程式。

在 IntelliJ IDEA 中開啟、瀏覽與執行你的 Ktor 專案

開啟專案

如果你安裝了 IntelliJ IDEA,可以輕鬆地從命令列開啟專案。

請確保你位於專案資料夾中,然後輸入 idea 指令,後接一個英文句點代表目前資料夾:

bash
idea .

或者,若要手動開啟專案,請啟動 IntelliJ IDEA。

如果開啟了歡迎畫面,請點擊 Open。 否則,請前往主功能表中的 File | Open 並選取 ktor-sample 資料夾以將其開啟。

有關管理專案的詳細資訊,請參閱 IntelliJ IDEA 文件。

瀏覽專案

開啟專案後,你可以看到以下結構:

IDE 中產生的 Ktor 專案檢視

若要檢視完整配置,請透過點擊每個資料夾旁邊的展開箭頭,展開 Project 檢視中的資料夾。

應用程式原始碼位於 src/main/kotlin 下。預設會建立兩個檔案,名為 Application.kt 與 Routing.kt

Ktor 專案 src 資料夾結構

專案名稱是在 settings.gradle.kts 檔案中設定的:

kotlin
rootProject.name = "ktor-sample"

設定檔和其他類型的內容位於 src/main/resources 資料夾內。

Ktor 專案 resources 資料夾結構

執行專案

    若要在 IntelliJ IDEA 內執行專案:

  1. 點擊右側邊欄上的 Gradle 圖示(IntelliJ IDEA Gradle 圖示),開啟 Gradle 工具視窗。

  2. 在此工具視窗中,瀏覽至 Tasks | application 並在 run 任務上按兩下。

    IntelliJ IDEA 中的 Gradle 索引標籤
  3. 你的 Ktor 應用程式會在 IDE 底部的 Run 工具視窗中啟動:

    在終端中執行的專案

    先前在命令列上顯示的相同訊息現在將顯示在 Run 工具視窗中。

  4. 若要確認專案正在執行,請在指定的 URL(http://0.0.0.0:8080)開啟瀏覽器。

    你應該會再次看到螢幕上顯示的訊息「Hello World!」:

    瀏覽器畫面中的 Hello World

你可以透過 Run 工具視窗管理應用程式。

  1. 若要終止應用程式,請點擊停止按鈕 IntelliJ IDEA 終止圖示。
  2. 若要重新啟動行程,請點擊重新執行按鈕 IntelliJ IDEA 重新執行圖示。

IntelliJ IDEA Run 工具視窗文件中對這些選項進行了進一步說明。

可嘗試的其他任務

以下是你可能想要嘗試的一些其他任務:

  1. 變更預設連接埠
  2. 新增 HTTP 端點
  3. 設定靜態內容
  4. 編寫整合測試
  5. 註冊錯誤處理常式

這些任務彼此不互相依賴,但複雜度逐漸增加。按宣告的順序嘗試它們是循序漸進學習的最簡單方式。為簡潔起見並避免重複,以下描述假設你按順序嘗試這些任務。

在需要撰寫程式碼的地方,我們同時指定了程式碼和相應的匯入。IDE 可能會自動為你新增這些匯入。

變更預設連接埠

在設定檔中變更連接埠

如果你選擇將配置儲存在外部的 YAML 或 HOCON 檔案中,請在 Project 檢視中瀏覽至 src/main/resources 資料夾並遵循以下步驟:

  1. 開啟你的設定檔( application.yaml 或 application.conf )。它應該如下所示:
    yaml
    ktor:
      deployment:
        port: 8080
      application:
        modules:
          - com.example.RoutingKt.configureRouting
    generic
    ktor {
      deployment {
        port = 8080
        port = ${?PORT}
      }
      application {
        modules = [
          com.example.RoutingKt.configureRouting
        ]
      }
    }
  2. 將檔案中的 port 值變更為你選擇的其他數字,例如 9292。
  3. 點擊重新執行按鈕(IntelliJ IDEA 重新執行按鈕圖示)以重新啟動應用程式。

  4. 若要驗證應用程式是否在新的連接埠號碼下執行,可以在新的 URL(http://0.0.0.0:9292)開啟瀏覽器,或在 IntelliJ IDEA 中建立新的 HTTP 請求檔案:

    在 IntelliJ IDEA 中使用 HTTP 請求檔案測試連接埠變更

在程式碼中變更連接埠

建立新的 Ktor 專案時,你可以選擇在程式碼中儲存配置,或者在外部的 YAML 或 HOCON 檔案中儲存。

如果你選擇了在程式碼中儲存配置的選項,請在 Project 檢視中瀏覽至 src/main/kotlin 資料夾並遵循以下步驟:

  1. 開啟 main.kt 檔案。你應該會找到類似以下內容的程式碼:

    kotlin
    fun main(args: Array<String>) {
        embeddedServer(
            factory = io.ktor.server.netty.Netty,
            port = 8080,
            host = "0.0.0.0",
            module = Application::rootModule
        ).start(wait = true)
    }
  2. 在 embeddedServer() 函式中,將 port 參數變更為你選擇的其他數字,例如 9292。

    kotlin
    fun main(args: Array<String>) {
        embeddedServer(
            factory = io.ktor.server.netty.Netty,
            port = 9292,
            host = "0.0.0.0",
            module = Application::rootModule
        ).start(wait = true)
    }
  3. 點擊重新執行按鈕(IntelliJ IDEA 重新執行按鈕圖示)以重新啟動應用程式。

  4. 若要驗證應用程式是否在新的連接埠號碼下執行,可以在新的 URL(http://0.0.0.0:9292)開啟瀏覽器,或在 IntelliJ IDEA 中建立新的 HTTP 請求檔案:

    在 IntelliJ IDEA 中使用 HTTP 請求檔案測試連接埠變更

新增 HTTP 端點

在 Project 工具視窗中,瀏覽至 src/main/kotlin 資料夾並遵循以下步驟:

  1. 開啟 Routing.kt 檔案。這是你應該看到的程式碼:

    kotlin
    fun Application.configureRouting() {
        routing {
            get("/") {
                call.respondText("Hello World!")
            }
        }
    }
  2. 若要建立新端點,請插入如下所示的額外路由:

    kotlin
    fun Application.configureRouting() {
        routing {
            // ...
    
            get("/test1") {
                val text = "<h1>Hello From Ktor</h1>"
                val type = ContentType.parse("text/html")
                call.respondText(text, type)
            }
        }
    }
    請注意,你可以將 /test1 URL 變更為你喜歡的任何名稱。
  3. IDE 會自動新增 ContentType 的匯入:

    kotlin
    import io.ktor.http.ContentType
  4. 點擊重新執行按鈕(IntelliJ IDEA 重新執行按鈕圖示)以重新啟動應用程式。

  5. 在瀏覽器中請求新的 URL(http://0.0.0.0:9292/test1)。連接埠號碼取決於你是否完成了變更預設連接埠任務。你應該會看到如下所示的輸出:

    顯示 Hello from Ktor 的瀏覽器畫面

    如果你建立了 HTTP 請求檔案,也可以在其中驗證新端點:

    http
    GET http://0.0.0.0:9292
    
    ###
    
    GET http://0.0.0.0:9292/test1
    請注意,包含三個井字號(###)的行用於分隔不同的請求。

設定靜態內容

在 Project 工具視窗中,瀏覽至 src/main/kotlin 資料夾並遵循以下步驟:

  1. 開啟 Routing.kt 檔案並在路由區段中新增以下路由:

    kotlin
    fun Application.configureRouting() {
        routing {
            staticResources("/content", "mycontent")
            // ...
        }
    }

    該行的含義如下:

    1. 呼叫 staticResources() 可讓你的應用程式提供標準網站內容,例如 HTML 和 JavaScript 檔案。儘管此內容可以在瀏覽器中執行,但從伺服器的角度來看它被視為靜態內容。
    2. URL /content 指定用於擷取此內容的路徑。
    3. 路徑 mycontent 是靜態內容所在的資料夾名稱。Ktor 將在 resources 目錄中尋找此資料夾。
  2. 如果 IDE 沒有自動新增,請新增以下匯入:

    kotlin
    import io.ktor.server.http.content.staticResources
  3. 在 Project 工具視窗中,右鍵點擊 src/main/resources 資料夾並選取 New | Directory。

    或者,選取 src/main/resources 資料夾,按下 ⌘Cmd+N(macOS)或 Ctrl+N(Windows/Linux),然後點擊 Directory。

  4. 將新目錄命名為 mycontent 並按下 ↩Enter 鍵。

  5. 右鍵點擊新建立的資料夾並點擊 New | File。

  6. 將新檔案命名為 sample.html 並按下 ↩Enter 鍵。

  7. 在剛建立的檔案頁面中填入有效的 HTML,例如:

    html
    <html lang="en">
        <head>
            <meta charset="UTF-8" />
            <title>My sample</title>
        </head>
        <body>
            <h1>This page is built with:</h1>
            <ol>
                <li>Ktor</li>
                <li>Kotlin</li>
                <li>HTML</li>
            </ol>
        </body>
    </html>
  8. 點擊重新執行按鈕(IntelliJ IDEA 重新執行按鈕圖示)以重新啟動應用程式。

  9. 當你在 http://0.0.0.0:9292/content/sample.html 開啟瀏覽器時,應會顯示範例頁面的內容:

    瀏覽器中靜態頁面的輸出

編寫整合測試

Ktor 提供對建立整合測試了解如何使用專門的測試引擎來測試您的伺服器應用程式。的支援,產生的專案已隨附此功能。

若要利用此功能,請遵循以下步驟:

  1. 瀏覽至 src/test/kotlin 資料夾。

  2. 開啟 ServerTest.kt 檔案。你應該會看到以下程式碼:

    kotlin
    class ServerTest {
    
        @Test
        fun `test root endpoint`() = testApplication {
            // loads default configuration
            configure()
            // verify server root returns 200
            assertEquals(HttpStatusCode.OK, client.get("/").status)
        }
    
    }

    testApplication() 函式會建立一個新的 Ktor 執行個體。此執行個體在測試環境中執行,而不是在 Netty 等伺服器中執行。

    然後你可以使用 configure() 函式來調用與從 embeddedServer() 呼叫的相同設定。

    最後,你可以使用內建的 client 物件和 JUnit 判斷提示來發送範例請求並檢查回應。

你可以使用在 IntelliJ IDEA 中執行測試的任何標準方式來執行測試。請注意,由於你執行的是一個新的 Ktor 執行個體,因此測試的成功或失敗並不取決於你的應用程式是否在 0.0.0.0 執行。

如果你已成功完成新增 HTTP 端點,請新增此額外測試:

kotlin
@Test
fun `test new endpoint`() = testApplication {
    configure()

    val response = client.get("/test1")

    assertEquals(HttpStatusCode.OK, response.status)
    assertEquals("html", response.contentType()?.contentSubtype)
    assertContains(response.bodyAsText(), "Hello From Ktor")
}

新增以下額外的匯入:

kotlin
import io.ktor.http.contentType
import io.ktor.client.statement.bodyAsText

註冊錯誤處理常式

你可以使用 StatusPages 外掛程式StatusPages 允許 Ktor 應用程式根據擲出的例外或狀態碼,對任何失敗狀態做出適當的回應。在 Ktor 應用程式中處理錯誤。

此外掛程式預設不包含在專案中。你可以在使用 Ktor 專案產生器或 IntelliJ IDEA 中的專案精靈建立專案時,透過 Plugins 區段將其新增至專案中。

在接下來的步驟中,你將學習如何手動新增和設定該外掛程式。實現此目的有四個步驟:

  1. 在 Gradle 組建檔案中新增相依性。
  2. 安裝外掛程式並指定例外處理常式。
  3. 撰寫範例程式碼以觸發處理常式。
  4. 重新啟動並叫用範例程式碼。

新增相依性

    在 Project 工具視窗中,瀏覽至專案根資料夾並遵循以下步驟:

  1. 開啟 build.gradle.kts 檔案並新增相依性,如下所示:

    kotlin
    dependencies {
        implementation(ktorLibs.server.config.yaml)
        implementation(ktorLibs.server.core)
        implementation(ktorLibs.server.netty)
        // Add new dependency
        implementation(ktorLibs.server.statusPages)
        implementation(libs.logback.classic)
    
        testImplementation(libs.kotlin.test)
        testImplementation(ktorLibs.server.testHost)
    }
  2. 按下 Shift+⌘Cmd+I(macOS)或 Ctrl+Shift+O(Windows/Linux)以重新載入專案。

安裝外掛程式並指定例外處理常式

  1. 瀏覽至 Routing.kt 中的 .configureRouting() 方法並新增以下幾行程式碼:

    kotlin
    fun Application.configureRouting() {
        install(StatusPages) {
            exception<IllegalStateException> { call, cause ->
                call.respondText("App in illegal state as ${cause.message}")
            }
        }
        routing {
            // ...
        }
    }

    這幾行安裝了 StatusPages 外掛程式,並指定擲回 IllegalStateException 型別的例外時要採取的動作。

  2. 新增以下匯入:

    kotlin
    import io.ktor.server.plugins.statuspages.StatusPages

請注意,通常會在回應中設定 HTTP 錯誤代碼,但出於此任務的目的,輸出直接顯示在瀏覽器中。

撰寫範例程式碼以觸發處理常式

  1. 保留在 .configureRouting() 方法中,新增額外的路由,如下所示:

    kotlin
    fun Application.configureRouting() {
        install(StatusPages) {
            exception<IllegalStateException> { call, cause ->
                call.respondText("App in illegal state as ${cause.message}")
            }
        }
        routing {
            // ...
    
            get("/error-test") {
                throw IllegalStateException("Too Busy")
            }
        }
    }

    你現在已經新增了一個 URL 為 /error-test 的端點。當觸發此端點時,將擲回具有處理常式中所使用型別的例外。

重新啟動並叫用範例程式碼

  1. 點擊重新執行按鈕(IntelliJ IDEA 重新執行按鈕圖示)以重新啟動應用程式。

  2. 在瀏覽器中,前往 URL http://0.0.0.0:9292/error-test。你應該會看到如下所示的錯誤訊息:

    顯示訊息「App in illegal state as Too Busy」的瀏覽器畫面

後續步驟

如果你已經完成了所有其他任務,現在應該已經掌握了配置 Ktor 伺服器、整合 Ktor 外掛程式以及實作新路由的方法。然而,這只是一個開始。若要進一步深入探索 Ktor 的基礎概念,請繼續閱讀本指南中的下一篇教學。

接下來,你將學習如何透過建立工作管理員應用程式來處理請求並產生回應透過建置任務管理器應用程式,學習在 Kotlin 中使用 Ktor 進行路由、處理請求與參數的基本概念。。