Skip to content

從 Express 遷移到 Ktor

在本指南中,我們將探討在基本案例中如何將 Express 應用程式遷移至 Ktor:從產生應用程式與編寫你的第一個應用程式,到建立用於擴充應用程式功能性的中介軟體。

產生應用程式

Express

你可以使用 express-generator 工具產生新的 Express 應用程式:

shell
npx express-generator
Ktor

Ktor 提供了以下幾種產生應用程式骨架的方法:

有關詳細說明,請參閱建立、開啟與執行新的 Ktor 專案了解如何使用 Ktor 開啟、執行和測試伺服器應用程式。教學。

Hello world

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

Express

以下範例展示了 Express 應用程式如何啟動伺服器並在連接埠 3000 監聽連線。

javascript
const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
    res.send('Hello World!')
})

app.listen(port, () => {
    console.log(`Responding at http://0.0.0.0:${port}/`)
})

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

Ktor

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

kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main() {
    embeddedServer(Netty, port = 8080, host = "0.0.0.0") {
        routing {
            get("/") {
                call.respondText("Hello World!")
            }
        }
    }.start(wait = true)
}

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

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

請注意,上述 Express 應用程式新增了 Date 、 X-Powered-By 以及 ETag 回應標頭,內容可能如下所示:

Date: Fri, 05 Aug 2022 06:30:48 GMT
X-Powered-By: Express
ETag: W/"c-Lve95gjOVATpfV8EL5X4nxwjKHE"

若要在 Ktor 中為每個回應新增預設的 Server 和 Date 標頭, 你需要安裝 DefaultHeaders必要相依性:io.ktor:ktor-server-default-headers 外掛程式。ConditionalHeaders必要相依性:io.ktor:ktor-server-conditional-headers 外掛程式可用於配置 Etag 回應標頭。

提供靜態內容

在本節中,我們將了解如何在 Express 和 Ktor 中提供圖片、CSS 檔案以及 JavaScript 檔案等靜態檔案。 假設我們有一個 public 資料夾,內含主頁面 index.html 以及一組連結的資源。

public
├── index.html
├── ktor_logo.png
├── css
│   └──styles.css
└── js
    └── script.js
Express

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

javascript
const express = require('express')
const app = express()
const port = 3000

app.use(express.static('public'))

app.listen(port, () => {
    console.log(`Responding at http://0.0.0.0:${port}/`)
})

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

Ktor

在 Ktor 中,使用 staticFiles() 函式將任何發送至 / 路徑的請求對應到 public 實體資料夾。 此函式支援遞迴提供來自 public 資料夾的所有檔案。

kotlin
import io.ktor.server.application.*
import io.ktor.server.http.content.*
import io.ktor.server.routing.*
import java.io.*

fun main(args: Array<String>): Unit =
    io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    routing {
        staticFiles("", File("public"), "index.html")
    }
}

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

在提供靜態內容時,Express 會新增數個回應標頭,內容可能如下所示:

Accept-Ranges: bytes
Cache-Control: public, max-age=0
ETag: W/"181-1823feafeb1"
Last-Modified: Wed, 27 Jul 2022 13:49:01 GMT

若要在 Ktor 中管理這些標頭,你需要安裝以下外掛程式:

  • Accept-Ranges : PartialContent必要相依性:io.ktor:ktor-server-partial-content

  • Cache-Control : CachingHeaders必要相依性: io.ktor:ktor-server-caching-headers

  • ETag 以及 Last-Modified : ConditionalHeaders必要相依性:io.ktor:ktor-server-conditional-headers

路由

Routing路由是伺服器應用程式中處理傳入請求的核心外掛程式。 允許處理傳入至特定端點的請求,端點由特定 HTTP 請求方法(GET、POST 等)與路徑所定義。 以下範例展示如何處理傳入至 / 路徑的 GET 和 POST 請求。

Express
javascript
app.get('/', (req, res) => {
    res.send('GET request to the homepage')
})

app.post('/', (req, res) => {
    res.send('POST request to the homepage')
})

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

Ktor
kotlin
routing {
    get("/") {
        call.respondText("GET request to the homepage")
    }
    post("/") {
        call.respondText("POST request to the homepage")
    }
}

請參閱接收請求以了解如何接收 POST、PUT 或 PATCH 請求的請求內文。

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

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

Express

在 Express 中,你可以使用 app.route() 為路由路徑建立可鏈結的路由處理常式。

javascript
app.route('/book')
    .get((req, res) => {
        res.send('Get a random book')
    })
    .post((req, res) => {
        res.send('Add a book')
    })
    .put((req, res) => {
        res.send('Update the book')
    })

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

Ktor

