在Kotlin Ktor框架中处理multipart请求是文件上传、表单混合数据提交场景下的常见需求，part.readBytes()是读取multipart请求中单个部分二进制数据的核心方法，掌握其用法能高效完成相关功能开发。
Ktor处理multipart请求的前置准备
首先需要在项目的构建文件中添加Ktor的multipart相关依赖，以Gradle为例，在build.gradle.kts中添加如下依赖：
dependencies {
implementation("io.ktor:ktor-server-core:2.3.0")
implementation("io.ktor:ktor-server-multipart:2.3.0")
implementation("io.ktor:ktor-server-netty:2.3.0")
}
添加依赖后，需要在Ktor应用的初始化阶段安装Multipart插件，否则无法解析multipart类型的请求：
import io.ktor.server.application.*
import io.ktor.server.plugins.multipart.*
fun Application.module() {
install(Multipart)
// 其他插件安装和路由配置
}
multipart请求的基本处理流程
Ktor中处理multipart请求的核心是通过call.receiveMultipart()方法获取multipart的迭代器，然后遍历每个部分进行处理。每个部分对应PartData类型，常见的有PartData.FormItem（表单普通字段）和PartData.FileItem（文件字段）。
基础的multipart请求处理路由示例如下：
import io.ktor.server.routing.*
import io.ktor.server.request.*
import io.ktor.http.content.*
fun Application.configureRoutes() {
routing {
post("/upload") {
val multipart = call.receiveMultipart()
multipart.forEachPart { part ->
when (part) {
is PartData.FormItem -> {
// 处理普通表单字段
val fieldName = part.name
val fieldValue = part.value
println("表单字段 $fieldName 的值为 $fieldValue")
}
is PartData.FileItem -> {
// 处理文件字段
val fileName = part.originalFileName
println("上传的文件名为 $fileName")
}
else -> {}
}
part.dispose() // 处理完当前部分后释放资源
}
call.respondText("上传处理完成")
}
}
}
part.readBytes()的具体用法
part.readBytes()是PartData.FileItem和PartData.FormItem都具备的方法，用于读取当前part的全部二进制数据，返回值为ByteArray类型。该方法会一次性将part的所有数据读入内存，因此需要注意数据大小避免内存溢出。
读取文件字段的二进制数据
当处理文件上传时，使用part.readBytes()可以直接获取文件的完整字节数组，之后可以将字节数组写入本地文件或者进行其他处理：
import java.io.File
routing {
post("/upload_file") {
val multipart = call.receiveMultipart()
multipart.forEachPart { part ->
if (part is PartData.FileItem) {
val fileName = part.originalFileName ?: "unknown_file"
val fileBytes = part.readBytes() // 读取文件全部字节
// 将字节数组写入本地文件
val saveFile = File("uploads/$fileName")
saveFile.parentFile?.mkdirs()
saveFile.writeBytes(fileBytes)
println("文件 $fileName 保存成功，大小 ${fileBytes.size} 字节")
}
part.dispose()
}
call.respondText("文件上传成功")
}
}
读取普通表单字段的二进制数据
普通表单字段也可以通过part.readBytes()读取，不过通常普通字段更推荐使用PartData.FormItem的value属性直接获取字符串，只有在需要原始字节的场景下才使用该方法：
routing {
post("/upload_form") {
val multipart = call.receiveMultipart()
multipart.forEachPart { part ->
if (part is PartData.FormItem) {
val fieldName = part.name ?: "unknown_field"
val fieldBytes = part.readBytes() // 读取字段原始字节
val fieldValue = String(fieldBytes, Charsets.UTF_8) // 转为字符串
println("字段 $fieldName 的原始字节长度 ${fieldBytes.size}，值为 $fieldValue")
}
part.dispose()
}
call.respondText("表单处理完成")
}
}
使用part.readBytes()的注意事项
- 内存占用问题：
part.readBytes()会将整个part的数据一次性加载到内存中，如果处理大文件上传，建议使用流式读取的方式，避免内存溢出。可以通过part.provider()获取输入流，分块读取数据。 - 资源释放：处理完每个part之后，一定要调用
part.dispose()释放资源，否则可能导致内存泄漏。 - 数据完整性：
readBytes()会读取part的所有数据，如果请求传输过程中数据不完整，该方法会抛出异常，需要做好异常处理。 - 编码问题：如果是文本类型的part，读取字节后需要根据正确的字符集转换为字符串，避免出现乱码。
流式读取大文件的替代方案
如果上传的文件较大，不适合使用part.readBytes()一次性读取，可以使用流式读取的方式：
import java.io.FileOutputStream
routing {
post("/upload_large_file") {
val multipart = call.receiveMultipart()
multipart.forEachPart { part ->
if (part is PartData.FileItem) {
val fileName = part.originalFileName ?: "large_file"
val saveFile = File("uploads/$fileName")
saveFile.parentFile?.mkdirs()
val outputStream = FileOutputStream(saveFile)
// 获取输入流分块读取
part.streamProvider().use { inputStream ->
val buffer = ByteArray(1024 * 8)
var bytesRead: Int
while (inputStream.read(buffer).also { bytesRead = it } != -1) {
outputStream.write(buffer, 0, bytesRead)
}
}
outputStream.close()
println("大文件 $fileName 流式保存成功")
}
part.dispose()
}
call.respondText("大文件上传成功")
}
}
常见问题解答
问：part.readBytes()读取后数据为空是什么原因？
答：可能是part已经被读取过一次，Ktor的part数据只能读取一次，重复调用readBytes()会返回空数组，需要避免重复读取同一个part。
问：读取文件时中文文件名乱码怎么处理？
答：可以在安装Multipart插件时配置字符集，或者在获取originalFileName后进行转码处理，确保文件名编码正确。
KotlinKtormultipart请求part_readBytes修改时间：2026-06-23 15:54:46