Kotlin 的 Serialization (kotlinx)：完整指南及示例

什么是 kotlinx.serialization，为什么需要它？

kotlinx.serialization 是 JetBrains 官方提供的用于在 Kotlin 中进行数据序列化和反序列化的库。它提供了一种强大、类型安全且跨平台的方式，将 Kotlin 对象转换为各种格式（JSON、Protobuf、CBOR、YAML 等）以及反向转换。

使用此库的主要原因：

• 跨平台： 可在 JVM、JS、Native（iOS、Android、Desktop）上运行。
• 类型安全： 序列化在编译阶段进行检查，从而消除运行时错误。
• 性能： 仅在必要时使用反射（通过编译器插件）。
• 灵活性： 支持自定义序列化器、多态性、可选字段等更多功能。
• 与 Kotlin 集成： 充分利用语言特性（data class、sealed class、null safety）。

安装与配置

要使用 kotlinx.serialization，您需要在项目中添加编译器插件和依赖项。

1. 添加插件 (build.gradle.kts)：

plugins {    kotlin("jvm") version "1.9.0" // 或您的 Kotlin 版本    kotlin("plugin.serialization") version "1.9.0"}

2. 添加依赖项：

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

3. 对于 Maven (pom.xml)：

<plugin>    <groupId>org.jetbrains.kotlin</groupId>    <artifactId>kotlin-maven-plugin</artifactId>    <version>1.9.0</version>    <configuration>        <pluginOptions>            <option>plugin:org.jetbrains.kotlin.plugin.serialization</option>        </pluginOptions>    </configuration></plugin>

<dependency>    <groupId>org.jetbrains.kotlinx</groupId>    <artifactId>kotlinx-serialization-json</artifactId>    <version>1.6.2</version></dependency>

快速入门：第一个示例

import kotlinx.serialization.Serializableimport kotlinx.serialization.json.Jsonimport kotlinx.serialization.encodeToStringimport kotlinx.serialization.decodeFromString

// 1. 定义可序列化的类@Serializabledata class User(val name: String, val age: Int, val email: String? = null)

fun main() {    // 2. 创建对象    val user = User("Alice", 30, "alice@example.com")

    // 3. 序列化为 JSON    val jsonString = Json.encodeToString(user)    println("序列化后的 JSON: $jsonString")

    // 4. 反序列化回来    val decodedUser = Json.decodeFromString<User>(jsonString)    println("反序列化后的对象: $decodedUser")}

输出：

序列化后的 JSON: {"name":"Alice","age":30,"email":"alice@example.com"}反序列化后的对象: User(name=Alice, age=30, email=alice@example.com)

主要方法和函数 (8+)

1. Json.encodeToString()

功能： 将 Kotlin 对象序列化为 JSON 字符串。

参数：

• value (T) — 要序列化的对象。
• serializer (Serializer<T>?) — 可选的自定义序列化器。

val user = User("Bob", 25)val json = Json.encodeToString(user)println(json) // {"name":"Bob","age":25}

2. Json.decodeFromString()

功能： 将 JSON 字符串反序列化为 Kotlin 对象。

参数：

• string (String) — JSON 字符串。
• des