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

程式碼範例: tutorial-server-get-started

在本教學中，您將學習如何建立、開啟及執行您的第一個 Ktor 伺服器專案。一旦啟動並運行，您可以嘗試一系列任務來熟悉 Ktor。

這是系列教學中的第一個，旨在協助您開始 使用 Ktor 建置伺服器應用程式。您可以獨立完成每個教學， 但是，我們強烈建議您遵循建議的順序：

1. 建立、開啟及執行新的 Ktor 專案。
2. 處理請求並產生回應

   透過建置任務管理器應用程式，使用 Kotlin 和 Ktor 學習路由、處理請求和參數的基礎知識。
   。
3. 建立產生 JSON 的 RESTful API

   學習如何使用 Kotlin 和 Ktor 建置後端服務，其中包含一個產生 JSON 檔案的 RESTful API 範例。
   。
4. 使用 Thymeleaf 模板建立網站

   學習如何使用 Kotlin 和 Ktor 以及 Thymeleaf 模板建置網站。
   。
5. 建立 WebSocket 應用程式

   學習如何利用 WebSocket 的強大功能來傳送和接收內容。
   。
6. 整合資料庫與 Exposed

   學習使用 Exposed SQL Library 將 Ktor 服務連接到資料庫儲存庫的過程。
   。

建立新的 Ktor 專案

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

或者，您可以 使用 IntelliJ IDEA Ultimate 專用的 Ktor 外掛程式 或 Ktor CLI 工具產生專案。

使用 Ktor 專案產生器

要使用 Ktor 專案產生器建立新專案，請遵循以下步驟：

1. 導覽至 Ktor 專案產生器。

2. 在 Project artifact 欄位中，輸入 com.example.ktor-sample-app 作為您的專案成品名稱。

3. 點擊 Configure 以開啟設定下拉式選單：

   以下設定可用：

   • Build System ： 選擇所需的

     建置系統

     學習如何將 Ktor 伺服器依賴項新增到現有 Gradle/Maven 專案。
     。 這可以是 Gradle 使用 Kotlin 或 Groovy DSL，或者 Maven 。

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

   • Engine ： 選擇用於執行伺服器的

     引擎

     了解處理網路請求的引擎。
     。

   • Configuration ： 選擇是 在

     YAML 或 HOCON 檔案中

     學習如何在設定檔中配置各種伺服器參數。
     指定伺服器參數，還是
     在程式碼中

     學習如何在程式碼中配置各種伺服器參數。
     指定。

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

   對於本教學，您可以將這些設定保留為預設值。

4. 點擊 Done 以儲存設定並關閉選單。

5. 下方您會找到一組可新增至專案的

   外掛程式

   外掛程式提供通用功能，例如序列化、內容編碼、壓縮等。
   。外掛程式是建置區塊，在 Ktor 應用程式中提供通用功能， 例如認證、序列化和內容編碼、壓縮、Cookie 支援等。

   對於本教學，您目前無需新增任何外掛程式。

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

您的下載應該會自動開始。

既然您已產生了一個新專案，請繼續解壓縮並執行您的 Ktor 專案。

使用 IntelliJ IDEA Ultimate 的 Ktor 外掛程式

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

要建立新的 Ktor 專案， 開啟 IntelliJ IDEA，並 遵循以下步驟：

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

   否則，從主選單中選擇 File | New | Project。

2. 在 New Project 精靈中，從左側列表中選擇 Ktor 。

3. 在右側窗格中，您可以指定以下設定：

   

   • Name ： 指定專案名稱。輸入 ktor-sample-app 作為您的專案名稱。

   • Location ： 指定專案的目錄。

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

   • Artifact ： 此欄位顯示產生的成品名稱。

   • Engine ： 選擇用於執行伺服器的

     引擎

     了解處理網路請求的引擎。
     。

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

4. 點擊 Advanced Settings 以展開 附加設定選單：

   

   以下設定可用：

   • Build System ： 選擇所需的

     建置系統

     學習如何將 Ktor 伺服器依賴項新增到現有 Gradle/Maven 專案。
     。 這可以是 Gradle 使用 Kotlin 或 Groovy DSL，或者 Maven 。

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

   • Configuration ： 選擇是 在

     YAML 或 HOCON 檔案中

     學習如何在設定檔中配置各種伺服器參數。
     指定伺服器參數，還是
     在程式碼中

     學習如何在程式碼中配置各種伺服器參數。
     指定。

   對於本教學，您可以將這些設定保留為預設值。

