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

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

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

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

這是引導您開始使用 Ktor 建置伺服器應用程式系列教學的第一部分。您可以獨立完成每個教學，但我們強烈建議您按照建議的順序進行：

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

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

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

   學習如何使用 Ktor 和 Thymeleaf 範本在 Kotlin 中建置網站。
   。
5. 建立 WebSocket 應用程式

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

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

建立新的 Ktor 專案

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

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

使用 Ktor 專案產生器

若要使用 Ktor 專案產生器建立新專案，請按照以下步驟操作：

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

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

3. 點擊 Configure 以開啟設定下拉式功能表：

   提供以下設定：

   • Build System ： 選擇所需的

     建構系統

     學習如何將 Ktor 伺服器相依性新增至現有的 Gradle/Maven 專案。
     。 可以是 Gradle Kotlin、 Gradle Groovy、 Maven 或 Amper。

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

     引擎

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

   • Configuration ： 選擇是要在

     YAML 或 HOCON 檔案中

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

     學習如何在程式碼中配置各種伺服器參數。
     指定伺服器參數。
     目前以 Maven 為基礎的 Ktor 專案不支援 YAML 配置。

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

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 作為您的專案名稱。

   • Location：指定您的專案目錄。

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

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

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

     引擎

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

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

4. 點擊 Advanced Settings 以展開額外的設定功能表：

   

   提供以下設定：

   • Build System ： 選擇所需的

     建構系統

     學習如何將 Ktor 伺服器相依性新增至現有的 Gradle/Maven 專案。
     。 可以是 Gradle Kotlin、 Gradle Groovy、 Maven 或 Amper。

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

   • Configuration ： 選擇是要在

     YAML 或 HOCON 檔案中

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

     學習如何在程式碼中配置各種伺服器參數。
     指定伺服器參數。
     目前以 Maven 為基礎的 Ktor 專案不支援 YAML 配置。

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

5. 點擊 Next 以前往下一頁。

   

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

   外掛程式

   外掛程式提供常見功能，例如序列化、內容編碼、壓縮等。
   — 這些是提供 Ktor 應用程式常見功能的建構區塊，例如身份驗證、序列化和內容編碼、壓縮、Cookie 支援等等。

   就本教學而言，您目前不需要新增任何外掛程式。

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

既然您已建立了新專案，請繼續學習如何 開啟、探索並執行 該應用程式。

使用 Ktor CLI 工具

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

若要建立新的 Ktor 專案，請開啟您偏好的終端機並按照以下步驟操作：

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

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

4. 按下 Enter 以繼續。
5. 在下一個步驟中，您可以搜尋並將
   外掛程式

   外掛程式提供常見功能，例如序列化、內容編碼、壓縮等。
   新增到您的專案中。外掛程式是提供 Ktor 應用程式常見功能的建構區塊，例如身份驗證、序列化和內容編碼、壓縮、Cookie 支援等等。

   就本教學而言，您目前不需要新增任何外掛程式。

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

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

解包並執行您的 Ktor 專案

在本節中，您將學習如何從命令列解包、組建並執行專案。以下步驟假設：

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

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

開啟您偏好的命令列工具並按照以下步驟操作：

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

2. 將 ZIP 封存檔解包到同名的資料夾中：

   macOSWindows

   您的目錄現在將包含 ZIP 封存檔和解包後的資料夾。

3. 從該目錄導覽進入新建立的資料夾：

4. 在 macOS 和 UNIX 系統上，您必須使 Gradle 輔助指令碼成為可執行檔，以便系統將其識別為可執行指令。為此，請使用 chmod 指令：

   macOS

5. 若要組建專案，請使用以下指令：

   macOSWindows

   當組建成功後，繼續下一個步驟以執行專案。

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

   macOSWindows

