序列化(serialization)

最终更新: 2024/03/21

序列化(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
Protocol buffers: kotlinx-serialization-protobuf
CBOR: kotlinx-serialization-cbor
Properties: kotlinx-serialization-properties
HOCON: kotlinx-serialization-hocon (只限于 JVM 平台)

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

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

示例: JSON 序列化

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

添加插件和依赖项

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

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

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

 plugins {
     id 'org.jetbrains.kotlin.jvm' version '1.9.23'
     id 'org.jetbrains.kotlin.plugin.serialization' version '1.9.23'  
 }

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

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

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

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

序列化和反序列化 JSON

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

import kotlinx.serialization.Serializable

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

调用函数 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"}

也可以通过单次函数调用, 序列化对象的集合, 比如 List:
val dataList = listOf(Data(42, "str"), Data(12, "test"))
val jsonList = Json.encodeToString(dataList)

使用 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 序列化的不同方面: