Kotlin Academy · 课时

内容协商与 kotlinx.serialization

Q: 「内容协商与 kotlinx.serialization」这节课中我会学到什么？

配置 JSON 序列化，并自动反序列化请求正文。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

配置 JSON 序列化，并自动反序列化请求正文。

内容协商与 kotlinx.serialization 是 CoddyKit 上的免费 Kotlin Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Kotlin Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Kotlin Academy 课程共包含 4 节课。

什么是内容协商？

内容协商是 HTTP 的一种机制，客户端和服务器通过它协商响应正文的格式。客户端发送 Accept 标头，服务器选择最匹配的格式。Ktor 的 ContentNegotiation 插件会自动完成这一过程。

添加依赖项

添加 ContentNegotiation 插件和 kotlinx.serialization JSON 转换器：

dependencies {
    implementation("io.ktor:ktor-server-content-negotiation:2.3.12")
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.12")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

安装 ContentNegotiation

在 Application 模块中安装该插件，并注册 JSON 转换器：

import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json()
    }
}

@Serializable 数据类

使用 kotlinx.serialization 中的 @Serializable 为您的数据类添加注解。Kotlin 编译器插件会在编译时生成序列化器，因此运行时无需反射：

import kotlinx.serialization.Serializable

@Serializable
data class User(val id: Long, val name: String, val email: String)

使用可序列化对象进行响应

安装 ContentNegotiation 后，将任意 @Serializable 对象传递给 call.respond()。Ktor 会自动将其序列化为 JSON：

get("/users/{id}") {
    val user = User(1L, "Alice", "alice@example.com")
    call.respond(user)  // serialized to JSON
}

接收可序列化对象

使用 call.receive() 将请求正文反序列化为 @Serializable 类。如果正文格式错误，Ktor 会抛出 ContentTransformationException：

post("/users") {
    val newUser = call.receive<User>()
    call.respond(HttpStatusCode.Created, newUser)
}

自定义 JSON 配置

将 Json 实例传递给 json() 以自定义序列化：忽略未知键、美化输出、使用宽松模式等：

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

多种内容类型

注册多个转换器以支持不同的 Accept 类型。Ktor 会选择第一个与客户端 Accept 标头匹配的转换器：

install(ContentNegotiation) {
    json()
    // xml() with ktor-serialization-kotlinx-xml if needed
}

序列化列表和映射

将集合包装在响应对象中，或直接使用 call.respond(list)。只要元素类型带有 @Serializable，kotlinx.serialization 就能处理 List、Map 和嵌套泛型：

get("/users") {
    val users = listOf(
        User(1, "Alice", "a@example.com"),
        User(2, "Bob", "b@example.com")
    )
    call.respond(users)
}

自定义序列化器

对于您无法修改的类型（例如 java.time.Instant），请实现一个 KSerializer，并通过 @Serializable(with = MySerializer::class) 或上下文序列化器模块进行注册：

val module = SerializersModule {
    contextual(Instant::class, InstantSerializer)
}
install(ContentNegotiation) {
    json(Json { serializersModule = module })
}

反序列化失败的错误处理

请安装 StatusPages 插件，以便在 call.receive() 失败时返回整洁的错误响应：

install(StatusPages) {
    exception<ContentTransformationException> { call, _ ->
        call.respond(HttpStatusCode.BadRequest, "Invalid request body")
    }
}

快速检查

要让 Kotlin 数据类能够由 kotlinx.serialization 进行序列化，必须添加哪个注解？

回顾：内容协商与 kotlinx.serialization

要点：

安装 ContentNegotiation 和 json()，即可自动进行 JSON 序列化和反序列化
为数据类添加 @Serializable 注解
使用 call.respond(obj) 进行序列化，使用 call.receive() 进行反序列化
将 Json { ... } 实例传递给 json()，即可进行自定义配置
使用 StatusPages 优雅地处理反序列化错误

常见问题解答

「内容协商与 kotlinx.serialization」课时是免费的吗？

是的 — 「内容协商与 kotlinx.serialization」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Kotlin Academy 课程的其余内容，请升级到 CoddyKit PRO。 Kotlin Academy 课程共包含 4 节课。

「内容协商与 kotlinx.serialization」这节课中我会学到什么？

配置 JSON 序列化，并自动反序列化请求正文。你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Kotlin Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「内容协商与 kotlinx.serialization」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Kotlin Academy 课中编写并运行代码吗？

能。每节 Kotlin Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

Ktor 项目设置：embeddedServer 与 Application 模块
路由与类型化参数
内容协商与 kotlinx.serialization
身份验证插件：JWT 与会话

← 返回 Kotlin Academy