7. 若要驗證專案是否正在執行，請在瀏覽器中開啟終端機輸出中顯示的 URL (http://0.0.0.0:8080)。 您應該會在瀏覽器中看到顯示 "Hello World!" 訊息：

   

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

NOTE

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

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

開啟專案

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

確保您位於專案資料夾中，然後輸入 idea 指令，後跟一個句點來代表當前資料夾：

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

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

TIP

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

探索專案

開啟專案後，您可以看到以下結構：

若要檢視完整的版面配置，請點擊每個資料夾旁邊的展開箭頭，在 Project 檢視中展開資料夾。

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

專案名稱是在 settings.gradle.kts 檔案中配置的：

配置檔案和其他類型的內容位於 src/main/resources 資料夾內。

執行專案

若要在 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. 新增 HTTP 端點
3. 配置靜態內容
4. 撰寫整合測試
5. 註冊錯誤處理常式

這些任務彼此獨立，但複雜度逐漸增加。按宣告的順序嘗試它們是循序漸進學習的最簡單方式。為了簡單起見並避免重複，下面的描述假設您正按順序嘗試任務。

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

更改預設連接埠

在配置檔案中更改連接埠

如果您選擇將配置儲存在外部的 YAML 或 HOCON 檔案中，在 Project 檢視中導覽至 src/main/resources 資料夾並按照以下步驟操作：

1. 開啟您的配置檔案 ( application.yaml 或 application.conf )。它應該如下所示：
   application.yaml (YAML)application.conf (HOCON)
2. 將檔案中的 port 值更改為您選擇的另一個數字，例如 9292。

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

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

   

在程式碼中更改連接埠

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

如果您選擇了將配置儲存在程式碼中的選項，在 Project 檢視中導覽至 src/main/kotlin 資料夾並按照以下步驟操作：

1. 開啟 main.kt 檔案。您應該會發現類似於以下的程式碼：

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

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

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

   

新增 HTTP 端點

在 Project 工具視窗中，導覽至 src/main/kotlin 資料夾並按照以下步驟操作：

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

2. 若要建立新端點，請插入如下所示的額外路由：

   NOTE

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

3. IDE 會自動為 ContentType 新增匯入：

4. 點擊重新執行按鈕 () 以重新啟動應用程式。

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

   

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

   NOTE

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

配置靜態內容

在 Project 工具視窗中，導覽至 src/main/kotlin 資料夾並按照以下步驟操作：

1. 開啟 Routing.kt 檔案並將以下路由新增到路由區段：

   這一行的含義如下：

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

2. 如果 IDE 沒有自動新增，請新增以下匯入。

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，例如：

8. 點擊重新執行按鈕 () 以重新啟動應用程式。

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

   

撰寫整合測試

Ktor 提供對

建立整合測試

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

的支援，且您產生的專案已隨附此功能。

若要使用此功能，請按照以下步驟操作：

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

2. 開啟 ServerTest.kt 檔案。您應該會看到如下程式碼：

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

   接著您可以使用 configure() 函式來調用與 embeddedServer() 中相同的設定。

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

您可以使用 IntelliJ IDEA 中執行測試的任何標準方式來執行該測試。請注意，由於您正在執行一個新的 Ktor 執行個體，測試的成功與否並不取決於您的應用程式是否正在 0.0.0.0 執行。

如果您已成功完成新增 HTTP 端點，請新增此額外測試：

新增以下額外匯入：

註冊錯誤處理常式

您可以使用

StatusPages 外掛程式

StatusPages 讓 Ktor 應用程式能根據拋出的例外或狀態碼對任何失敗狀態做出適當回應。

來處理 Ktor 應用程式中的錯誤。

TIP

預設情況下，您的專案中不包含此外掛程式。在使用 Ktor 專案產生器建立專案時，您可以透過 Plugins 部分新增它，或者在 IntelliJ IDEA 中透過專案精靈新增。

在接下來的步驟中，您將學習如何手動新增和配置此外掛程式。實現這一目標有四個步驟：

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

在 Project 工具視窗中，導覽至專案根資料夾並按照以下步驟操作：

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

2. 按下 Shift+⌘Cmd+I (macOS) 或 Ctrl+Shift+O (Windows/Linux) 來重新載入專案。

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 的核心概念，請繼續閱讀本指南中的下一個教學。

接下來，您將學習如何藉由建立一個

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

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

。