從 Express 遷移至 Ktor

程式碼範例： migrating-express migrating-express-ktor

在本指南中，我們將探討在基本情境下如何將 Express 應用程式遷移至 Ktor：從產生應用程式與撰寫您的第一個應用程式，到建立用於擴充應用程式功能的中介軟體。

產生應用程式

Express

您可以使用 express-generator 工具來產生新的 Express 應用程式：

shell

Ktor

Ktor 提供以下幾種方式來產生應用程式骨架：

Ktor 專案產生器 (Ktor Project Generator) — 使用網頁版產生器。
Ktor CLI 工具 — 透過命令列介面使用 ktor new 指令產生 Ktor 專案：
shell
Yeoman 產生器 — 以互動方式配置專案設定並選取所需的外掛程式：
shell
IntelliJ IDEA Ultimate — 使用內建的 Ktor 專案精靈。

如需詳細指示，請參閱

教學。

Hello world

在本節中，我們將探討如何建立最簡單的伺服器應用程式，該程式接收 GET 請求並以預定義的純文字進行回應。

Express

下方的範例顯示了啟動伺服器並監聽通訊埠 3000 連線的 Express 應用程式。

javascript

如需完整範例，請參閱 1_hello 專案。

Ktor

在 Ktor 中，您可以使用 embeddedServer 函式在程式碼中配置伺服器參數並快速執行應用程式。

kotlin

如需完整範例，請參閱 1_hello 專案。

您也可以在採用 HOCON 或 YAML 格式的外部配置檔案中指定伺服器設定。

請注意，上述 Express 應用程式會加入 Date、X-Powered-By 和 ETag 回應標頭，內容可能如下所示：

若要在 Ktor 的每個回應中加入預設的 Server 與 Date 標頭，您需要安裝

外掛程式。外掛程式則可用於配置 Etag 回應標頭。

提供靜態內容

在本節中，我們將探討如何在 Express 與 Ktor 中提供影像、CSS 檔案與 JavaScript 檔案等靜態檔案。假設我們有一個 public 資料夾，其中包含主要的 index.html 頁面以及一組連結的資源。

Express

在 Express 中，將資料夾名稱傳遞給 express.static 函式。

javascript

如需完整範例，請參閱 2_static 專案。

Ktor

在 Ktor 中，使用 staticFiles() 函式將對 / 路徑的任何請求對應到 public 實體資料夾。此函式可以遞迴地提供 public 資料夾中的所有檔案。

kotlin

如需完整範例，請參閱 2_static 專案。

提供靜態內容時，Express 會加入數個回應標頭，內容可能如下所示：

要在 Ktor 中管理這些標頭，您需要安裝以下外掛程式：

Accept-Ranges ：
PartialContent
需要的相依性：io.ktor:%artifact_name% 伺服器範例：download-file，用戶端範例：client-download-file-range
Cache-Control ：
CachingHeaders
需要的相依性：io.ktor:%artifact_name%
ETag 與 Last-Modified ：
ConditionalHeaders
需要的相依性：io.ktor:%artifact_name%

路由

允許處理傳送到特定端點的請求，端點由特定的 HTTP 請求方法（GET、POST 等）與路徑定義。下方的範例展示如何處理傳送到 / 路徑的 GET 與 POST 請求。

Express	javascript 如需完整範例，請參閱 3_router 專案。
Ktor	kotlin TIP 請參閱接收請求以了解如何接收 `POST`、`PUT` 或 `PATCH` 請求的請求主體。如需完整範例，請參閱 3_router 專案。

以下範例示範如何依路徑分組路由處理常式。

Express

在 Express 中，您可以使用 app.route() 為路由路徑建立可鏈式呼叫的路由處理常式。

javascript

如需完整範例，請參閱 3_router 專案。

Ktor

Ktor 提供 route 函式，您可以在其中定義路徑，然後將該路徑的動詞作為巢狀函式放置在內。

kotlin

如需完整範例，請參閱 3_router 專案。

這兩個架構都允許您將相關路由分組在單個檔案中。

Express

Express 提供 express.Router 類別來建立可掛載的路由處理常式。假設我們在應用程式目錄中有一個 birds.js 路由檔案。此路由模組可以按照 app.js 所示載入到應用程式中：

birds.jsapp.js

javascript

如需完整範例，請參閱 3_router 專案。

Ktor

