建立、開啟與執行新的 Ktor 專案
程式碼範例: tutorial-server-get-started
在本教學中,你將學習如何建立、開啟和執行你的第一個 Ktor 伺服器專案。啟動並順利執行後,你可以完成一系列任務以熟悉 Ktor。
這是幫助你開始使用 Ktor 建置伺服器應用程式系列教學的第一篇。你可以獨立完成每個教學,但我們強烈建議你遵循建議的順序:
- 建立、開啟與執行新的 Ktor 專案。
- 處理請求並產生回應透過建置任務管理器應用程式,學習在 Kotlin 中使用 Ktor 進行路由、處理請求與參數的基本概念。。
- 建立產生 JSON 的 RESTful API了解如何使用 Kotlin 和 Ktor 建置後端服務,其中包含一個產生 JSON 檔案的 RESTful API 範例。。
- 使用 Thymeleaf 範本建立網站了解如何使用 Ktor 和 Thymeleaf 範本在 Kotlin 中建置網站。。
- 建立 WebSocket 應用程式了解如何利用 WebSockets 的強大功能來傳送與接收內容。。
- 使用 Exposed 整合資料庫了解使用 Exposed SQL 程式庫將 Ktor 服務連接到資料庫存儲庫的過程。。
建立新的 Ktor 專案
建立新 Ktor 專案最快的方法之一是使用基於 Web 的 Ktor 專案產生器。
或者,你也可以使用 IntelliJ IDEA Ultimate 專用的 Ktor 外掛程式或 Ktor CLI 工具來產生專案。
使用 Ktor 專案產生器
若要使用 Ktor 專案產生器建立新專案,請遵循以下步驟:
前往 Ktor 專案產生器。
在 Project artifact 欄位中,輸入 com.example.ktor-sample 作為專案構件的名稱。

點擊 Configure 以開啟設定下拉式功能表:

提供以下設定:
Build System : 選擇所需的建置系統了解如何將 Ktor Server 相依性新增至現有的 Gradle/Maven 專案。。 可以是 Gradle Kotlin、 Gradle Groovy、 Maven 或 Amper。
Engine : 選取用於執行伺服器的引擎了解處理網路請求的引擎。。
Configuration : 選擇是在 YAML 或 HOCON 檔案中了解如何在組態檔案中配置各種伺服器參數。,還是在程式碼中了解如何在程式碼中配置各種伺服器參數。指定伺服器參數。
基於 Maven 的 Ktor 專案目前不支援 YAML 配置。
在本教學中,你可以為這些設定保留預設值。
點擊 Done 儲存配置並關閉功能表。
在下方你會看到一組可以新增到專案中的外掛程式外掛程式提供常見的功能性,例如序列化、內容編碼、壓縮等。。外掛程式是提供 Ktor 應用程式中常見功能的建置組塊,例如身分驗證、序列化與內容編碼、壓縮、Cookie 支援等。
就本教學而言,你現階段不需要新增任何外掛程式。
點擊 Download 按鈕以產生並下載你的 Ktor 專案。

你的下載應該會自動開始。
產生新專案後,繼續進行解包並執行你的 Ktor 專案。
使用適用於 IntelliJ IDEA Ultimate 的 Ktor 外掛程式
本節介紹使用適用於 IntelliJ IDEA Ultimate 的 Ktor 外掛程式進行專案設定。
若要建立新的 Ktor 專案,請開啟 IntelliJ IDEA 並遵循以下步驟:
在歡迎畫面中,點擊 New Project。
或者從主功能表中選取 File | New | Project。
在 New Project 精靈中,從左側清單中選擇 Ktor。
在右側窗格中,你可以指定以下設定:

Name:指定專案名稱。輸入 ktor-sample 作為專案的名稱。
Location:指定專案的目錄。
Website : 指定用於產生套件名稱的網域。
Artifact : 此欄位顯示產生的構件名稱。
Engine : 選取用於執行伺服器的引擎了解處理網路請求的引擎。。
Include samples : 保持啟用此選項以新增外掛程式的範例程式碼。
點擊 Advanced Settings 以展開其他設定功能表:

提供以下設定:
Build System : 選擇所需的建置系統了解如何將 Ktor Server 相依性新增至現有的 Gradle/Maven 專案。。 可以是 Gradle Kotlin、 Gradle Groovy、 Maven 或 Amper。
Ktor version : 選擇所需的 Ktor 版本。
Configuration : 選擇是在 YAML 或 HOCON 檔案中了解如何在組態檔案中配置各種伺服器參數。,還是在程式碼中了解如何在程式碼中配置各種伺服器參數。指定伺服器參數。
基於 Maven 的 Ktor 專案目前不支援 YAML 配置。
就本教學而言,你可以保留這些設定的預設值。
點擊 Next 進入下一頁。

