序列化

最终更新: 2025/02/06

序列化(serialization) 是指将应用程序使用的数据转换为一种格式, 使它可以通过网络传输, 或保存到数据库或文件. 相应的, 反序列化(deserialization) 是指相反的过程, 从外部读取数据, 将它转换为运行时对象. 这两种功能结合到一起, 就是大多数应用程序与第三方交换数据时必不可少的部分.

有些序列化格式, 比如 JSON 和 protocol buffers 是非常通用的. 它们独立于编程语言和运行平台, 可以用来在各种现代语言编写的系统之间交换数据.

在 Kotlin 中, 数据序列化工具是一个单独的组件, kotlinx.serialization. 其中包含几个主要部分: org.jetbrains.kotlin.plugin.serialization Gradle plugin, 运行库, 以及编译器插件.

编译器插件, kotlinx-serialization-compiler-plugin 和 kotlinx-serialization-compiler-plugin-embeddable, 直接发布到 Maven Central. 第 2 个插件用来与 kotlin-compiler-embeddable artifact 配合使用, 对于脚本 artifact, 它是默认选项. Gradle 会把编译器插件添加为你的项目的编译器参数.

库

kotlinx.serialization 提供了一组库, 用于所有支持的平台 – JVM, JavaScript, Native – 而且支持很多序列化格式 – JSON, CBOR, protocol buffers, 以及其他格式. 关于所支持的序列化格式的完整列表, 请参见下文.

所有的 Kotlin 序列化库都属于 org.jetbrains.kotlinx: 组. 库名称以 kotlinx-serialization- 开头, 后缀对应于序列化格式. 比如:

  • org.jetbrains.kotlinx:kotlinx-serialization-json, 为 Kotlin 项目提供 JSON 序列化功能.

  • org.jetbrains.kotlinx:kotlinx-serialization-cbor, 提供 CBOR 序列化功能.

针对各编译平台的 artifact 会自动选择; 你不需要手动添加. 在 JVM, JS, Native, 和跨平台项目中, 可以使用相同的依赖项.

注意, kotlinx.serialization 库使用单独的版本结构, 与 Kotlin 本身的版本不同. 最新的发布版本请参见 GitHub 的版本列表.

格式

kotlinx.serialization 包括针对多种序列化格式的库:

注意, 除 JSON 序列化(kotlinx-serialization-json )之外, 其他所有库都处于实验状态, 也就是说, 它们的 API 可能会发生变化, 不另行通知.

此外还有社区维护的库, 支持更多序列化格式, 比如 YAML 或 Apache Avro. 关于可用的序列化格式, 详情请参见 kotlinx.serialization 文档.

示例: JSON 序列化

下面我们来看一看如何将 Kotlin 对象序列化为 JSON.

添加插件和依赖项

开始之前, 你需要配置你的构建脚本, 使你的项目能够使用 Kotlin 序列化工具:

  1. 应用 Kotlin 序列化 Gradle 插件 org.jetbrains.kotlin.plugin.serialization (在 Kotlin Gradle DSL 中是 kotlin("plugin.serialization")).

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

  2. 添加 JSON 序列化库的依赖项: org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3

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

现在, 可以在你的代码中使用序列化 API 了. API 所在的包是 kotlinx.serialization, 以及各个格式专用的子包, 比如 kotlinx.serialization.json.

序列化和反序列化 JSON

  1. 对一个类添加 @Serializable 注解, 使它可以被序列化.

    import kotlinx.serialization.Serializable

@Serializable
data class Data(val a: Int, val b: String)

  2. 调用函数 Json.encodeToString(), 序列化这个类的实例.

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

@Serializable
data class Data(val a: Int, val b: String)

fun main() {
  val json = Json.encodeToString(Data(42, "str"))
}

    结果, 你会得到一个 JSON 格式的字符串, 其中包含这个对象的状态: {"a": 42, "b": "str"}

    note

    也可以通过单次函数调用, 序列化对象的集合, 比如 List:

    val dataList = listOf(Data(42, "str"), Data(12, "test"))
val jsonList = Json.encodeToString(dataList)

  3. 使用 decodeFromString() 函数, 从 JSON 字符串中反序列化对象:

    import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.decodeFromString

@Serializable
data class Data(val a: Int, val b: String)

fun main() {
  val obj = Json.decodeFromString<Data>("""{"a":42, "b": "str"}""")
}

就是这样! 你已经成功的将对象序列化为 JSON 字符串, 然后将 JSON 字符串反序列化为对象.

下一步

关于 Kotlin 中的序列化, 更多详情请阅读 Kotlin 序列化指南.

你可以阅读以下资料, 学习 Kotlin 序列化的不同方面: