Kotlin Academy · 课时

kotlinx.serialization 配置

Q: 「kotlinx.serialization 配置」这节课中我会学到什么？

添加插件 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

添加插件

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

什么是 kotlinx.serialization？

kotlinx.serialization 是 Kotlin 官方库，用于在对象与 JSON 等格式之间进行转换。

纯 Kotlin 编写，可用于多平台
在编译时生成代码（无需反射）
由 JetBrains 维护

它需要配合编译器插件和运行时库使用。

为什么需要编译器插件

与基于反射的库不同，kotlinx.serialization 会在编译时生成序列化器。

速度更快，不产生运行时反射开销
可用于 Kotlin/Native 和反射能力有限的 JS
类型安全，并由编译器进行验证

因此您必须应用 kotlin-serialization 插件，而不能只添加依赖项。

应用插件（Kotlin DSL）

在 build.gradle.kts 中应用序列化插件，并使其版本与 Kotlin 插件的版本相同。

plugins {
    kotlin("jvm") version "2.0.0"
    kotlin("plugin.serialization") version "2.0.0"
}

添加运行时依赖项

插件会生成代码，但您还需要 JSON 运行时库。

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

版本对齐很重要

plugin.serialization 的版本必须与 Kotlin 编译器的版本匹配。运行时库使用独立的版本。

插件版本 = Kotlin 版本（例如 2.0.0）
运行时版本独立（例如 1.7.1）

插件版本与 Kotlin 版本不匹配会导致难以理解的构建错误。

其他格式

JSON 最常用，但 kotlinx.serialization 还可以通过额外的构件支持更多格式：

kotlinx-serialization-json — JSON
kotlinx-serialization-cbor — CBOR 二进制格式
kotlinx-serialization-protobuf — Protocol Buffers

您只需添加所需格式对应的构件。

Groovy DSL 等价写法

如果您的项目使用 Groovy build.gradle 而不是 Kotlin DSL，配置方式如下。

// build.gradle (Groovy)
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.0.0'
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.0'
}

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1'
}

Json 入口

配置完成后，您可以使用 kotlinx.serialization.json 中的 Json 对象，作为编码和解码的主要入口。

import kotlinx.serialization.json.Json

val format = Json
// format.encodeToString(...) / format.decodeFromString(...)

最小可运行代码片段

下面是配置好插件和运行时库后，端到端运行所需的最小示例。

import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

@Serializable
data class City(val name: String, val population: Int)

fun main() {
    val city = City("Istanbul", 15000000)
    val json = Json.encodeToString(city)
    println(json)
}

多平台配置

在 Kotlin Multiplatform 项目中，将运行时库添加到 commonMain，这样所有目标平台都可以共享它。

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
        }
    }
}

常见配置错误

请注意以下常见问题：

忘记插件 — 您会遇到 Serializer has not been found
插件版本与 Kotlin 版本不匹配
添加了运行时库却没有添加插件（或反过来）
缺少 encodeToString 导入

快速检查

为什么 kotlinx.serialization 需要 Gradle 编译器插件？

回顾

您通过以下步骤完成了 kotlinx.serialization 的配置：

应用与 Kotlin 版本匹配的 kotlin("plugin.serialization") 插件
添加 kotlinx-serialization-json 运行时依赖项
使用 Json 对象作为入口

下一步，您将使用 @Serializable 标注模型类。

常见问题解答

「kotlinx.serialization 配置」课时是免费的吗？

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

「kotlinx.serialization 配置」这节课中我会学到什么？

添加插件你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

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

「kotlinx.serialization 配置」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 Kotlin Academy