5. 點擊 Next 以進入下一頁。

   

   在此頁面，您可以選擇一組

   外掛程式

   外掛程式提供通用功能，例如序列化、內容編碼、壓縮等。
   - 提供 Ktor 應用程式通用功能的建置區塊，例如 認證、序列化和內容編碼、壓縮、Cookie 支援等。

   對於本教學，您目前無需新增任何外掛程式。

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

現在您已經建立了一個新專案，請繼續學習如何開啟、 探索及執行應用程式。

使用 Ktor CLI 工具

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

要建立新的 Ktor 專案，請開啟您選擇的終端機並 遵循以下步驟：

1. 使用以下其中一個命令安裝 Ktor CLI 工具：
   macOS/LinuxWindows
2. 要在互動模式下產生新專案，請使用以下命令：
3. 輸入 ktor-sample-app 作為您的專案名稱：

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

4. 按下 以繼續。
5. 在下一步中，您可以搜尋並新增
   外掛程式

   外掛程式提供通用功能，例如序列化、內容編碼、壓縮等。
   至您的 專案。外掛程式是建置區塊，在 Ktor 應用程式中提供通用功能， 例如認證、序列化和內容編碼、壓縮、Cookie 支援等。

   對於本教學，您目前無需新增任何外掛程式。

6. 按下 以產生專案。

   或者，您可以透過選擇 CREATE PROJECT (CTRL+G) 並按下 來產生專案。

解壓縮並執行您的 Ktor 專案

在本節中，您將學習如何從命令列解壓縮、建置並執行專案。以下描述 假設：

1. 您已建立並下載了一個名為 ktor-sample-app 的專案。
2. 它已放置在您主目錄中一個名為 myprojects 的資料夾中。

如有必要，請更改名稱和路徑以符合您自己的設定。

開啟您選擇的命令列工具並遵循以下步驟：

1. 在終端機中，導覽至您下載專案的資料夾：

2. 將 ZIP 壓縮檔解壓縮到同名資料夾中：

   macOSWindows

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

3. 從目錄中，導覽至新建立的資料夾：

4. 在 macOS/UNIX 系統上，您需要使 gradlew Gradle 輔助腳本可執行。為此，請使用 chmod 命令：

   macOS

5. 要建置專案，請使用以下命令：

   macOSWindows

   如果您看到建置成功，則可以再次透過 Gradle 執行專案。

6. 要執行專案，請使用以下命令：

   macOSWindows