在此頁面上,你可以選擇一組外掛程式外掛程式提供常見的功能性,例如序列化、內容編碼、壓縮等。——提供 Ktor 應用程式常見功能的建置組塊,例如身分驗證、序列化與內容編碼、壓縮、Cookie 支援等。
就本教學而言,你現階段不需要新增任何外掛程式。
點擊 Create 並等待 IntelliJ IDEA 產生專案並安裝相依性。
建立新專案後,繼續學習如何開啟、瀏覽與執行該應用程式。
使用 Ktor CLI 工具
本節介紹使用 Ktor CLI 工具進行專案設定。
若要建立新的 Ktor 專案,請開啟你慣用的終端並遵循以下步驟:
- 使用下列其中一個指令安裝 Ktor CLI 工具: console
brew install ktorconsolewinget install JetBrains.KtorCLI - 若要在互動模式下產生新專案,請使用以下指令: console
ktor new - 輸入 ktor-sample 作為專案的名稱:

(選填)你也可以透過編輯專案名稱下方的 Location 路徑來變更專案的儲存位置。
- 按下 Enter 鍵 以繼續。
- 在下一步中,你可以搜尋並新增外掛程式外掛程式提供常見的功能性,例如序列化、內容編碼、壓縮等。至專案中。外掛程式是提供 Ktor 應用程式中常見功能的建置組塊,例如身分驗證、序列化與內容編碼、壓縮、Cookie 支援等。

