当前位置：首页 > news >正文

Kotlinx.serialization终极指南：如何创建自定义序列化格式

news 2026/5/12 7:14:25

Kotlinx.serialization终极指南：如何创建自定义序列化格式

【免费下载链接】kotlinx.serializationKotlin multiplatform / multi-format serialization项目地址: https://gitcode.com/gh_mirrors/ko/kotlinx.serialization

欢迎来到Kotlinx.serialization自定义序列化格式的终极指南！🚀 如果你正在寻找超越JSON、Protobuf和CBOR等内置格式的解决方案，想要为特定需求创建定制化的序列化格式，那么这篇文章正是为你准备的。

Kotlinx.serialization是JetBrains官方推出的Kotlin多平台/多格式序列化库，它提供了强大的扩展性，让你能够轻松创建自己的序列化格式。无论你需要二进制格式、文本格式还是其他特殊格式，这个指南都将带你一步步掌握创建自定义序列化格式的核心技巧。

📋 为什么需要自定义序列化格式？

在实际开发中，你可能会遇到以下场景：

需要与特定协议或遗留系统集成
追求极致的性能优化
处理特殊的数据结构
需要特定的数据压缩算法

Kotlinx.serialization通过提供AbstractEncoder和AbstractDecoder基类，让创建自定义格式变得异常简单。

🔧 核心概念与架构

要创建自定义格式，你需要理解以下几个核心概念：

1. SerialFormat接口

在core/commonMain/src/kotlinx/serialization/SerialFormat.kt中定义了序列化格式的基本接口：

public interface SerialFormat { public val serializersModule: SerializersModule }

2. 编码器与解码器

AbstractEncoder: 编码器的骨架实现，位于core/commonMain/src/kotlinx/serialization/encoding/AbstractEncoder.kt
AbstractDecoder: 解码器的骨架实现，位于core/commonMain/src/kotlinx/serialization/encoding/AbstractDecoder.kt

3. 序列化描述符

通过SerialDescriptor提供类型信息，帮助编码器/解码器理解数据结构。

🛠️ 创建自定义二进制格式的完整示例

让我们通过一个实际的例子来学习如何创建自定义二进制格式。我们将创建一个简单的二进制格式，用于存储项目数据。

步骤1：定义数据模型

首先，创建一个简单的数据类：

@Serializable data class Project( val name: String, val language: String, val stars: Int, val isActive: Boolean )

步骤2：实现自定义编码器

创建BinaryProjectEncoder类，继承自AbstractEncoder：

@ExperimentalSerializationApi class BinaryProjectEncoder(val output: DataOutput) : AbstractEncoder() { override val serializersModule: SerializersModule = EmptySerializersModule() override fun encodeBoolean(value: Boolean) = output.writeByte(if (value) 1 else 0) override fun encodeByte(value: Byte) = output.writeByte(value.toInt()) override fun encodeInt(value: Int) = output.writeInt(value) override fun encodeString(value: String) { val bytes = value.encodeToByteArray() encodeInt(bytes.size) output.write(bytes) } override fun encodeEnum(enumDescriptor: SerialDescriptor, index: Int) = output.writeInt(index) override fun beginCollection(descriptor: SerialDescriptor, collectionSize: Int): CompositeEncoder { encodeInt(collectionSize) return this } }

步骤3：实现自定义解码器

创建BinaryProjectDecoder类，继承自AbstractDecoder：

@ExperimentalSerializationApi class BinaryProjectDecoder(val input: DataInput) : AbstractDecoder() { private var elementIndex = 0 private var elementsCount = 0 override val serializersModule: SerializersModule = EmptySerializersModule() override fun decodeBoolean(): Boolean = input.readByte().toInt() != 0 override fun decodeByte(): Byte = input.readByte() override fun decodeInt(): Int = input.readInt() override fun decodeString(): String { val size = decodeInt() val bytes = ByteArray(size) input.readFully(bytes) return bytes.decodeToString() } override fun decodeEnum(enumDescriptor: SerialDescriptor): Int = input.readInt() override fun decodeElementIndex(descriptor: SerialDescriptor): Int { if (elementIndex == elementsCount) return CompositeDecoder.DECODE_DONE return elementIndex++ } override fun decodeCollectionSize(descriptor: SerialDescriptor): Int = decodeInt().also { elementsCount = it } }