在 Ktor 中，常見的模式是在 Routing 型別上使用擴充函式來定義實際路由。下方的範例 (Birds.kt) 定義了 birdsRoutes 擴充函式。您可以透過在 routing 區塊內呼叫此函式，將對應的路由包含在應用程式 (Application.kt) 中：

Birds.ktApplication.kt

kotlin

如需完整範例，請參閱 3_router 專案。

除了將 URL 路徑指定為字串外，Ktor 還包含實作

的功能。

路由與查詢參數

本節將展示如何存取路由參數與查詢參數。

路由（或路徑）參數是具名的 URL 片段，用於擷取在 URL 中該位置指定的值。

Express

要在 Express 中存取路由參數，您可以使用 Request.params。例如，下方程式碼片段中的 req.parameters["login"] 對於 /user/admin 路徑將傳回 admin：

javascript

如需完整範例，請參閱 4_parameters 專案。

Ktor

在 Ktor 中，路由參數是使用 {param} 語法定義的。您可以使用 call.parameters 在路由處理常式中存取路由參數：

kotlin

如需完整範例，請參閱 4_parameters 專案。

下表比較了如何存取查詢字串的參數。

Express

要在 Express 中存取路由參數，您可以使用 Request.params。例如，下方程式碼片段中的 req.parameters["login"] 對於 /user/admin 路徑將傳回 admin：

javascript

如需完整範例，請參閱 4_parameters 專案。

Ktor

在 Ktor 中，路由參數是使用 {param} 語法定義的。您可以使用 call.parameters 在路由處理常式中存取路由參數：

kotlin

如需完整範例，請參閱 4_parameters 專案。

傳送回應

在之前的章節中，我們已經看過如何以純文字內容進行回應。讓我們來看看如何傳送 JSON、檔案與重新導向回應。

JSON

Express

要在 Express 中傳送具有適當內容類型的 JSON 回應，請呼叫 res.json 函式：

javascript

如需完整範例，請參閱 5_send_response 專案。

Ktor

在 Ktor 中，您需要安裝

外掛程式並配置 JSON 序列化器：

kotlin

要將資料序列化為 JSON，您需要建立一個帶有 @Serializable 註解的資料類別：

kotlin

然後，您可以使用 call.respond 在回應中傳送此類別的物件：

kotlin

如需完整範例，請參閱 5_send_response 專案。

檔案

Express

要在 Express 中以檔案回應，請使用 res.sendFile：

javascript

如需完整範例，請參閱 5_send_response 專案。

Ktor

Ktor 提供 call.respondFile 函式用於將檔案傳送至用戶端：

kotlin

如需完整範例，請參閱 5_send_response 專案。

Express 應用程式在以檔案回應時，會加入 Accept-Ranges HTTP 回應標頭。伺服器使用此標頭向用戶端宣告其支援部分請求以進行檔案下載。在 Ktor 中，您需要安裝

外掛程式以支援部分請求。

檔案附件

Express

res.download 函式會將指定的檔案作為附件傳輸：

javascript

如需完整範例，請參閱 5_send_response 專案。

Ktor

在 Ktor 中，您需要手動配置 Content-Disposition 標頭以將檔案作為附件傳輸：

kotlin

如需完整範例，請參閱 5_send_response 專案。

重新導向

Express

要在 Express 中產生重新導向回應，請呼叫 redirect 函式：

javascript

如需完整範例，請參閱 5_send_response 專案。

Ktor

在 Ktor 中，使用 respondRedirect 來傳送重新導向回應：

kotlin

如需完整範例，請參閱 5_send_response 專案。

範本

Express 與 Ktor 都能夠配合範本引擎來處理檢視 (views)。

Express

假設我們在 views 資料夾中有以下的 Pug 範本：

要以該範本回應，請呼叫 res.render：

javascript

如需完整範例，請參閱 6_templates 專案。

Ktor

Ktor 支援數種

，如 FreeMarker、Velocity 等。例如，如果您需要以放置在應用程式資源中的 FreeMarker 範本回應，請安裝並配置 FreeMarker 外掛程式，然後使用 call.respond 傳送範本：

kotlin

如需完整範例，請參閱 6_templates 專案。

接收請求

本節將展示如何接收不同格式的請求主體。

原始文字

下方的 POST 請求向伺服器傳送文字資料：

http

讓我們來看看如何在伺服器端將此請求的主體作為純文字接收。