就本教學而言,你現階段不需要新增任何外掛程式。
- 按下 CTRL+G 以產生專案。
或者,你也可以透過選取 CREATE PROJECT (CTRL+G) 並按下 Enter 鍵 來產生專案。
解包並執行你的 Ktor 專案
在本節中,你將學習如何從命令列解包、建置和執行專案。以下步驟假設:
- 你已建立並下載名為 ktor-sample 的 Gradle 專案。
- 此專案位於家目錄中名為 myprojects 的資料夾內。
如有必要,請修改名稱和路徑以符合你自己的設定。
開啟你慣用的命令列工具並遵循以下步驟:
在終端視窗中,瀏覽至你下載專案的資料夾:
consolecd ~/myprojects將 ZIP 壓縮檔解包至同名資料夾中:
consoleunzip ktor-sample.zip -d ktor-sampleconsoletar -xf ktor-sample.zip現在你的目錄將包含 ZIP 壓縮檔和解包後的資料夾。
從該目錄瀏覽至新建立的資料夾:
consolecd ktor-sample在 macOS 和 UNIX 系統上,你必須使 Gradle 幫助程式指令碼具備可執行權限,以便系統將其識別為可執行的指令。為此,請使用
chmod指令:consolechmod +x ./gradlew若要建置專案,請使用以下指令:
console./gradlew buildconsolegradlew build建置成功後,繼續執行下一步以執行專案。
若要執行專案,請使用以下指令:
console./gradlew runconsolegradlew run若要驗證專案正在執行,請在終端輸出中顯示的 URL(http://0.0.0.0:8080)開啟瀏覽器。 你應該會在瀏覽器中看到顯示的訊息「Hello World!」:

恭喜!你已成功啟動 Ktor 專案。
在 IntelliJ IDEA 中開啟、瀏覽與執行你的 Ktor 專案
開啟專案
如果你安裝了 IntelliJ IDEA,可以輕鬆地從命令列開啟專案。
請確保你位於專案資料夾中,然後輸入 idea 指令,後接一個英文句點代表目前資料夾:
idea .或者,若要手動開啟專案,請啟動 IntelliJ IDEA。
如果開啟了歡迎畫面,請點擊 Open。 否則,請前往主功能表中的 File | Open 並選取 ktor-sample 資料夾以將其開啟。
瀏覽專案
開啟專案後,你可以看到以下結構:

若要檢視完整配置,請透過點擊每個資料夾旁邊的展開箭頭,展開 Project 檢視中的資料夾。
應用程式原始碼位於 src/main/kotlin 下。預設會建立兩個檔案,名為 Application.kt 與 Routing.kt

專案名稱是在 settings.gradle.kts 檔案中設定的:
rootProject.name = "ktor-sample"設定檔和其他類型的內容位於 src/main/resources 資料夾內。

執行專案
點擊右側邊欄上的 Gradle 圖示(
),開啟 Gradle 工具視窗。
在此工具視窗中,瀏覽至 Tasks | application 並在 run 任務上按兩下。

你的 Ktor 應用程式會在 IDE 底部的 Run 工具視窗中啟動:

先前在命令列上顯示的相同訊息現在將顯示在 Run 工具視窗中。
若要確認專案正在執行,請在指定的 URL(http://0.0.0.0:8080)開啟瀏覽器。
你應該會再次看到螢幕上顯示的訊息「Hello World!」:

若要在 IntelliJ IDEA 內執行專案:
你可以透過 Run 工具視窗管理應用程式。
- 若要終止應用程式,請點擊停止按鈕
。
- 若要重新啟動行程,請點擊重新執行按鈕
。
IntelliJ IDEA Run 工具視窗文件中對這些選項進行了進一步說明。
可嘗試的其他任務
以下是你可能想要嘗試的一些其他任務:
這些任務彼此不互相依賴,但複雜度逐漸增加。按宣告的順序嘗試它們是循序漸進學習的最簡單方式。為簡潔起見並避免重複,以下描述假設你按順序嘗試這些任務。
在需要撰寫程式碼的地方,我們同時指定了程式碼和相應的匯入。IDE 可能會自動為你新增這些匯入。
變更預設連接埠
在設定檔中變更連接埠
如果你選擇將配置儲存在外部的 YAML 或 HOCON 檔案中,請在 Project 檢視中瀏覽至 src/main/resources 資料夾並遵循以下步驟:
- 開啟你的設定檔( application.yaml 或 application.conf )。它應該如下所示: yaml
ktor: deployment: port: 8080 application: modules: - com.example.RoutingKt.configureRoutinggenericktor { deployment { port = 8080 port = ${?PORT} } application { modules = [ com.example.RoutingKt.configureRouting ] } } - 將檔案中的
port值變更為你選擇的其他數字,例如9292。 點擊重新執行按鈕(
)以重新啟動應用程式。
若要驗證應用程式是否在新的連接埠號碼下執行,可以在新的 URL(http://0.0.0.0:9292)開啟瀏覽器,或在 IntelliJ IDEA 中建立新的 HTTP 請求檔案:

在程式碼中變更連接埠
建立新的 Ktor 專案時,你可以選擇在程式碼中儲存配置,或者在外部的 YAML 或 HOCON 檔案中儲存。
如果你選擇了在程式碼中儲存配置的選項,請在 Project 檢視中瀏覽至 src/main/kotlin 資料夾並遵循以下步驟:
開啟 main.kt 檔案。你應該會找到類似以下內容的程式碼:
kotlinfun main(args: Array<String>) { embeddedServer( factory = io.ktor.server.netty.Netty, port = 8080, host = "0.0.0.0", module = Application::rootModule ).start(wait = true) }在
embeddedServer()函式中,將port參數變更為你選擇的其他數字,例如9292。kotlinfun main(args: Array<String>) { embeddedServer( factory = io.ktor.server.netty.Netty, port = 9292, host = "0.0.0.0", module = Application::rootModule ).start(wait = true) }點擊重新執行按鈕(
)以重新啟動應用程式。
若要驗證應用程式是否在新的連接埠號碼下執行,可以在新的 URL(http://0.0.0.0:9292)開啟瀏覽器,或在 IntelliJ IDEA 中建立新的 HTTP 請求檔案:

新增 HTTP 端點
在 Project 工具視窗中,瀏覽至 src/main/kotlin 資料夾並遵循以下步驟:
開啟 Routing.kt 檔案。這是你應該看到的程式碼:
kotlinfun Application.configureRouting() { routing { get("/") { call.respondText("Hello World!") } } }若要建立新端點,請插入如下所示的額外路由:
kotlinfun Application.configureRouting() { routing { // ... get("/test1") { val text = "<h1>Hello From Ktor</h1>" val type = ContentType.parse("text/html") call.respondText(text, type) } } }請注意,你可以將/test1URL 變更為你喜歡的任何名稱。IDE 會自動新增
ContentType的匯入:kotlinimport io.ktor.http.ContentType點擊重新執行按鈕(
)以重新啟動應用程式。
在瀏覽器中請求新的 URL(http://0.0.0.0:9292/test1)。連接埠號碼取決於你是否完成了變更預設連接埠任務。你應該會看到如下所示的輸出:

如果你建立了 HTTP 請求檔案,也可以在其中驗證新端點:
httpGET http://0.0.0.0:9292 ### GET http://0.0.0.0:9292/test1請注意,包含三個井字號(###)的行用於分隔不同的請求。
設定靜態內容
在 Project 工具視窗中,瀏覽至 src/main/kotlin 資料夾並遵循以下步驟:
開啟 Routing.kt 檔案並在路由區段中新增以下路由:
kotlinfun Application.configureRouting() { routing { staticResources("/content", "mycontent") // ... } }該行的含義如下:
- 呼叫
staticResources()可讓你的應用程式提供標準網站內容,例如 HTML 和 JavaScript 檔案。儘管此內容可以在瀏覽器中執行,但從伺服器的角度來看它被視為靜態內容。 - URL
/content指定用於擷取此內容的路徑。 - 路徑
mycontent是靜態內容所在的資料夾名稱。Ktor 將在resources目錄中尋找此資料夾。
- 呼叫
如果 IDE 沒有自動新增,請新增以下匯入:
kotlinimport io.ktor.server.http.content.staticResources在 Project 工具視窗中,右鍵點擊 src/main/resources 資料夾並選取 New | Directory。
或者,選取 src/main/resources 資料夾,按下 ⌘Cmd+N(macOS)或 Ctrl+N(Windows/Linux),然後點擊 Directory。
將新目錄命名為
mycontent並按下 ↩Enter 鍵。右鍵點擊新建立的資料夾並點擊 New | File。
將新檔案命名為 sample.html 並按下 ↩Enter 鍵。
在剛建立的檔案頁面中填入有效的 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>點擊重新執行按鈕(
)以重新啟動應用程式。
當你在 http://0.0.0.0:9292/content/sample.html 開啟瀏覽器時,應會顯示範例頁面的內容:

編寫整合測試
Ktor 提供對建立整合測試了解如何使用專門的測試引擎來測試您的伺服器應用程式。的支援,產生的專案已隨附此功能。
若要利用此功能,請遵循以下步驟:
瀏覽至 src/test/kotlin 資料夾。
開啟 ServerTest.kt 檔案。你應該會看到以下程式碼:
kotlinclass 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 端點,請新增此額外測試:
@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")
}新增以下額外的匯入:
import io.ktor.http.contentType
import io.ktor.client.statement.bodyAsText註冊錯誤處理常式
你可以使用 StatusPages 外掛程式StatusPages 允許 Ktor 應用程式根據擲出的例外或狀態碼,對任何失敗狀態做出適當的回應。在 Ktor 應用程式中處理錯誤。
在接下來的步驟中,你將學習如何手動新增和設定該外掛程式。實現此目的有四個步驟:
新增相依性
開啟 build.gradle.kts 檔案並新增相依性,如下所示:
kotlindependencies { 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) }按下 Shift+⌘Cmd+I(macOS)或 Ctrl+Shift+O(Windows/Linux)以重新載入專案。
在 Project 工具視窗中,瀏覽至專案根資料夾並遵循以下步驟:
安裝外掛程式並指定例外處理常式
瀏覽至 Routing.kt 中的
.configureRouting()方法並新增以下幾行程式碼:kotlinfun Application.configureRouting() { install(StatusPages) { exception<IllegalStateException> { call, cause -> call.respondText("App in illegal state as ${cause.message}") } } routing { // ... } }這幾行安裝了
StatusPages外掛程式,並指定擲回IllegalStateException型別的例外時要採取的動作。新增以下匯入:
kotlinimport io.ktor.server.plugins.statuspages.StatusPages
請注意,通常會在回應中設定 HTTP 錯誤代碼,但出於此任務的目的,輸出直接顯示在瀏覽器中。
撰寫範例程式碼以觸發處理常式
保留在
.configureRouting()方法中,新增額外的路由,如下所示:kotlinfun 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的端點。當觸發此端點時,將擲回具有處理常式中所使用型別的例外。
重新啟動並叫用範例程式碼
點擊重新執行按鈕(
)以重新啟動應用程式。
在瀏覽器中,前往 URL http://0.0.0.0:9292/error-test。你應該會看到如下所示的錯誤訊息:

後續步驟
如果你已經完成了所有其他任務,現在應該已經掌握了配置 Ktor 伺服器、整合 Ktor 外掛程式以及實作新路由的方法。然而,這只是一個開始。若要進一步深入探索 Ktor 的基礎概念,請繼續閱讀本指南中的下一篇教學。
接下來,你將學習如何透過建立工作管理員應用程式來處理請求並產生回應透過建置任務管理器應用程式,學習在 Kotlin 中使用 Ktor 進行路由、處理請求與參數的基本概念。。
