Skip to content

从 Express 迁移到 Ktor

在本指南中,我们将了解在基本场景下如何将 Express 应用程序迁移到 Ktor:从生成应用程序、编写您的第一个应用程序,到创建用于扩展应用程序功能的中间件。

生成应用

Express

您可以使用 express-generator 工具生成新的 Express 应用程序:

shell
npx express-generator
Ktor

Ktor 提供了以下几种生成应用程序骨架的方式:

有关详细说明,请参阅创建、打开和运行新的 Ktor 项目了解如何使用 Ktor 打开、运行和测试服务器应用程序。教程。

Hello world

在本节中,我们将了解如何创建最简单的服务器应用程序,该程序接收 GET 请求并响应预定义的纯文本。

Express

以下示例展示了启动服务器并侦听端口 3000 连接的 Express 应用程序。

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 文件。假设我们有一个包含主 index.html 页面和一组关联资源的 public 文件夹。

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

路由

路由路由是处理服务器应用程序中传入请求的核心插件。允许处理发送到特定端点的传入请求,该端点由特定的 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。例如,在下面的代码片段中,针对 /user/admin 路径,req.params["login"] 将返回 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。例如,在下面的代码片段中,针对 /user/admin 路径,req.parameters["login"] 将返回 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 需要一个单独的模块来解析多部分数据。在以下示例中,使用 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 中,如果您需要接收作为多部分请求一部分发送的文件,请调用 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 页面,其中提供了一系列分步指南和开箱即用的示例。