Kotlin Serialization JSON解析指南

1. 添加依赖

在 build.gradle.kts 中配置：

// 项目级 build.gradle.kts
plugins {
    kotlin("jvm") version "1.9.0"
    kotlin("plugin.serialization") version "1.9.0" // 应用序列化插件
}

// 模块级 build.gradle.kts
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
}

2. 定义可序列化数据类

使用 @Serializable 注解标记数据类，支持 Kotlin 不可变属性和空安全：

import kotlinx.serialization.Serializable

@Serializable
data class User(
    val name: String,
    val age: Int = 18, // 默认值
    @SerialName("email_address") val email: String? // 自定义 JSON 键名
)

3. 序列化与反序列化

使用 Json 对象进行转换，支持配置选项：

import kotlinx.serialization.encodeToString
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.json.Json

fun main() {
    val json = Json {
        ignoreUnknownKeys = true // 忽略未知字段
        coerceInputValues = true // 使用默认值处理缺失字段
        explicitNulls = false // 不序列化 null 值
    }

    // 序列化为 JSON 字符串
    val user = User("Alice", email = "alice@example.com")
    val jsonString = json.encodeToString(user)
    println(jsonString) // {"name":"Alice","email_address":"alice@example.com"}

    // 反序列化回对象
    val jsonInput = """{"name":"Bob","email_address":null}"""
    val decodedUser = json.decodeFromString<User>(jsonInput)
    println(decodedUser) // User(name=Bob, age=18, email=null)
}

4. 处理复杂场景

自定义序列化器

针对特殊类型（如日期），实现 KSerializer：

import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
import java.text.SimpleDateFormat
import java.util.Date

object DateSerializer : KSerializer<Date> {
    private val format = SimpleDateFormat("yyyy-MM-dd")

    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("Date", PrimitiveKind.STRING)

    override fun serialize(encoder: Encoder, value: Date) {
        encoder.encodeString(format.format(value))
    }

    override fun deserialize(decoder: Decoder): Date {
        return format.parse(decoder.decodeString()) ?: throw SerializationException("Invalid date")
    }
}

@Serializable
data class Event(
    val name: String,
    @Serializable(with = DateSerializer::class) val date: Date
)

多态序列化

处理继承类时，使用 @Polymorphic：

@Serializable
abstract class Response

@Serializable
@SerialName("success")
data class SuccessResponse(val data: String) : Response()

@Serializable
@SerialName("error")
data class ErrorResponse(val message: String) : Response()

// 序列化配置
val json = Json {
    classDiscriminator = "type"
    polymorphicDefault = Response.serializer()
}

5. 常见问题处理

• 字段名映射：使用 @SerialName("json_key") 注解。
• 默认值与空安全：配置 coerceInputValues = true 允许使用默认值填充缺失字段。
• 混淆配置：在 ProGuard 中添加规则保持序列化类：

  -keep class com.example.model.** { *; }
  

优势总结

• 轻量高效：无需反射，编译时生成序列化器。
• Kotlin 原生支持：完美适配数据类、默认参数、空安全。
• 灵活配置：通过 Json {} 配置多项策略，适应不同 JSON 结构。

通过以上步骤，可快速在 Kotlin 项目中集成 JSON 序列化功能，兼顾开发效率与运行时性能。更多细节参考 官方文档。