Skip to content

处理请求 ​

Ktor 允许您从路由处理程序内部处理传入的请求并发送响应。

每个路由处理程序都通过 call 属性提供一个 ApplicationCall 对象。ApplicationCall 表示单个 HTTP 交换,并提供对传入请求和传出响应的访问。

在路由处理程序内部,您可以使用 ApplicationCall 执行以下操作:

通用请求信息 ​

您可以通过 call.request 属性访问请求数据。这将返回一个 ApplicationRequest 实例,该实例提供对底层 HTTP 请求信息的访问。

例如,您可以在 GET 请求处理程序中使用 call.request.uri 获取请求 URI:

kotlin
routing {
    get("/") {
        val uri = call.request.uri
        call.respondText("Request uri: $uri")
    }
}

call.respondText() 函数用于将纯文本响应发送回客户端。

标头 ​

要访问所有 HTTP 请求标头,请使用 ApplicationRequest.headers 属性。

为了方便起见,Ktor 还提供了专用的扩展函数来访问常用的标头,例如 .acceptEncoding()、.contentType() 和 .cacheControl()。

Cookie ​

要访问随请求发送的 Cookie,请使用 ApplicationRequest.cookies 属性。

有关使用 Cookie 处理会话的更多信息,请参阅会话部分。

连接详情 ​

使用 ApplicationRequest.local 属性可以访问连接详情,例如主机、端口和方案。

X-Forwarded- 标头 ​

要收集通过 HTTP 代理或负载均衡器传递的请求信息,请安装 Forwarded headers 插件。然后您可以通过 ApplicationRequest.origin 属性访问这些信息。

路径形参 ​

处理请求时,您可以使用 ApplicationCall.parameters 属性获取路径形参的值。

例如,对于向 /user/admin 发起的请求,call.parameters["login"] 将返回 "admin":

kotlin
get("/user/{login}") {
    if (call.parameters["login"] == "admin") {
        // ...
    }
}

查询形参 ​

要获取 URL 查询字符串的形参,请使用 ApplicationRequest.queryParameters 属性。

以下示例访问了对 /products?price=asc 发起的请求中的 price 查询形参:

kotlin
get("/products") {
    if (call.request.queryParameters["price"] == "asc") {
        // 按价格从低到高显示产品
    }
}

您还可以使用 ApplicationRequest.queryString() 函数获取整个查询字符串。

必选请求形参 ​

处理请求时,通常会从路径形参、查询形参、标头或 Cookie 中提取值,并在继续处理请求之前验证它们是否存在。

Ktor 提供了以下辅助函数来简化对必选请求数据的访问,从而避免在每个路由处理程序中手动检查缺失值:

每个函数都会返回一个非 null 值,或者在请求的值缺失时抛出 MissingRequestParameterException。

kotlin
post("/checkout/{cartId}") {
    val userId = call.requireCookie("userId")
    val cartId = call.requirePathParameter("cartId")
    val amount = call.requireQueryParameter("amount").toLong()

    // 业务逻辑
}

正文内容 ​

要访问请求正文,请使用 Ktor 的接收函数。具体使用哪种函数取决于您需要原始内容、反序列化对象、表单形参还是多部分数据。

原始载荷 ​

要访问原始正文载荷并手动进行解析,请使用 ApplicationCall.receive() 函数,该函数接受要接收的载荷类型。

假设客户端发送了以下 HTTP 请求:

HTTP
POST http://localhost:8080/text
Content-Type: text/plain

Hello, world!

您可以将请求正文作为 String、ByteArray 或 ByteReadChannel 接收。

String ​

要将请求正文作为文本接收,请使用 .receive<String>() 或 .receiveText() 函数:

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

ByteArray ​

要将请求正文作为字节数组接收,请使用 .receive<ByteArray>() 函数:

kotlin
        post("/bytes") {
            val bytes = call.receive<ByteArray>()
            call.respond(String(bytes))
        }

ByteReadChannel ​

要将其作为 ByteReadChannel 异步读取正文,请使用 .receive<ByteReadChannel>() 或 .receiveChannel() 函数:

kotlin
post("/channel") {
    val readChannel = call.receiveChannel()
    val text = readChannel.readRemaining().readString()
    call.respondText(text)
}

