序列化

序列化是将应用程序使用的数据转换为可以通过网络传输或存储在数据库或文件中的格式的过程。反之，反序列化是从外部源读取数据并将其转换为运行时对象的相反过程。这两者结合在一起，对于大多数与第三方交换数据的应用程序都至关重要。

一些数据序列化格式，例如 JSON 和 protocol buffers 特别常见。由于它们与语言无关且平台无关，因此可以在使用任何现代语言编写的系统之间进行数据交换。

在 Kotlin 中，数据序列化工具包含在一个独立的组件中：kotlinx.serialization。它由几个部分组成：org.jetbrains.kotlin.plugin.serialization Gradle 插件、运行时库以及编译器插件。

编译器插件 kotlinx-serialization-compiler-plugin 和 kotlinx-serialization-compiler-plugin-embeddable 直接发布到 Maven Central。第二个插件专为配合 kotlin-compiler-embeddable 构件使用而设计，这是脚本构件的默认选项。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 序列化。

平台特定的构件会被自动处理；您不需要手动添加它们。在 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 序列化工具：

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

   KotlinGroovy

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

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

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

   KotlinGroovy

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

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

现在您已经准备好在代码中使用序列化 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"}

   您还可以在单次调用中序列化对象集合，例如列表：

   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 字符串，并将其反序列化回对象。

下一步

有关 Kotlin 中序列化的更多信息，请参阅 Kotlin 序列化指南。

您可以通过以下资源探索 Kotlin 序列化的不同方面：

• 详细了解 Kotlin 序列化及其核心概念
• 探索 Kotlin 内置的可序列化类
• 更详细地了解序列化器并学习如何创建自定义序列化器
• 了解 Kotlin 如何处理多态序列化
• 了解处理 Kotlin 序列化的各种 JSON 功能
• 详细了解 Kotlin 支持的实验性序列化格式