Ktor 提供了 route 函式, 你可以在其中定義路徑,然後將該路徑的 HTTP 動詞作為巢狀函式置於其中。

kotlin
routing {
    route("book") {
        get {
            call.respondText("Get a random book")
        }
        post {
            call.respondText("Add a book")
        }
        put {
            call.respondText("Update the book")
        }
    }
}

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

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

Express

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

javascript
const express = require('express')
const router = express.Router()

router.get('/', (req, res) => {
    res.send('Birds home page')
})

router.get('/about', (req, res) => {
    res.send('About birds')
})

module.exports = router
javascript
const express = require('express')
const app = express()
const birds = require('./birds')
const port = 3000

app.use('/birds', birds)

app.listen(port, () => {
    console.log(`Responding at http://0.0.0.0:${port}/`)
})

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

Ktor

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

kotlin
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Routing.birdsRoutes() {
    route("/birds") {
        get {
            call.respondText("Birds home page")
        }
        get("/about") {
            call.respondText("About birds")
        }
    }
}
kotlin
import com.example.routes.*
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main(args: Array<String>): Unit =
    io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    routing {
        birdsRoutes()
    }
}

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

除了將 URL 路徑指定為字串之外,Ktor 還支援實作型別安全路由Resources 外掛程式可讓您實作型別安全路由。的功能。

路由與查詢參數

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

路由(或路徑)參數是具名的 URL 區段,用於擷取在其 URL 位置所指定的值。

Express

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

javascript
app.get('/user/:login', (req, res) => {
    if (req.params['login'] === 'admin') {
        res.send('You are logged in as Admin')
    } else {
        res.send('You are logged in as Guest')
    }
})

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

Ktor

在 Ktor 中,路由參數使用 {param} 語法定義。 你可以在路由處理常式中使用 call.parameters 來存取路由參數:

kotlin
routing {
    get("/user/{login}") {
        if (call.parameters["login"] == "admin") {
            call.respondText("You are logged in as Admin")
        } else {
            call.respondText("You are logged in as Guest")
        }
    }
}

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

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

Express

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

javascript
app.get('/products', (req, res) => {
    if (req.query['price'] === 'asc') {
        res.send('Products from the lowest price to the highest')
    }
})

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

Ktor

在 Ktor 中,路由參數使用 {param} 語法定義。 你可以在路由處理常式中使用 call.parameters 來存取路由參數:

kotlin
routing {
    get("/products") {
        if (call.request.queryParameters["price"] == "asc") {
            call.respondText("Products from the lowest price to the highest")
        }
    }
}

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

發送回應

在先前的章節中,我們已經了解如何使用純文字內容進行回應。 接下來看看如何發送 JSON、檔案與重新導向回應。

JSON

Express

若要在 Express 中發送帶有適當內容類型的 JSON 回應, 請呼叫 res.json 函式:

javascript
const car = {type:"Fiat", model:"500", color:"white"};
app.get('/json', (req, res) => {
    res.json(car)
})

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

Ktor

在 Ktor 中,你需要安裝 ContentNegotiationContentNegotiation 外掛程式有兩個主要用途:在用戶端與伺服器之間協商媒體類型,以及將內容以特定格式進行序列化/反序列化。 外掛程式並配置 JSON 序列化器:

kotlin
install(ContentNegotiation) {
    json()
}

若要將資料序列化為 JSON,你需要建立帶有 @Serializable 註解的資料類別:

kotlin
@Serializable
data class Car(val type: String, val model: String, val color: String)

然後,你可以使用 call.respond 在回應中發送此類別的物件:

kotlin
get("/json") {
    call.respond(Car("Fiat", "500", "white"))
}

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

檔案

Express

若要在 Express 中以檔案進行回應,請使用 res.sendFile:

javascript
const path = require("path")

app.get('/file', (req, res) => {
    res.sendFile(path.join(__dirname, 'ktor_logo.png'))
})

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

Ktor

Ktor 提供了 call.respondFile 函式用於向用戶端發送檔案:

kotlin
get("/file") {
    val file = File("public/ktor_logo.png")
    call.respondFile(file)
}

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

Express 應用程式在回應檔案時會新增 Accept-Ranges HTTP 回應標頭。 伺服器使用此標頭宣傳其支援用戶端下載檔案時的部分請求。 在 Ktor 中,你需要安裝 PartialContent必要相依性:io.ktor:ktor-server-partial-content 外掛程式以支援部分請求。

檔案附件

Express

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

javascript
app.get('/file-attachment', (req, res) => {
    res.download("ktor_logo.png")
})

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

Ktor

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