7. 要驗證專案是否正在運行，請在輸出中提及的 URL (http://0.0.0.0:8080) 開啟瀏覽器。 您應該會在螢幕上看到「Hello World!」訊息：

   

恭喜！您已成功啟動您的 Ktor 專案。

請注意，命令列無回應，因為底層程序正在忙於運行 Ktor 應用程式。您可以按下 以終止應用程式。

在 IntelliJ IDEA 中開啟、探索並執行您的 Ktor 專案

開啟專案

如果您已安裝 IntelliJ IDEA，您可以輕鬆地從命令列開啟 專案。

請確保您位於專案資料夾中，然後輸入 idea 命令，後跟一個句點以表示當前 資料夾：

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

如果歡迎畫面開啟，請點擊 Open 。否則，從主選單中進入 File | Open 並選擇 ktor-sample-app 資料夾以開啟它。

TIP

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

探索專案

無論您選擇哪種選項，專案都應如下圖所示開啟：

為了說明專案佈局，我們在 Project 視圖中展開了結構，並選擇了 settings-gradle.kts 檔案。

您將看到執行應用程式的程式碼位於 src/main/kotlin 下的套件中。預設套件名為 com.example 並包含一個名為 plugins 的子套件。 這兩個套件中已建立兩個檔案，名為 Application.kt 和 Routing.kt

專案的名稱在 settings-gradle.kts 中配置。

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

在 src/test/kotlin 下的一個套件中已建立一個骨架測試。

執行專案

要從 IntelliJ IDEA 內部執行專案：

1. 透過點擊右側邊欄上的 Gradle 圖示（） 開啟Gradle 工具視窗 。

   

2. 在此工具視窗內導覽至 Tasks | application 並雙擊 run 任務。

   

3. 您的 Ktor 應用程式將在 IDE 底部的執行工具視窗中啟動：

   

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

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

   您應該會再次在螢幕上看到「Hello World!」訊息：

   

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

1. 要終止應用程式，請點擊停止按鈕
2. 要重新啟動程序，請點擊重新執行按鈕

這些選項在IntelliJ IDEA 執行 工具視窗文件中有進一步解釋。

要嘗試的其他任務

以下是一些您可能希望嘗試的其他任務：

1. 更改預設埠。
2. 透過 YAML 更改埠。
3. 新增一個 HTTP 端點。
4. 配置靜態內容。
5. 撰寫整合測試。
6. 註冊錯誤處理程式。

這些任務彼此獨立，但複雜度逐漸增加。按聲明的順序嘗試它們是 逐步學習的最簡單方法。為了簡化並避免重複，以下描述 假設您按順序嘗試這些任務。

需要編碼時，我們已指定了程式碼和相應的匯入。IDE 可能會自動為您 新增這些匯入。

更改預設埠

在 Project 視圖中，導覽至 src/main/kotlin 資料夾，然後進入為您建立的單一套件，並遵循以下步驟：

1. 開啟 Application.kt 檔案。您應該會找到類似以下的程式碼：

2. 在 embeddedServer() 函數中，將 port 參數更改 為您選擇的另一個數字，例如「9292」。

3. 點擊重新執行按鈕（） 以重新啟動應用程式。

4. 要驗證您的應用程式是否在新的埠號下運行，您可以在新的 URL (http://0.0.0.0:9292) 開啟瀏覽器，或者 在 IntelliJ IDEA 中建立一個新的 HTTP 請求檔案：

   

透過 YAML 更改埠

建立新的 Ktor 專案時，您可以選擇將配置外部儲存，可以是 YAML 或 HOCON 檔案：

如果您選擇外部儲存配置，那麼 Application.kt 中的程式碼將是：

這些將是儲存在 src/main/resources/ 中設定檔中的值：

application.yaml (YAML)application.conf (HOCON)

在這種情況下，您無需更改任何程式碼即可更改埠號。只需更改 YAML 或 HOCON 檔案中的值並重新啟動應用程式即可。更改可以與上方更改預設埠 相同的方式進行驗證。

新增一個 HTTP 端點

接下來，您將建立一個新的 HTTP 端點，它將回應 GET 請求。

在 Project 工具視窗中，導覽至 src/main/kotlin/com/example 資料夾並遵循以下步驟：

1. 開啟 Application.kt 檔案並找到 configureRouting() 函數。

2. 在 IntelliJ IDEA 中，將游標置於函數名稱上並按下 ，導覽至 configureRouting() 函數。

   或者，您可以透過開啟 Routing.kt 檔案導覽至該函數。

   這是您應該看到的程式碼：

3. 要建立一個新端點，請插入以下額外五行程式碼：

   請注意，您可以將 /test1 URL 更改為您喜歡的任何內容。

4. 為了使用 ContentType，請新增以下匯入：

5. 點擊重新執行按鈕（） 以重新啟動應用程式。

6. 在瀏覽器中請求新的 URL (http://0.0.0.0:9292/test1)。您應該使用的埠號將取決於您是否已嘗試第一個任務（更改預設埠）。您應該會看到 如下圖所示的輸出：

   

   如果您已建立 HTTP 請求檔案，您也可以在那裡驗證新端點：

   

   請注意，需要一行包含三個井字號 (###) 來分隔不同的請求。

配置靜態內容

在 Project 工具視窗中，導覽至 src/main/kotlin/com/example/plugins 資料夾並遵循以下步驟：

1. 開啟 Routing.kt 檔案。

   這應該是預設內容：

   對於此任務，無論您是否已插入 新增 HTTP 端點中指定 的額外端點內容，都無關緊要。

2. 在路由區段中新增以下行：

   這行的含義如下：

   1. 呼叫 staticResources() 告訴 Ktor 我們希望應用程式能夠提供標準網站內容，例如 HTML 和 JavaScript 檔案。儘管這些內容可能在瀏覽器中執行，但從 伺服器的角度來看，它被認為是靜態的。
   2. URL /content 指定應用程式應該用於獲取此內容的路徑。
   3. 路徑 mycontent 是靜態內容將所在的資料夾名稱。Ktor 將在 resources 目錄中尋找此資料夾。

3. 新增以下匯入：

4. 在 Project 工具視窗中，右鍵點擊 src/main/resources 資料夾並選擇 New | Directory 。

   或者，選擇 src/main/resources 資料夾，按下 ，然後點擊 Directory 。

5. 將新目錄命名為 mycontent 並按下 。

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

7. 將新檔案命名為「sample.html」並按下 。

8. 使用有效的 HTML 填充新建立的檔案頁面，例如：

9. 點擊重新執行按鈕（） 以重新啟動應用程式。

10. 當您在 http://0.0.0.0:9292/content/sample.html 開啟瀏覽器時，您樣本頁面的內容應該會顯示：

    

撰寫整合測試

Ktor 提供對

建立整合測試

學習如何使用特殊的測試引擎測試您的伺服器應用程式。

的支援，並且您產生的 專案捆綁了此功能。

要使用此功能，請遵循以下步驟：

1. 在 src 下建立一個名為「test」的新目錄，並在其中建立一個名為「kotlin」的子目錄。

2. 在 src/test/kotlin 內建立一個名為「com.example」的新套件。

3. 在 src/test/kotlin/com.example 內建立一個名為「ApplicationTest.kt」的新檔案。

4. 開啟 ApplicationTest.kt 檔案並新增以下程式碼：

   testApplication() 方法建立一個新的 Ktor 實例。此實例在測試環境中運行， 而不是像 Netty 這樣的伺服器。

   然後，您可以使用 application() 方法調用與從 embeddedServer() 呼叫的相同設定。

   最後，您可以使用內建的 client 物件和 JUnit 斷言來發送範例請求並檢查回應。

5. 新增以下所需匯入：

測試可以在 IntelliJ IDEA 中執行測試的任何標準方式運行。請注意，因為 您正在運行 Ktor 的新實例，所以測試的成功或失敗不取決於您的應用程式是否正在 0.0.0.0 運行。

如果您已成功完成新增 HTTP 端點， 您應該能夠新增此額外測試：

需要以下額外匯入：

註冊錯誤處理程式

您可以使用

StatusPages 外掛程式

%plugin_name% 允許 Ktor 應用程式根據拋出的異常或狀態碼適當地回應任何失敗狀態。

在 Ktor 應用程式中處理錯誤。

此外掛程式預設不包含在您的專案中。您可以透過 Ktor 專案產生器中的Plugins 部分，或 IntelliJ IDEA 中的專案精靈將其新增到您的專案中。由於您已建立專案，在接下來的步驟中 您將學習如何手動新增和配置該外掛程式。

為此有四個步驟：

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

在 Project 工具視窗中，導覽至專案根資料夾並遵循以下步驟：

1. 開啟 build.gradle.kts 檔案。

2. 在依賴項部分中新增額外依賴項，如下所示：

   完成此操作後，您需要重新載入專案以載入此新依賴項。

3. 在 macOS 上按 或在 Windows 上按 以重新載入專案。

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

   這些行安裝 StatusPages 外掛程式並指定當拋出 IllegalStateException 類型的異常時要執行的動作。

2. 新增以下匯入：

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

1. 仍在 configureRouting() 方法中，新增以下額外行：

   您現在已新增一個 URL 為 /error-test 的端點。當此端點被觸發時，將拋出一個 與處理程式中使用的類型相同的異常。

1. 點擊重新執行按鈕（） 以重新啟動應用程式。

2. 在您的瀏覽器中，導覽至 URL http://0.0.0.0:9292/error-test。 您應該會看到如下圖所示的錯誤訊息：

   

後續步驟

如果您已完成這些額外任務，您現在應該已掌握配置 Ktor 伺服器、整合 Ktor 外掛程式以及實作新路由。然而，這僅僅是個開始。要更深入地 探索 Ktor 的基礎概念，請繼續本指南中的下一個教學。

接下來，您將學習如何

透過建立任務管理器應用程式來處理請求並 產生回應

透過建置任務管理器應用程式，使用 Kotlin 和 Ktor 學習路由、處理請求和參數的基礎知識。

。