Express

要在 Express 中剖析傳入的請求主體，您需要加入 body-parser：

javascript

在 post 處理常式中，您需要傳遞文字剖析器 (bodyParser.text)。請求主體將可透過 req.body 屬性取得：

javascript

如需完整範例，請參閱 7_receive_request 專案。

Ktor

在 Ktor 中，您可以使用 call.receiveText 將主體作為文字接收：

kotlin

如需完整範例，請參閱 7_receive_request 專案。

JSON

在本節中，我們將探討如何接收 JSON 主體。下方的範例顯示了一個在其主體中帶有 JSON 物件的 POST 請求：

http

Express

要在 Express 中接收 JSON，請使用 bodyParser.json：

javascript

如需完整範例，請參閱 7_receive_request 專案。

Ktor

在 Ktor 中，您需要安裝

外掛程式並配置 Json 序列化器：

kotlin

要將接收到的資料還原序列化為物件，您需要建立一個資料類別：

kotlin

然後，使用接受此資料類別作為參數的 receive 方法：

kotlin

如需完整範例，請參閱 7_receive_request 專案。

URL 編碼

現在讓我們來看看如何接收使用 application/x-www-form-urlencoded 類型傳送的表單資料。下方的程式碼片段顯示了一個帶有表單資料的範例 POST 請求：

http

Express

與純文字和 JSON 同樣，Express 需要 body-parser。您需要將剖析器型別設定為 bodyParser.urlencoded：

javascript

如需完整範例，請參閱 7_receive_request 專案。

Ktor

在 Ktor 中，使用 call.receiveParameters 函式：

kotlin

如需完整範例，請參閱 7_receive_request 專案。

原始資料

下一個使用案例是處理二進位資料。下方的請求將帶有 application/octet-stream 類型的 PNG 影像傳送至伺服器：

http

Express

要在 Express 中處理二進位資料，請將剖析器型別設定為 raw：

javascript

如需完整範例，請參閱 7_receive_request 專案。

Ktor

Ktor 提供 ByteReadChannel 與 ByteWriteChannel 用於非同步讀取／寫入位元組序列：

kotlin

如需完整範例，請參閱 7_receive request 專案。

多部分 (Multipart)

在最後一節中，讓我們來看看如何處理多部分 (multipart) 主體。下方的 POST 請求使用 multipart/form-data 類型傳送 PNG 影像與說明：

http

Express

Express 需要個別的模組來剖析多部分資料。在下方的範例中，使用了 multer 將檔案上傳至伺服器：

javascript

如需完整範例，請參閱 7_receive_request 專案。

Ktor

在 Ktor 中，如果您需要接收作為多部分請求的一部分傳送的檔案，請呼叫 receiveMultipart 函式，然後視需要對每個部分進行迴圈處理。在下方的範例中，使用 PartData.FileItem 將檔案作為位元組串流接收：

kotlin

如需完整範例，請參閱 7_receive_request 專案。

建立中介軟體

最後我們要探討的是如何建立允許您擴充伺服器功能的中介軟體。下方的範例展示如何使用 Express 與 Ktor 實作請求記錄。

Express

在 Express 中，中介軟體是使用 app.use 綁定到應用程式的函式：

javascript

如需完整範例，請參閱 8_middleware 專案。

Ktor

Ktor 允許您使用

來擴充其功能。下方的程式碼範例展示如何處理 onCall 以實作請求記錄：

kotlin

如需完整範例，請參閱 8_middleware 專案。

下一步

本指南中還有許多未涵蓋的使用案例，如工作階段管理、授權、資料庫整合等。對於大多數功能，Ktor 提供了專用的外掛程式，可以安裝在應用程式中並根據需要進行配置。要繼續您的 Ktor 旅程，請造訪學習頁面，其中提供了一系列的逐步指南與開箱即用的範例。

新增相依性

相依注入

範本製作

驗證與授權

JSON Web Tokens

WebSockets

建立 Fat JAR

驗證與授權

WebSockets

從 Express 遷移至 Ktor ​

從 Express 遷移至 Ktor

產生應用程式

Hello world

提供靜態內容

路由

路由與查詢參數

傳送回應

JSON

檔案

檔案附件

重新導向

範本

接收請求

原始文字

JSON

URL 編碼

原始資料

多部分 (Multipart)

建立中介軟體

下一步

從 Express 遷移至 Ktor