处理请求
Ktor 允许您从路由处理程序内部处理传入的请求并发送响应。
每个路由处理程序都通过 call 属性提供一个 ApplicationCall 对象。ApplicationCall 表示单个 HTTP 交换,并提供对传入请求和传出响应的访问。
在路由处理程序内部,您可以使用 ApplicationCall 执行以下操作:
通用请求信息
您可以通过 call.request 属性访问请求数据。这将返回一个 ApplicationRequest 实例,该实例提供对底层 HTTP 请求信息的访问。
例如,您可以在 GET 请求处理程序中使用 call.request.uri 获取请求 URI:
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":
get("/user/{login}") {
if (call.parameters["login"] == "admin") {
// ...
}
}查询形参
要获取 URL 查询字符串的形参,请使用 ApplicationRequest.queryParameters 属性。
以下示例访问了对 /products?price=asc 发起的请求中的 price 查询形参:
get("/products") {
if (call.request.queryParameters["price"] == "asc") {
// 按价格从低到高显示产品
}
}您还可以使用 ApplicationRequest.queryString() 函数获取整个查询字符串。
必选请求形参
处理请求时,通常会从路径形参、查询形参、标头或 Cookie 中提取值,并在继续处理请求之前验证它们是否存在。
Ktor 提供了以下辅助函数来简化对必选请求数据的访问,从而避免在每个路由处理程序中手动检查缺失值:
.requireQueryParameter()从请求 URL 中检索所需的查询形参。.requireHeader()检索所需的 HTTP 标头值。.requireCookie()检索所需的 Cookie 值,(可选)使用指定的编码进行解码。.requirePathParameter()从路由定义中检索所需的路径形参。
每个函数都会返回一个非 null 值,或者在请求的值缺失时抛出 MissingRequestParameterException。
post("/checkout/{cartId}") {
val userId = call.requireCookie("userId")
val cartId = call.requirePathParameter("cartId")
val amount = call.requireQueryParameter("amount").toLong()
// 业务逻辑
}正文内容
要访问请求正文,请使用 Ktor 的接收函数。具体使用哪种函数取决于您需要原始内容、反序列化对象、表单形参还是多部分数据。
原始载荷
要访问原始正文载荷并手动进行解析,请使用 ApplicationCall.receive() 函数,该函数接受要接收的载荷类型。
假设客户端发送了以下 HTTP 请求:
POST http://localhost:8080/text
Content-Type: text/plain
Hello, world!您可以将请求正文作为 String、ByteArray 或 ByteReadChannel 接收。
String
要将请求正文作为文本接收,请使用 .receive<String>() 或 .receiveText() 函数:
post("/text") {
val text = call.receiveText()
call.respondText(text)
}ByteArray
要将请求正文作为字节数组接收,请使用 .receive<ByteArray>() 函数:
post("/bytes") {
val bytes = call.receive<ByteArray>()
call.respond(String(bytes))
}ByteReadChannel
要将其作为 ByteReadChannel 异步读取正文,请使用 .receive<ByteReadChannel>() 或 .receiveChannel() 函数:
post("/channel") {
val readChannel = call.receiveChannel()
val text = readChannel.readRemaining().readString()
call.respondText(text)
}您还可以使用 ByteReadChannel 上传文件:
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() 函数:
post("/customer") {
val customer = call.receive<Customer>()
customerStorage.add(customer)
call.respondText("Customer stored correctly", status = HttpStatusCode.Created)
}如果请求内容可以反序列化为 null,请使用可空类型实参:
val customer = call.receive<Customer?>()欲了解更多信息,请参阅 Ktor Server 中的内容协商与序列化。
表单形参
您可以使用 .receiveParameters() 函数接收通过 x-www-form-urlencoded 和 multipart/form-data 类型发送的表单形参。
例如,假设客户端发送了以下请求:
POST http://localhost:8080/signup
Content-Type: application/x-www-form-urlencoded
username=JetBrains&email=example@jetbrains.com&password=foobar&confirmation=foobar您可以按如下方式在代码中获取形参值:
post("/signup") {
val formParameters = call.receiveParameters()
val username = formParameters["username"].toString()
call.respondText("The '$username' account is created")
}有关完整示例,请参阅 post-form-parameters。
多部分表单数据
要接收作为多部分请求的一部分发送的文件,请使用 .receiveMultipart() 函数。
多部分请求数据是按顺序处理的,因此您无法直接访问其特定部分。每个部分都可以表示表单字段、文件或其他二进制内容,因此需要分别处理每种类型。
以下示例接收表单字段和文件,然后将文件保存到本地文件系统:
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() 函数:
val multipartData = call.receiveMultipart(formFieldLimit = 1024 * 1024 * 100)在此示例中,限制被设置为 100 MiB。
表单字段
PartData.FormItem 代表表单字段。您可以通过 value 属性访问其值:
when (part) {
is PartData.FormItem -> {
fileDescription = part.value
}
}文件上传
PartData.FileItem 代表上传的文件。您可以将文件上传作为字节流进行处理。使用 .provider() 函数以 ByteReadChannel 形式访问文件内容,并将其流式传输到目标位置:
when (part) {
is PartData.FileItem -> {
fileName = part.originalFileName as String
val file = File("uploads/$fileName")
part.provider().copyAndClose(file.writeChannel())
}
}使用 .copyAndClose() 函数,您可以将文件内容写入指定目标位置,同时确保正确的资源清理。
如果请求包含 Content-Length 标头值,您可以使用它来检查整个请求正文的大小:
post("/upload") {
val contentLength = call.request.header(HttpHeaders.ContentLength)
// ...
}对于多部分请求,Content-Length 表示整个多部分正文的大小,而不是单个上传文件的大小。
资源清理
表单处理完成后,使用 .dispose() 函数处置每个多部分项以释放其资源:
part.dispose()要了解如何运行此示例,请参阅 upload-file。