kotlin
get("/file-attachment") {
    val file = File("public/ktor_logo.png")
    call.response.header(
        HttpHeaders.ContentDisposition,
        ContentDisposition.Attachment.withParameter(ContentDisposition.Parameters.FileName, "ktor_logo.png")
            .toString()
    )
    call.respondFile(file)
}

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

重新導向

Express

若要在 Express 中產生重新導向回應,請呼叫 redirect 函式:

javascript
app.get('/old', (req, res) => {
    res.redirect(301, "moved")
})

app.get('/moved', (req, res) => {
    res.send('Moved resource')
})

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

Ktor

在 Ktor 中,使用 respondRedirect 發送重新導向回應:

kotlin
get("/old") {
    call.respondRedirect("/moved", permanent = true)
}
get("/moved") {
    call.respondText("Moved resource")
}

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

範本

Express 和 Ktor 都支援使用範本引擎來處理檢視。

Express

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

html
  head
    title= title
  body
    h1= message

若要使用此範本進行回應,請呼叫 res.render:

javascript
app.set('views', './views')
app.set('view engine', 'pug')

app.get('/', (req, res) => {
    res.render('index', { title: 'Hey', message: 'Hello there!' })
})

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

Ktor

Ktor 支援多種 JVM 範本引擎了解如何處理使用 HTML/CSS 或 JVM 範本引擎建置的檢視。, 例如 FreeMarker、Velocity 等。 例如,如果你需要使用位於應用程式資源中的 FreeMarker 範本進行回應, 請安裝並配置 FreeMarker 外掛程式, 然後使用 call.respond 發送範本:

kotlin
fun Application.module() {
    install(FreeMarker) {
        templateLoader = ClassTemplateLoader(this::class.java.classLoader, "views")
    }
    routing {
        get("/") {
            val article = Article("Hey", "Hello there!")
            call.respond(FreeMarkerContent("index.ftl", mapOf("article" to article)))
        }
    }
}

data class Article(val title: String, val message: String)

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

接收請求

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

原始文字

以下 POST 請求向伺服器發送文字資料:

http
POST http://0.0.0.0:3000/text
Content-Type: text/plain

Hello, world!

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

Express

若要在 Express 中剖析傳入的請求內文,你需要新增 body-parser:

javascript
const bodyParser = require('body-parser')

在 post 處理常式中, 你需要傳入文字剖析器(bodyParser.text)。 請求內文將可透過 req.body 屬性取得:

javascript
app.post('/text', bodyParser.text(), (req, res) => {
    let text = req.body
    res.send(text)
})

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

Ktor

在 Ktor 中,你可以使用 call.receiveText 將內文作為文字接收:

kotlin
post("/text") {
    val text = call.receiveText()
    call.respondText(text)
}

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

JSON

在本節中,我們將探討如何接收 JSON 內文。 以下範例展示了內文帶有 JSON 物件的 POST 請求:

http
POST http://0.0.0.0:3000/json
Content-Type: application/json

{
  "type": "Fiat",
  "model" : "500",
  "color": "white"
}
Express

若要在 Express 中接收 JSON,請使用 bodyParser.json:

javascript
const bodyParser = require('body-parser')

app.post('/json', bodyParser.json(), (req, res) => {
    let car = req.body
    res.send(car)
})

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

Ktor

在 Ktor 中,你需要安裝 ContentNegotiationContentNegotiation 外掛程式有兩個主要用途:在用戶端與伺服器之間協商媒體類型,以及將內容以特定格式進行序列化/反序列化。 外掛程式 並配置 Json 序列化器:

kotlin
install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
    })
}

若要將接收到的資料反序列化為物件,你需要建立一個資料類別:

kotlin
@Serializable
data class Car(val type: String, val model: String, val color: String)

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

kotlin
post("/json") {
    val car = call.receive<Car>()
    call.respond(car)
}

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

URL 編碼

現在讓我們看看如何接收使用 application/x-www-form-urlencoded 類型發送的表單資料。 以下程式碼片段展示了帶有表單資料的 POST 請求範例:

http
POST http://localhost:3000/urlencoded
Content-Type: application/x-www-form-urlencoded

username=JetBrains&email=example@jetbrains.com&password=foobar&confirmation=foobar
Express

與純文字和 JSON 一樣,Express 需要 body-parser。 你需要將剖析器類型設定為 bodyParser.urlencoded:

javascript
const bodyParser = require('body-parser')

app.post('/urlencoded', bodyParser.urlencoded({extended: true}), (req, res) => {
    let user = req.body
    res.send(`The ${user["username"]} account is created`)
})

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

Ktor

在 Ktor 中,使用 call.receiveParameters 函式:

kotlin
post("/urlencoded") {
    val formParameters = call.receiveParameters()
    val username = formParameters["username"].toString()
    call.respondText("The '$username' account is created")
}

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

