Kotlin Serialization：JSON、XML 数据处理最佳实践 – wiki词典

作者： /

Kotlin Serialization：JSON、XML 数据处理最佳实践

在现代应用程序开发中，数据序列化和反序列化是不可或缺的环节。无论是在客户端与服务器通信、本地数据存储还是处理配置文件时，我们都需要高效、可靠地将对象转换为可传输的格式（如 JSON、XML），反之亦然。Kotlin Serialization 是 JetBrains 官方推出的一个强大且灵活的库，旨在简化 Kotlin 对象与各种数据格式之间的转换。

本文将深入探讨 Kotlin Serialization 在处理 JSON 和 XML 数据时的最佳实践，包括其核心特性、设置、常见用例以及高级技巧。

1. 引言：Kotlin Serialization 简介

Kotlin Serialization 是一个多平台序列化库，它使用 Kotlin 编译器插件来生成序列化器。这意味着你不需要使用反射，从而带来了更好的性能和更小的包体积。它支持多种数据格式，其中 JSON 是最常用和内置支持的格式，而 XML 则可以通过社区或第三方库与 Kotlin 数据类良好集成。

核心优势：
* 类型安全： 利用 Kotlin 的类型系统，编译时检查确保数据结构匹配。
* 无需反射： 编译时生成序列化器，提升性能并减少运行时开销。
* 多平台支持： 适用于 JVM、JS、Native 等所有 Kotlin 平台。
* 扩展性： 易于扩展以支持新的数据格式或自定义序列化逻辑。
* 简洁的 API： 提供直观易用的 API，特别是与 Kotlin 数据类结合使用时。

2. 环境搭建

要使用 Kotlin Serialization，你需要在项目的 build.gradle.kts (或 build.gradle) 文件中添加必要的插件和依赖。

build.gradle.kts 配置示例：

“`kotlin
plugins {
kotlin(“jvm”) version “1.9.23” // 或 kotlin(“multiplatform”)
kotlin(“plugin.serialization”) version “1.9.23” // 必须添加此插件
}

repositories {
mavenCentral()
}

dependencies {
// JSON 格式支持
implementation(“org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3”)

// XML 格式支持 (通常需要第三方库，例如 kotlinx-serialization-xml 或 clikt/lib-xml-serialization)
// 这里以 kotlinx-serialization-xml 为例，但请注意其成熟度与官方 JSON 库有所不同
implementation("io.github.pdvrieze.xmlutil:core:0.87.1") // XML 核心库
implementation("io.github.pdvrieze.xmlutil:serialization:0.87.1") // XML Serialization 适配器
// 或者其他 XML 库，如 Simple XML Serialization (com.github.pozo:kotlin-poet-simplexml:...)

}
“`

3. JSON 数据处理最佳实践

JSON 是最流行的数据交换格式之一。Kotlin Serialization 对 JSON 提供了原生且功能强大的支持。

3.1 基本使用

使用 @Serializable 注解标记你的数据类，然后使用 Json 对象进行序列化和反序列化。

“`kotlin
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

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

fun main() {
val user = User(“Alice”, 30, “[email protected]”)
val jsonString = Json.encodeToString(user)
println(“Serialized JSON: $jsonString”) // {“name”:”Alice”,”age”:30,”email”:”[email protected]”}

val decodedUser = Json.decodeFromString<User>(jsonString)
println("Deserialized User: $decodedUser") // User(name=Alice, age=30, [email protected])

// 处理缺失的可空字段
val jsonWithoutEmail = """{"name":"Bob","age":25}"""
val userWithoutEmail = Json.decodeFromString<User>(jsonWithoutEmail)
println("User without email: $userWithoutEmail") // User(name=Bob, age=25, email=null)

}
“`

3.2 配置 Json 实例

Json 对象提供了多种配置选项，可以根据你的需求定制序列化行为。始终建议创建一个自定义的 Json 实例，而不是使用默认的 Json 单例，以便更好地控制。

“`kotlin
import kotlinx.serialization.json.Json

val customJson = Json {
prettyPrint = true // 格式化输出，方便阅读
ignoreUnknownKeys = true // 反序列化时忽略 JSON 中存在但数据类中不存在的字段
explicitNulls = false // 序列化时，如果字段为 null，则不输出该字段
encodeDefaults = true // 序列化时，即使字段是默认值也输出
coerceInputValues = true // 尝试将不匹配的枚举值强制转换为 null 或默认值
}

// 使用 customJson 进行序列化和反序列化
// val jsonString = customJson.encodeToString(user)
// val decodedUser = customJson.decodeFromString(jsonString)
“`

最佳实践：
* ignoreUnknownKeys = true： 在处理来自外部服务（如 REST API）的数据时非常有用，可以让你在不破坏旧版本客户端的情况下向 JSON 响应添加新字段。
* prettyPrint = true： 仅用于调试或需要人类可读输出的场景，生产环境应设为 false 以节省带宽。
* explicitNulls = false： 当后端期望缺少字段而不是 null 值时非常有用。
* encodeDefaults = false： 可以减少 JSON 输出的冗余，仅发送非默认值。但需确保接收方能正确处理缺失的默认值。

3.3 自定义序列化器

有时，你需要对特定类型进行非标准的序列化或反序列化。可以通过实现 KSerializer 接口来创建自定义序列化器。

示例：序列化 java.time.LocalDate

“`kotlin
import kotlinx.serialization.KSerializer
import kotlinx.serialization.descriptors.PrimitiveKind
import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
import kotlinx.serialization.descriptors.SerialDescriptor
import kotlinx.serialization.encoding.Decoder
import kotlinx.serialization.encoding.Encoder
import kotlinx.serialization.Serializable
import java.time.LocalDate
import java.time.format.DateTimeFormatter

object LocalDateSerializer : KSerializer {
private val formatter = DateTimeFormatter.ISO_LOCAL_DATE // “YYYY-MM-DD”

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

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

override fun deserialize(decoder: Decoder): LocalDate {
    return LocalDate.parse(decoder.decodeString(), formatter)
}

}

@Serializable
data class Event(
val name: String,
@Serializable(with = LocalDateSerializer::class)
val date: LocalDate
)

fun main() {
val event = Event(“Meeting”, LocalDate.of(2026, 1, 6))
val jsonString = Json.encodeToString(event)
println(jsonString) // {“name”:”Meeting”,”date”:”2026-01-06″}

val decodedEvent = Json.decodeFromString<Event>(jsonString)
println(decodedEvent) // Event(name=Meeting, date=2026-01-06)

}
“`

最佳实践：
* 通用性： 对于常用的自定义类型（如日期、货币），可以将其序列化器定义为单例 object，并提供一个通用的 Json 配置。
* 注解使用： 使用 @Serializable(with = YourSerializer::class) 注解将自定义序列化器应用于特定属性或整个类。

3.4 处理多态性 (Polymorphism)

当你的数据结构中包含接口或抽象类，并且在运行时需要根据具体实现类进行序列化或反序列化时，就需要处理多态性。

“`kotlin
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.modules.SerializersModule
import kotlinx.serialization.modules.polymorphic
import kotlinx.serialization.modules.subclass

@Serializable
sealed class Shape {
abstract val id: String
}

@Serializable
data class Circle(override val id: String, val radius: Double) : Shape()

@Serializable
data class Rectangle(override val id: String, val width: Double, val height: Double) : Shape()

val shapeModule = SerializersModule {
polymorphic(Shape::class) {
subclass(Circle::class)
subclass(Rectangle::class)
}
}

val polymorphicJson = Json {
serializersModule = shapeModule
prettyPrint = true
}

fun main() {
val shapes: List = listOf(
Circle(“c1”, 10.0),
Rectangle(“r1”, 20.0, 30.0)
)

val jsonString = polymorphicJson.encodeToString(shapes)
println("Serialized Shapes:\n$jsonString")
/*
[
  {
    "id": "c1",
    "radius": 10.0,
    "type": "Circle"
  },
  {
    "id": "r1",
    "width": 20.0,
    "height": 30.0,
    "type": "Rectangle"
  }
]
*/

val decodedShapes = polymorphicJson.decodeFromString<List<Shape>>(jsonString)
println("Deserialized Shapes: $decodedShapes")

}
“`

最佳实践：
* sealed class： 对于受限的多态性场景，使用 sealed class (或 sealed interface) 是最佳选择，因为编译器可以确保所有子类都已注册。
* SerializersModule： 将多态性配置集中在一个 SerializersModule 中，并在 Json 实例中引用它，保持代码整洁。
* classDiscriminator： 默认情况下，Kotlin Serialization 会添加一个名为 type 的字段来区分类型。你可以通过 Json { classDiscriminator = "yourTypeField" } 来更改此字段的名称。

3.5 忽略、重命名字段和默认值

  • 忽略字段： 使用 @Transient 注解可以告诉序列化器忽略该属性。
  • 重命名字段： 使用 @SerialName 注解可以指定 JSON 字段的名称，这在 Kotlin 属性名与 JSON 字段名不一致时非常有用。
  • 默认值： 在数据类中使用默认参数值，反序列化时如果 JSON 中缺少该字段，将使用默认值。