步骤4：创建完整的格式类

现在，让我们创建完整的BinaryProjectFormat类：

@ExperimentalSerializationApi class BinaryProjectFormat : BinaryFormat { override val serializersModule: SerializersModule = EmptySerializersModule() override fun <T> encodeToByteArray( serializer: SerializationStrategy<T>, value: T ): ByteArray { val output = ByteArrayOutputStream() val encoder = BinaryProjectEncoder(DataOutputStream(output)) encoder.encodeSerializableValue(serializer, value) return output.toByteArray() } override fun <T> decodeFromByteArray( deserializer: DeserializationStrategy<T>, bytes: ByteArray ): T { val input = ByteArrayInputStream(bytes) val decoder = BinaryProjectDecoder(DataInputStream(input)) return decoder.decodeSerializableValue(deserializer) } }

步骤5：使用自定义格式

现在你可以像使用内置格式一样使用你的自定义格式：

fun main() { val format = BinaryProjectFormat() val project = Project("kotlinx.serialization", "Kotlin", 8500, true) // 序列化 val bytes = format.encodeToByteArray(project) println("序列化后的字节数组大小: ${bytes.size} bytes") // 反序列化 val deserialized = format.decodeFromByteArray<Project>(bytes) println("反序列化结果: $deserialized") }

🎯 高级技巧与最佳实践

1. 处理嵌套对象

对于嵌套对象，你需要正确实现beginStructure和endStructure方法：

override fun beginStructure(descriptor: SerialDescriptor): CompositeEncoder { // 记录当前结构信息 return this } override fun endStructure(descriptor: SerialDescriptor) { // 清理结构信息 }

2. 支持可选字段

通过实现encodeNull和decodeNotNullMark方法来支持可空字段：

override fun encodeNull() { output.writeByte(0) // 0表示null } override fun encodeNotNullMark() { output.writeByte(1) // 1表示非null } override fun decodeNotNullMark(): Boolean = input.readByte().toInt() != 0

3. 性能优化技巧

缓冲区重用: 重用ByteArrayOutputStream以减少内存分配
批量写入: 对于数组和集合，考虑批量写入以提高性能
压缩算法: 对于大型数据，集成压缩算法

4. 错误处理

确保你的格式能够正确处理错误情况：

override fun <T> decodeFromByteArray( deserializer: DeserializationStrategy<T>, bytes: ByteArray ): T { return try { val input = ByteArrayInputStream(bytes) val decoder = BinaryProjectDecoder(DataInputStream(input)) decoder.decodeSerializableValue(deserializer) } catch (e: IOException) { throw SerializationException("Failed to decode binary data", e) } catch (e: IllegalArgumentException) { throw SerializationException("Invalid binary format", e) } }

📊 实际应用场景

场景1：游戏存档格式

创建专门用于游戏存档的二进制格式，支持快速读写和压缩：

class GameSaveFormat : BinaryFormat { // 实现特定的游戏数据编码逻辑 // 支持压缩、加密等功能 }

场景2：网络协议序列化

为自定义网络协议创建高效的序列化格式：

class NetworkProtocolFormat : BinaryFormat { // 实现网络协议特定的编码规则 // 支持数据包分片、校验和等 }

场景3：配置文件格式

创建人类可读但结构化的配置文件格式：

class ConfigFileFormat : StringFormat { // 实现类似INI或TOML的格式 // 支持注释、节、键值对等 }

🔍 调试与测试

1. 使用Hex转储调试

Kotlinx.serialization提供了内置的Hex转换工具：

fun debugBinaryData(bytes: ByteArray) { val hex = bytes.joinToString("") { "%02x".format(it) } println("Hex转储: $hex") }

2. 编写单元测试

确保你的格式在各种情况下都能正常工作：

@Test fun testCustomFormat() { val format = BinaryProjectFormat() val testData = Project("Test", "Kotlin", 100, true) // 序列化测试 val bytes = format.encodeToByteArray(testData) assertTrue(bytes.isNotEmpty()) // 反序列化测试 val result = format.decodeFromByteArray<Project>(bytes) assertEquals(testData, result) // 边界条件测试 val emptyProject = Project("", "", 0, false) val emptyBytes = format.encodeToByteArray(emptyProject) val emptyResult = format.decodeFromByteArray<Project>(emptyBytes) assertEquals(emptyProject, emptyResult) }