原始資料

下一個使用案例是處理二進位資料。 以下請求將帶有 application/octet-stream 的 PNG 圖片發送至伺服器:

http
POST http://localhost:3000/raw
Content-Type: application/octet-stream

< ./ktor_logo.png
Express

若要在 Express 中處理二進位資料,請將剖析器類型設定為 raw:

javascript
const bodyParser = require('body-parser')
const fs = require('fs')

app.post('/raw', bodyParser.raw({type: () => true}), (req, res) => {
    let rawBody = req.body
    fs.createWriteStream('./uploads/ktor_logo.png').write(rawBody)
    res.send('A file is uploaded')
})

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

Ktor

Ktor 提供了 ByteReadChannel 與 ByteWriteChannel, 用於非同步讀取/寫入位元組序列:

kotlin
post("/raw") {
    val file = File("uploads/ktor_logo.png")
    call.receiveChannel().copyAndClose(file.writeChannel())
    call.respondText("A file is uploaded")
}

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

Multipart

在最後一節中,我們來看看如何處理 multipart 內文。 以下 POST 請求使用 multipart/form-data 類型發送附帶說明的 PNG 圖片:

http
POST http://localhost:3000/multipart
Content-Type: multipart/form-data; boundary=WebAppBoundary

--WebAppBoundary
Content-Disposition: form-data; name="description"
Content-Type: text/plain

Ktor logo
--WebAppBoundary
Content-Disposition: form-data; name="image"; filename="ktor_logo.png"
Content-Type: image/png

< ./ktor_logo.png
--WebAppBoundary--
Express

Express 需要獨立的模組來剖析 multipart 資料。 在以下範例中,使用了 multer 將檔案上傳到伺服器:

javascript
const multer = require('multer')

const storage = multer.diskStorage({
    destination: './uploads/',
    filename: function (req, file, cb) {
        cb(null, file.originalname);
    }
})
const upload = multer({storage: storage});
app.post('/multipart', upload.single('image'), function (req, res, next) {
    let fileDescription = req.body["description"]
    let fileName = req.file.filename
    res.send(`${fileDescription} is uploaded to uploads/${fileName}`)
})

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

Ktor

在 Ktor 中,如果你需要接收作為 multipart 請求一部分發送的檔案, 請呼叫 receiveMultipart 函式,然後依需求對每個部分進行迴圈處理。 在以下範例中,使用 PartData.FileItem 將檔案作為位元組串流接收:

kotlin
post("/multipart") {
    var fileDescription = ""
    var fileName = ""
    val multipartData = call.receiveMultipart()
    multipartData.forEachPart { part ->
        when (part) {
            is PartData.FormItem -> {
                fileDescription = part.value
            }

            is PartData.FileItem -> {
                fileName = part.originalFileName as String
                val channel = part.provider()
                SystemFileSystem.sink(Path("uploads/$fileName")).use { sink ->
                    while (!channel.exhausted()) {
                        channel.readBuffer().transferTo(sink)
                        sink.flush()
                    }
                }
            }

            else -> {}
        }
        part.dispose()
    }
    call.respondText("$fileDescription is uploaded to 'uploads/$fileName'")
}

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

建立中介軟體

最後我們要看的是如何建立中介軟體來擴充伺服器功能性。 以下範例展示了如何使用 Express 和 Ktor 實作請求記錄。

Express

在 Express 中,中介軟體是使用 app.use 繫結到應用程式的函式:

javascript
const express = require('express')
const app = express()
const port = 3000

const requestLogging = function (req, res, next) {
    let scheme = req.protocol
    let host = req.headers.host
    let url = req.url
    console.log(`Request URL: ${scheme}://${host}${url}`)
    next()
}

app.use(requestLogging)

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

Ktor

Ktor 允許你使用自訂外掛程式了解如何建立你自己的自訂外掛程式。擴充其功能性。 以下程式碼範例展示如何處理 onCall 來實作請求記錄:

kotlin
val RequestLoggingPlugin = createApplicationPlugin(name = "RequestLoggingPlugin") {
    onCall { call ->
        call.request.origin.apply {
            println("Request URL: $scheme://$localHost:$localPort$uri")
        }
    }
}

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

後續步驟

本指南中還有許多未涵蓋的使用案例, 例如工作階段管理、授權、資料庫整合等等。 針對大部分的這些功能性,Ktor 都提供了專用的外掛程式, 可以安裝在應用程式中並根據需求進行配置。 若要繼續你的 Ktor 之旅, 請造訪 Learn 頁面 ,該頁面提供了一系列逐步指南和現成可用的範例。