“`kotlin
import kotlinx.serialization.Serializable
import kotlinx.serialization.Transient
import kotlinx.serialization.SerialName
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString

@Serializable
data class Product(
val id: String,
@SerialName(“product_name”) // JSON 中是 product_name，Kotlin 中是 name
val name: String,
val price: Double,
val description: String = “No description provided.”, // 默认值
@Transient // 忽略此字段
val internalId: String = java.util.UUID.randomUUID().toString()
)

fun main() {
val product = Product(“p001”, “Laptop”, 1200.0)
val jsonString = Json.encodeToString(product)
println(jsonString) // {“id”:”p001″,”product_name”:”Laptop”,”price”:1200.0,”description”:”No description provided.”}
// internalId 被忽略

val jsonPartial = """{"id":"p002","product_name":"Mouse","price":25.0}"""
val decodedProduct = Json.decodeFromString<Product>(jsonPartial)
println(decodedProduct) // Product(id=p002, name=Mouse, price=25.0, description=No description provided., internalId=...)
// description 使用了默认值

}
“`

3.6 错误处理

默认情况下，如果反序列化时遇到不匹配的类型或格式错误，Kotlin Serialization 会抛出 SerializationException。可以通过 Json 配置来调整行为。

  • ignoreUnknownKeys = true： 忽略 JSON 中多余的字段。
  • coerceInputValues = true： 尝试将不匹配的枚举值或数字转换为 null 或默认值，而不是抛出异常。
  • isLenient = true： 允许 JSON 中存在不规范的格式，例如未用引号引起来的字符串等（不推荐在生产环境使用）。

对于更细粒度的错误处理，你可能需要在解析前后进行手动验证，或者在自定义序列化器中捕获和处理特定异常。

4. XML 数据处理

Kotlin Serialization 官方库目前没有直接内置 XML 格式的支持。然而，这并不意味着你不能在 Kotlin 项目中高效处理 XML。通常有两种方法：

  1. 使用第三方 kotlinx-serialization 兼容库： 例如 kotlinx-serialization-xml (一个社区项目) 或 kotlin-xmlutil。它们通常提供一个 Xml 格式对象，其用法与 Json 类似。
  2. 使用传统的 XML 解析库配合 Kotlin 数据类： 例如 javax.xml.parsers (DOM/SAX)、jackson-dataformat-xml (如果使用 Jackson) 或 SimpleXML。然后手动映射到 Kotlin 数据类。

我们以 kotlin-xmlutil (即 io.github.pdvrieze.xmlutil:serialization) 为例来演示其最佳实践，因为它试图遵循 kotlinx-serialization 的 API 风格。

4.1 使用 kotlin-xmlutil

首先确保你的 build.gradle.kts 包含了 kotlin-xmlutil 的依赖。

“`kotlin
import kotlinx.serialization.Serializable
import nl.adaptivity.xmlutil.serialization.XML
import nl.adaptivity.xmlutil.QName // 用于命名空间

@Serializable
data class Book(
val title: String,
val author: String,
val year: Int,
val isbn: String? = null // 可选字段
)

@Serializable
data class Library(
val name: String,
val location: String,
val books: List // 列表元素
)

fun main() {
val book1 = Book(“The Hitchhiker’s Guide to the Galaxy”, “Douglas Adams”, 1979)
val book2 = Book(“1984”, “George Orwell”, 1949, “978-0451524935”)
val library = Library(“City Library”, “Main Street”, listOf(book1, book2))

val xmlPretty = XML {
    indent = 4 // 格式化输出
    // 如果需要处理命名空间，可以在这里配置
    // addNamespace("http://www.example.com/books", "bk")
}

val xmlString = xmlPretty.encodeToString(library)
println("Serialized XML:\n$xmlString")
/* 示例输出 (可能略有不同，取决于库版本和配置):
<Library name="City Library" location="Main Street">
    <books>
        <Book title="The Hitchhiker's Guide to the Galaxy" author="Douglas Adams" year="1979"/>
        <Book title="1984" author="George Orwell" year="1949" isbn="978-0451524935"/>
    </books>
</Library>
*/

val decodedLibrary = xmlPretty.decodeFromString<Library>(xmlString)
println("Deserialized Library: $decodedLibrary")

}
“`

XML 特有注解和配置：

kotlin-xmlutil 提供了 @XmlSerialName, @XmlChildrenName, @XmlAttribute, @XmlText, @XmlElement 等注解来精细控制 XML 元素的名称、是否作为属性、子元素或文本内容。