您还可以使用 ByteReadChannel 上传文件:

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

有关在 Ktor 通道与 RawSink、RawSource 或 OutputStream 等类型之间进行转换的信息,请参阅 I/O 互操作性。

有关完整示例,请参阅 post-raw-data。

对象 ​

Ktor 提供了 ContentNegotiation 插件来协商请求的媒体类型并将内容反序列化为所需类型的对象。

要接收并转换请求的内容,请使用带有预期类型的 ApplicationCall.receive() 函数:

kotlin
post("/customer") {
    val customer = call.receive<Customer>()
    customerStorage.add(customer)
    call.respondText("Customer stored correctly", status = HttpStatusCode.Created)
}

如果请求内容可以反序列化为 null,请使用可空类型实参:

kotlin
val customer = call.receive<Customer?>()

欲了解更多信息,请参阅 Ktor Server 中的内容协商与序列化。

表单形参 ​

您可以使用 .receiveParameters() 函数接收通过 x-www-form-urlencoded 和 multipart/form-data 类型发送的表单形参。

例如,假设客户端发送了以下请求:

HTTP
POST http://localhost:8080/signup
Content-Type: application/x-www-form-urlencoded

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

您可以按如下方式在代码中获取形参值:

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

有关完整示例,请参阅 post-form-parameters。

多部分表单数据 ​

要接收作为多部分请求的一部分发送的文件,请使用 .receiveMultipart() 函数。

多部分请求数据是按顺序处理的,因此您无法直接访问其特定部分。每个部分都可以表示表单字段、文件或其他二进制内容,因此需要分别处理每种类型。

以下示例接收表单字段和文件,然后将文件保存到本地文件系统:

kotlin
import io.ktor.server.application.*
import io.ktor.http.content.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.util.cio.*
import io.ktor.utils.io.*
import java.io.File

fun Application.main() {
    routing {
        post("/upload") {
            var fileDescription = ""
            var fileName = ""
            val multipartData = call.receiveMultipart(formFieldLimit = 1024 * 1024 * 100)

            multipartData.forEachPart { part ->
                when (part) {
                    is PartData.FormItem -> {
                        fileDescription = part.value
                    }

                    is PartData.FileItem -> {
                        fileName = part.originalFileName as String
                        val file = File("uploads/$fileName")
                        part.provider().copyAndClose(file.writeChannel())
                    }

                    else -> {}
                }
                part.dispose()
            }

            call.respondText("$fileDescription is uploaded to 'uploads/$fileName'")
        }
    }
}

默认文件大小限制 ​

默认情况下,二进制项和文件项的大小限制为 50 MiB。如果某个部分超过此限制,Ktor 会抛出 IOException。

要替代调用的默认限制,请将 formFieldLimit 形参传递给 .receiveMultipart() 函数:

kotlin
val multipartData = call.receiveMultipart(formFieldLimit = 1024 * 1024 * 100)

在此示例中,限制被设置为 100 MiB。

表单字段 ​

PartData.FormItem 代表表单字段。您可以通过 value 属性访问其值:

kotlin
when (part) {
    is PartData.FormItem -> {
        fileDescription = part.value
    }
}

文件上传 ​

PartData.FileItem 代表上传的文件。您可以将文件上传作为字节流进行处理。使用 .provider() 函数以 ByteReadChannel 形式访问文件内容,并将其流式传输到目标位置:

kotlin
when (part) {
    is PartData.FileItem -> {
        fileName = part.originalFileName as String
        val file = File("uploads/$fileName")
        part.provider().copyAndClose(file.writeChannel())
    }
}

使用 .copyAndClose() 函数,您可以将文件内容写入指定目标位置,同时确保正确的资源清理。

如果请求包含 Content-Length 标头值,您可以使用它来检查整个请求正文的大小:

kotlin
post("/upload") {
    val contentLength = call.request.header(HttpHeaders.ContentLength)
    // ...
}

对于多部分请求,Content-Length 表示整个多部分正文的大小,而不是单个上传文件的大小。

资源清理 ​

表单处理完成后,使用 .dispose() 函数处置每个多部分项以释放其资源:

kotlin
part.dispose()

要了解如何运行此示例,请参阅 upload-file。