01.Kotlin Serialization - 基础用法

📖 前言

在现代软件开发中，数据序列化是将对象转换为可存储或传输格式的关键技术。Kotlin Serialization 是 JetBrains 官方推出的序列化框架，提供类型安全、高性能的序列化解决方案。

本文带你初探 Kotlin Serialization，了解什么是可序列化类型，并学会基础的序列化操作。

说明：JSON 作为应用最广泛的数据传输格式，是本系列教程的主要讲解对象。

🔧 项目配置

Gradle 配置（Kotlin DSL）

在 build.gradle.kts 文件中添加必要的插件和依赖：

kotlin 复制代码

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

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

Gradle 配置（Groovy DSL）

如果使用传统的 build.gradle 文件：

groovy 复制代码

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

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

📝 可序列化类型

只有可序列化的类型才能进行序列化和反序列化操作。那么，哪些类型是可序列化的呢？

自定义类型 ：添加了 @Serializable 注解的类
内置类型：Kotlin Serialization 内置支持的类型

📦 内置支持的类型

基础类型（Primitives）

数值类型：Byte、Short、Int、Long、Float、Double
其他基础类型：Boolean、Char、String
枚举类：所有枚举类都自动支持序列化（无需 @Serializable 注解）

集合类型（Collections）

列表：List<T>、MutableList<T>、ArrayList<T>
集合：Set<T>、MutableSet<T>、HashSet<T>、LinkedHashSet<T>
映射：Map<K,V>、MutableMap<K,V>、HashMap<K,V>、LinkedHashMap<K,V>

数组类型（Arrays）

泛型数组：Array<T>
基础类型数组：ByteArray、ShortArray、IntArray、LongArray、FloatArray、DoubleArray、BooleanArray、CharArray

复合类型（Composites）

元组：Pair<A,B>、Triple<A,B,C>
特殊类型：Unit（序列化为空对象 {}）
时间类型：Duration（自 Kotlin 1.7.20 起）

特殊类型

Nothing：用于参数化多态基类等场景

🚀 基础示例

kotlin 复制代码

@Serializable
data class User(
    val id: Int,
    val name: String,
    val email: String?,
)

fun main() {
    val user = User(1, "张三", "zhang@example.com")
    
    // 序列化：对象 -> JSON 字符串
    val jsonString = Json.encodeToString(user)
    println(jsonString) 
    // 输出：{"id":1,"name":"张三","email":"zhang@example.com"}
    
    // 反序列化：JSON 字符串 -> 对象
    val deserializedUser = Json.decodeFromString<User>(jsonString)
    println(deserializedUser)
    // 输出：User(id=1, name=张三, email=zhang@example.com)
}

📚 敬请期待

掌握了基础用法后，推荐继续深入学习：

📖 《02-序列化规则与配置详解》 - 深入了解序列化的各种规则和配置：

属性配置规则（必要属性、可选属性、忽略属性等）
JSON 配置选项和高级特性
常见问题和最佳实践