“`kotlin
import kotlinx.serialization.Serializable
import nl.adaptivity.xmlutil.serialization.XML
import nl.adaptivity.xmlutil.serialization.XmlSerialName
import nl.adaptivity.xmlutil.serialization.XmlAttribute
import nl.adaptivity.xmlutil.serialization.XmlText

@Serializable
@XmlSerialName(“item”, “”, “”) // 定义根元素名为 item
data class Item(
@XmlAttribute(name = “id”) // id 作为属性
val itemId: String,
@XmlSerialName(“name”, “”, “”) // name 作为子元素
val itemName: String,
@XmlText // value 作为元素的文本内容
val value: String
)

fun main() {
val item = Item(“A123”, “Product A”, “Some description text.”)
val xml = XML { indent = 2 }
val xmlString = xml.encodeToString(item)
println(“Custom XML:\n$xmlString”)
/

Product A
Some description text.

/
}
“`

最佳实践：
* 选择合适的库： 根据项目需求和对 XML 复杂度的要求选择库。如果 XML 结构相对简单，kotlin-xmlutil 是一个不错的选择，因为它与 kotlinx-serialization 生态系统集成良好。对于更复杂的企业级 XML，可能需要考虑 Jackson XML 或 JAXB 的 Kotlin 适配。
* 命名空间处理： XML 常常涉及命名空间。确保你选择的库能够灵活处理命名空间的声明、前缀和解析。kotlin-xmlutil 在 XML 配置中提供了命名空间相关的选项。
* 属性 vs 元素： XML 的灵活性在于数据可以存储为属性或子元素。使用 @XmlAttribute 和 @XmlElement (或 XmlSerialName 配合 XmlChildrenName) 来精确映射。
* 根元素： 注意 XML 通常有一个根元素。在序列化单个对象时，可能需要用 @XmlSerialName 注解来指定其作为根元素的名称。

4.2 传统 XML 解析库 (简述)

如果 kotlinx-serialization 生态中的 XML 库不能满足你的需求，你可以考虑其他成熟的 JVM 库：

  • Jackson-dataformat-xml： 如果你已经在项目中使用 Jackson JSON 库，那么添加 jackson-dataformat-xml 是一个自然的选择。它允许你使用相同的注解（如 @JsonProperty, @JsonCreator，虽然 Jackson 也有自己的 XML 注解）来序列化/反序列化 Kotlin 数据类到 XML。
  • JAXB (Jakarta XML Binding)： Java EE 标准，通过注解将 Java 对象映射到 XML。虽然它更偏向 Java 风格，但 Kotlin 可以很好地与其互操作。
  • DOM/SAX： 最底层的 Java API，适用于需要完全手动控制解析过程的复杂场景，但开发效率较低。

5. 性能与安全性考虑

5.1 性能

  • 避免不必要的序列化/反序列化： 尽量在需要时才进行转换。
  • 自定义 Json 实例： 禁用 prettyPrint、encodeDefaults 和 explicitNulls 可以减少生成的 JSON 字符串大小，从而提高网络传输和解析速度。
  • 使用 ignoreUnknownKeys = true： 尽管它在一定程度上增加了反序列化时的查找开销，但对于处理不稳定或不断演变的 API 来说，其带来的健壮性收益通常大于性能损失。
  • 针对大文件或流： Kotlin Serialization 可以与 kotlinx.serialization.json.Json.decodeFromStream 和 encodeToStream 配合使用，避免一次性将整个数据加载到内存中，尤其适用于处理大文件。

5.2 安全性

  • 信任输入： 永远不要完全信任来自外部的序列化数据。进行反序列化后，务必对数据进行严格的业务逻辑校验。
  • 拒绝未知字段： 默认情况下，如果 JSON 包含数据类中没有的字段，反序列化会失败。这是默认的安全行为。如果你需要忽略未知字段，请明确设置 ignoreUnknownKeys = true。
  • 防止反序列化漏洞： 某些序列化库（尤其是基于反射的）可能存在反序列化漏洞，允许攻击者通过恶意构造的数据执行任意代码。由于 Kotlin Serialization 是编译时生成序列化器且不依赖反射，这大大降低了此类风险，但仍然需要警惕其他潜在的安全问题，例如对枚举值的强制转换 (coerceInputValues) 可能会隐藏一些数据不一致的问题。

6. 总结

Kotlin Serialization 是一个为 Kotlin 开发者量身定制的现代化序列化库，特别是在处理 JSON 数据时展现出无与伦比的便利性和类型安全性。通过理解其核心概念，合理配置 Json 实例，以及利用自定义序列化器和多态性支持，可以构建健壮、高效的数据处理管道。

尽管官方对 XML 的支持不如 JSON 那么直接，但通过集成 kotlinx-serialization 兼容库（如 kotlin-xmlutil）或传统的 XML 解析方案，我们仍然可以在 Kotlin 项目中优雅地处理 XML 数据。

遵循本文所述的最佳实践，你将能够充分利用 Kotlin Serialization 的强大功能，提升开发效率，并确保应用程序中数据交互的可靠性与安全性。

滚动至顶部