自定义序列化格式
JSON 目前是 Kotlin 序列化中唯一稳定的格式。 Kotlin 序列化还为 CBOR 和 ProtoBuf 二进制格式提供了实验性支持,此外还提供了将类表示为以 String 为键的扁平 Map 的 Properties 格式。
这些实验性格式实现已达到生产质量,但未来的版本可能会对其默认序列化行为进行更改。 它们也可能存在特定于格式的局限性,或者在表示 Kotlin 数据的方式上存在限制。
如果这些格式都不符合你的用例,你可以创建自定义格式来控制值和结构的编码与解码方式。
创建自定义格式
要为 Kotlin 序列化创建自定义格式,请实现 Encoder 和 Decoder 接口。 序列化器使用这些实现来编码和解码值。
在编码或解码结构化值(例如类和集合)时,序列化器会调用这些实现上的 beginStructure() 函数。 该函数返回一个 CompositeEncoder 或 CompositeDecoder 接口,其中包含用于编码或解码每个属性或元素的函数。
虽然 Encoder 和 Decoder 接口功能十分广泛,但你可以使用 AbstractEncoder 和 AbstractDecoder 类来简化创建自定义编码器和解码器实现的过程。 这些类实现了 Encoder、Decoder、CompositeEncoder 和 CompositeDecoder 接口,因此在简单格式中,你可以使用同一个类来处理基本类型值和结构化值。
AbstractEncoder 类为大多数编码函数(例如 encodeString())提供了默认实现,这些函数委托给 encodeValue(value: Any) 函数。 这意味着只需重写 encodeValue() 函数,你就可以轻松创建一个基本且功能可用的自定义格式。
以下各节将使用这些 API 创建一个自定义格式:将值编码到列表中、从该列表中解码值,然后逐步添加顺序解码、集合支持以及 null 支持。
创建基础编码器
要构建自定义编码器,可以继承 AbstractEncoder 类。 这允许你重写默认实现,而无需从头实现 Encoder 和 CompositeEncoder 接口。
要创建基础编码器:
创建一个继承
AbstractEncoder的类以定义自定义序列化逻辑:kotlin@ExperimentalSerializationApi class ListEncoder : AbstractEncoder() { val list = mutableListOf<Any>() override val serializersModule: SerializersModule = EmptySerializersModule() }在
ListEncoder类中,重写encodeValue()以定义编码器如何处理每个值。kotlinoverride fun encodeValue(value: Any) { list.add(value) }创建一个使用该编码器序列化值的函数:
kotlin@ExperimentalSerializationApi fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> { val encoder = ListEncoder() encoder.encodeSerializableValue(serializer, value) return encoder.list }添加一个使用带有具体化(reified)类型形参的
serializer()的内联重载,这样调用方就无需显式传递序列化器:kotlin@ExperimentalSerializationApi inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
由于编码器通常会被应用程序的其他部分使用,因此请传递传播 @ExperimentalSerializationApi 注解,而不是仅在单个函数内部选择启用。
以下是一个最小示例,它将对象图中的基本类型值按序列化顺序编码为一个扁平列表:
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
import kotlinx.serialization.modules.*
// 创建一个将序列化值存储在列表中的自定义编码器
@ExperimentalSerializationApi
class ListEncoder : AbstractEncoder() {
val list = mutableListOf<Any>()
override val serializersModule: SerializersModule = EmptySerializersModule()
// 存储每个编码值
override fun encodeValue(value: Any) {
list.add(value)
}
}
// 编码一个值并将收集的值作为列表返回
@ExperimentalSerializationApi
fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
val encoder = ListEncoder()
encoder.encodeSerializableValue(serializer, value)
return encoder.list
}
// 提供类型安全的内联重载以方便调用
@ExperimentalSerializationApi
inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
@Serializable
data class Project(val name: String, val owner: User, val votes: Int)
@Serializable
data class User(val name: String)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Project("kotlinx.serialization", User("kotlin"), 9000)
println(encodeToList(data))
// [kotlinx.serialization, kotlin, 9000]
}输出显示,编码器按序列化顺序将所有序列化的值收集到了一个扁平列表中。 当你需要统一处理这些值时(例如计算哈希或摘要),这会非常有用。
创建基础解码器
要构建自定义解码器,可以继承 AbstractDecoder 类。 这允许你重写默认实现,而无需从头实现 Decoder 和 CompositeDecoder 接口。
要创建基础解码器:
创建一个继承
AbstractDecoder的类以定义自定义反序列化逻辑:kotlin@ExperimentalSerializationApi class ListDecoder(val list: ArrayDeque<Any>) : AbstractDecoder() { private var elementIndex = 0 override val serializersModule: SerializersModule = EmptySerializersModule() }在
ListDecoder类中,重写decodeValue()函数以定义解码器如何反序列化值:kotlinoverride fun decodeValue(): Any = list.removeFirst()重写
decodeElementIndex()函数以指示接下来解码哪个元素,并在结构处理完成时返回DECODE_DONE:kotlinoverride fun decodeElementIndex(descriptor: SerialDescriptor): Int { if (elementIndex == descriptor.elementsCount) return CompositeDecoder.DECODE_DONE return elementIndex++ }该格式按序列化顺序反序列化值,因此可以使用简单的
elementIndex计数器来跟踪进度。 更复杂的格式通常需要额外的逻辑来查找下一个要解码的元素。要了解自定义序列化器如何使用来自
decodeElementIndex()函数的元素索引,请参阅创建自定义复合序列化器。重写
beginStructure()函数为每个嵌套结构创建新的解码器,从而使每个递归解码的结构保持其各自的elementIndex状态:kotlinoverride fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder = ListDecoder(list)创建一个使用该解码器反序列化值的函数:
kotlin@ExperimentalSerializationApi fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T { val decoder = ListDecoder(ArrayDeque(list)) return decoder.decodeSerializableValue(deserializer) }添加一个内联重载以使反序列化更容易调用:
kotlin@ExperimentalSerializationApi inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
以下是一个完整的示例,展示了如何将基本类型值列表解码回对象:
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
import kotlinx.serialization.modules.*
// 创建一个将序列化值存储在列表中的自定义编码器
@ExperimentalSerializationApi
class ListEncoder : AbstractEncoder() {
val list = mutableListOf<Any>()
override val serializersModule: SerializersModule = EmptySerializersModule()
// 存储每个编码值
override fun encodeValue(value: Any) {
list.add(value)
}
}
// 编码一个值并将收集的值作为列表返回
@ExperimentalSerializationApi
fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
val encoder = ListEncoder()
encoder.encodeSerializableValue(serializer, value)
return encoder.list
}
// 提供类型安全的内联版本 encodeToList 以方便调用
@ExperimentalSerializationApi
inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
// 创建一个从列表中解码序列化值的自定义解码器
@ExperimentalSerializationApi
class ListDecoder(val list: ArrayDeque<Any>) : AbstractDecoder() {
private var elementIndex = 0
override val serializersModule: SerializersModule = EmptySerializersModule()
// 从列表中返回下一个值
override fun decodeValue(): Any = list.removeFirst()
// 指示下一个元素索引或发出解码完成的信号
override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
if (elementIndex == descriptor.elementsCount) return CompositeDecoder.DECODE_DONE
return elementIndex++
}
// 为每个嵌套结构创建新的解码器
override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
ListDecoder(list)
}
// 使用自定义解码器从列表中反序列化对象
@ExperimentalSerializationApi
fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
val decoder = ListDecoder(ArrayDeque(list))
return decoder.decodeSerializableValue(deserializer)
}
// 提供类型安全的内联版本 decodeFromList 以方便调用
@ExperimentalSerializationApi
inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
@Serializable
data class Project(val name: String, val owner: User, val votes: Int)
@Serializable
data class User(val name: String)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Project("kotlinx.serialization", User("kotlin"), 9000)
val list = encodeToList(data)
println(list)
// [kotlinx.serialization, kotlin, 9000]
val obj = decodeFromList<Project>(list)
println(obj)
// Project(name=kotlinx.serialization, owner=User(name=kotlin), votes=9000)
}输出显示解码器按序列化顺序重新读取列表,并重建了原始对象。
decodeElementIndex() 函数指示接下来处理哪个属性,而 beginStructure() 函数为嵌套对象创建新的解码器状态。
通过顺序解码进行优化
如果你的格式始终按声明顺序存储值,并且不支持跳过可选元素,则可以使用 decodeSequentially() 函数来优化解码。
当此函数返回 true 时,支持顺序解码的序列化器可以按顺序读取值,而无需重复请求下一个元素索引。 这可以提高反序列化按顺序格式存储的数据时的性能。由 kotlinx.serialization 插件生成的序列化器使用了这种优化。
从 decodeSequentially() 函数返回 true 并不保证使用你解码器的序列化器一定会采用顺序解码。 因此,请确保你的解码器同时支持通过 decodeElementIndex() 函数进行的常规解码。
要了解序列化器在反序列化期间如何使用 decodeSequentially() 函数,请参阅通过顺序解码优化反序列化。
以下是将此优化应用于自定义 ListDecoder 的方法:
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
import kotlinx.serialization.modules.*
@ExperimentalSerializationApi
class ListEncoder : AbstractEncoder() {
val list = mutableListOf<Any>()
override val serializersModule: SerializersModule = EmptySerializersModule()
override fun encodeValue(value: Any) {
list.add(value)
}
}
@ExperimentalSerializationApi
fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
val encoder = ListEncoder()
encoder.encodeSerializableValue(serializer, value)
return encoder.list
}
@ExperimentalSerializationApi
inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
@ExperimentalSerializationApi
class ListDecoder(val list: ArrayDeque<Any>) : AbstractDecoder() {
private var elementIndex = 0
override val serializersModule: SerializersModule = EmptySerializersModule()
override fun decodeValue(): Any = list.removeFirst()
// 当序列化器未使用顺序解码时添加常规解码支持
override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
if (elementIndex == descriptor.elementsCount) return CompositeDecoder.DECODE_DONE
return elementIndex++
}
override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
ListDecoder(list)
// 为支持它的序列化器启用顺序解码
override fun decodeSequentially(): Boolean = true
}
@ExperimentalSerializationApi
fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
val decoder = ListDecoder(ArrayDeque(list))
return decoder.decodeSerializableValue(deserializer)
}
@ExperimentalSerializationApi
inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
@Serializable
data class Project(val name: String, val owner: User, val votes: Int)
@Serializable
data class User(val name: String)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Project("kotlinx.serialization", User("kotlin"), 9000)
val list = encodeToList(data)
println(list)
// [kotlinx.serialization, kotlin, 9000]
val obj = decodeFromList<Project>(list)
println(obj)
// Project(name=kotlinx.serialization, owner=User(name=kotlin), votes=9000)
}在此示例中,ListDecoder 重写了 decodeSequentially() 函数以返回 true。 这使得受支持的序列化器可以直接按声明顺序读取值,而无需逐个查询每个元素索引。
添加集合支持
基础自定义格式可以逐个编码集合元素,但解码时也需要知道属于该集合的元素数量。
要在自定义格式中支持集合,请将集合大小与其元素一起编码,以便解码器知道集合在何处结束:
- 在编码器中实现
beginCollection()函数以处理集合大小。 - 如果编码器不需要额外的集合特定状态,则从
beginCollection()函数返回编码器实例本身。 - 在解码器中实现
decodeCollectionSize()函数,以便在反序列化期间解码并存储集合大小。 - 如果格式预先存储了集合大小且值是按顺序读取的,则从
decodeSequentially()函数返回true。
以下是为 ListEncoder 添加集合支持的完整示例:
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
import kotlinx.serialization.modules.*
@ExperimentalSerializationApi
fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
val encoder = ListEncoder()
encoder.encodeSerializableValue(serializer, value)
return encoder.list
}
@ExperimentalSerializationApi
inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
@ExperimentalSerializationApi
fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
val decoder = ListDecoder(ArrayDeque(list))
return decoder.decodeSerializableValue(deserializer)
}
@ExperimentalSerializationApi
inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
@Serializable
data class Project(val name: String, val owners: List<User>, val votes: Int)
@Serializable
data class User(val name: String)
@ExperimentalSerializationApi
class ListEncoder : AbstractEncoder() {
val list = mutableListOf<Any>()
override val serializersModule: SerializersModule = EmptySerializersModule()
override fun encodeValue(value: Any) {
list.add(value)
}
// 在元素之前存储集合大小
override fun beginCollection(descriptor: SerialDescriptor, collectionSize: Int): CompositeEncoder {
encodeInt(collectionSize)
// 返回相同的编码器,因为不需要额外的集合特定状态
return this
}
}
@ExperimentalSerializationApi
class ListDecoder(val list: ArrayDeque<Any>, var elementsCount: Int = 0) : AbstractDecoder() {
private var elementIndex = 0
override val serializersModule: SerializersModule = EmptySerializersModule()
override fun decodeValue(): Any = list.removeFirst()
override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
if (elementIndex == elementsCount) return CompositeDecoder.DECODE_DONE
return elementIndex++
}
override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
ListDecoder(list, descriptor.elementsCount)
// 发出按顺序解码值的信号,因为预先已知集合大小
override fun decodeSequentially(): Boolean = true
// 在读取集合元素之前解码并存储集合大小
override fun decodeCollectionSize(descriptor: SerialDescriptor): Int =
decodeInt().also { elementsCount = it }
}
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Project("kotlinx.serialization", listOf(User("kotlin"), User("jetbrains")), 9000)
val list = encodeToList(data)
println(list)
// [kotlinx.serialization, 2, kotlin, jetbrains, 9000]
val obj = decodeFromList<Project>(list)
println(obj)
// Project(name=kotlinx.serialization, owners=[User(name=kotlin), User(name=jetbrains)], votes=9000)
}在此示例中,编码后的列表在集合元素之前包含了集合大小,因此解码器能够正确解码集合。
添加 null 支持
要在自定义格式中支持 null 值,需要有一种方法将 null 与常规值区分开来。
这通常涉及在每个可为 null 的值之前添加一个“null 指示标记”,用于区分 null 值与实际数据。
要在自定义格式中添加对 null 值的支持:
- 在编码器中重写
encodeNull()以指定如何标记null值。 - 在编码器中重写
encodeNotNullMark()以标记非 null 值。 - 在解码器中重写
decodeNotNullMark()以在解码该值之前检查该标记。
以下是为 ListEncoder 和 ListDecoder 实现添加 null 支持的示例:
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
import kotlinx.serialization.modules.*
@ExperimentalSerializationApi
fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
val encoder = ListEncoder()
encoder.encodeSerializableValue(serializer, value)
return encoder.list
}
@ExperimentalSerializationApi
inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
@ExperimentalSerializationApi
fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
val decoder = ListDecoder(ArrayDeque(list))
return decoder.decodeSerializableValue(deserializer)
}
@ExperimentalSerializationApi
inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
@Serializable
data class Project(val name: String, val owner: User?, val votes: Int?)
@Serializable
data class User(val name: String)
@ExperimentalSerializationApi
class ListEncoder : AbstractEncoder() {
val list = mutableListOf<Any>()
override val serializersModule: SerializersModule = EmptySerializersModule()
override fun encodeValue(value: Any) {
list.add(value)
}
override fun beginCollection(descriptor: SerialDescriptor, collectionSize: Int): CompositeEncoder {
encodeInt(collectionSize)
return this
}
// 将 null 值表示为 NULL
override fun encodeNull() = encodeValue("NULL")
// 使用 "!!" 将值标记为非 null
override fun encodeNotNullMark() = encodeValue("!!")
}
@ExperimentalSerializationApi
class ListDecoder(val list: ArrayDeque<Any>, var elementsCount: Int = 0) : AbstractDecoder() {
private var elementIndex = 0
override val serializersModule: SerializersModule = EmptySerializersModule()
override fun decodeValue(): Any = list.removeFirst()
override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
if (elementIndex == elementsCount) return CompositeDecoder.DECODE_DONE
return elementIndex++
}
override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
ListDecoder(list, descriptor.elementsCount)
override fun decodeSequentially(): Boolean = true
override fun decodeCollectionSize(descriptor: SerialDescriptor): Int =
decodeInt().also { elementsCount = it }
// 检查下一个值是否为 "NULL",以确定下一个可为 null 的值是否为 null
override fun decodeNotNullMark(): Boolean = decodeString() != "NULL"
}
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Project("kotlinx.serialization", User("kotlin"), null)
val list = encodeToList(data)
println(list)
// [kotlinx.serialization, !!, kotlin, NULL]
val obj = decodeFromList<Project>(list)
println(obj)
// Project(name=kotlinx.serialization, owner=User(name=kotlin), votes=null)
}在此示例中,编码器在非 null 值之前写入 !!,并针对 null 值写入 NULL。 解码器检查这些标记以决定是解码值还是返回 null。
创建紧凑的二进制格式
二进制格式通常因其紧凑的数据表示形式而被使用,非常适合需要尽量减少存储或传输数据量的场景。
自定义二进制格式允许你在底层控制数据的序列化与反序列化方式。 这为你提供了优化性能以及与其他系统保持兼容性的灵活性。
你可以通过实现 java.io.DataOutput 和 java.io.DataInput 接口,使用 Kotlin 序列化创建自定义二进制格式。
以下示例展示了如何使用 DataOutput 和 DataInput 将 ListEncoder 和 ListDecoder 实现转变为紧凑的二进制格式:
为每个基本类型重写编码函数,例如用于整数的
encodeInt()或用于字符串的encodeString()。 这些针对特定类型的编码函数可以避免装箱,并允许你为每个基本类型定义二进制表示。 在此示例中,值直接编码到DataOutput流中:kotlinoverride fun encodeBoolean(value: Boolean) = output.writeByte(if (value) 1 else 0) override fun encodeByte(value: Byte) = output.writeByte(value.toInt()) override fun encodeShort(value: Short) = output.writeShort(value.toInt()) override fun encodeInt(value: Int) = output.writeInt(value) override fun encodeLong(value: Long) = output.writeLong(value) override fun encodeFloat(value: Float) = output.writeFloat(value) override fun encodeDouble(value: Double) = output.writeDouble(value) override fun encodeChar(value: Char) = output.writeChar(value.code) override fun encodeString(value: String) = output.writeUTF(value) override fun encodeEnum(enumDescriptor: SerialDescriptor, index: Int) = output.writeInt(index)为每个基本类型实现解码函数,例如
decodeInt()或decodeString()。 这使解码器能够直接从DataInput流中解码值并重建原始数据结构:kotlinoverride fun decodeBoolean(): Boolean = input.readByte().toInt() != 0 override fun decodeByte(): Byte = input.readByte() override fun decodeShort(): Short = input.readShort() override fun decodeInt(): Int = input.readInt() override fun decodeLong(): Long = input.readLong() override fun decodeFloat(): Float = input.readFloat() override fun decodeDouble(): Double = input.readDouble() override fun decodeChar(): Char = input.readChar() override fun decodeString(): String = input.readUTF() override fun decodeEnum(enumDescriptor: SerialDescriptor): Int = input.readInt()使用这些类以二进制格式序列化和反序列化 Kotlin 对象:
kotlinimport kotlinx.serialization.* import kotlinx.serialization.Serializable import kotlinx.serialization.descriptors.* import kotlinx.serialization.encoding.* import kotlinx.serialization.modules.* import java.io.* @ExperimentalSerializationApi class DataOutputEncoder(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 encodeShort(value: Short) = output.writeShort(value.toInt()) override fun encodeInt(value: Int) = output.writeInt(value) override fun encodeLong(value: Long) = output.writeLong(value) override fun encodeFloat(value: Float) = output.writeFloat(value) override fun encodeDouble(value: Double) = output.writeDouble(value) override fun encodeChar(value: Char) = output.writeChar(value.code) override fun encodeString(value: String) = output.writeUTF(value) override fun encodeEnum(enumDescriptor: SerialDescriptor, index: Int) = output.writeInt(index) override fun beginCollection(descriptor: SerialDescriptor, collectionSize: Int): CompositeEncoder { encodeInt(collectionSize) return this } override fun encodeNull() = encodeBoolean(false) override fun encodeNotNullMark() = encodeBoolean(true) } @ExperimentalSerializationApi fun <T> encodeTo(output: DataOutput, serializer: SerializationStrategy<T>, value: T) { val encoder = DataOutputEncoder(output) encoder.encodeSerializableValue(serializer, value) } @ExperimentalSerializationApi inline fun <reified T> encodeTo(output: DataOutput, value: T) = encodeTo(output, serializer(), value) @ExperimentalSerializationApi class DataInputDecoder(val input: DataInput, var elementsCount: Int = 0) : AbstractDecoder() { private var elementIndex = 0 override val serializersModule: SerializersModule = EmptySerializersModule() // 直接从二进制形式解码基本类型值 override fun decodeBoolean(): Boolean = input.readByte().toInt() != 0 override fun decodeByte(): Byte = input.readByte() override fun decodeShort(): Short = input.readShort() override fun decodeInt(): Int = input.readInt() override fun decodeLong(): Long = input.readLong() override fun decodeFloat(): Float = input.readFloat() override fun decodeDouble(): Double = input.readDouble() override fun decodeChar(): Char = input.readChar() override fun decodeString(): String = input.readUTF() 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 beginStructure(descriptor: SerialDescriptor): CompositeDecoder = DataInputDecoder(input, descriptor.elementsCount) override fun decodeSequentially(): Boolean = true override fun decodeCollectionSize(descriptor: SerialDescriptor): Int = decodeInt().also { elementsCount = it } override fun decodeNotNullMark(): Boolean = decodeBoolean() } @ExperimentalSerializationApi fun <T> decodeFrom(input: DataInput, deserializer: DeserializationStrategy<T>): T { val decoder = DataInputDecoder(input) return decoder.decodeSerializableValue(deserializer) } @ExperimentalSerializationApi inline fun <reified T> decodeFrom(input: DataInput): T = decodeFrom(input, serializer()) fun ByteArray.toAsciiHexString() = joinToString("") { if (it in 32..127) it.toInt().toChar().toString() else "{${it.toUByte().toString(16).padStart(2, '0').uppercase()}}" } @Serializable data class Project(val name: String, val language: String) @OptIn(ExperimentalSerializationApi::class) fun main() { val data = Project("kotlinx.serialization", "Kotlin") // 将对象编码为自定义二进制格式 val output = ByteArrayOutputStream() encodeTo(DataOutputStream(output), data) val bytes = output.toByteArray() println(bytes.toAsciiHexString()) // {00}{15}kotlinx.serialization{00}{06}Kotlin // 从自定义二进制格式解码对象 val input = ByteArrayInputStream(bytes) val obj = decodeFrom<Project>(DataInputStream(input)) println(obj) // Project(name=kotlinx.serialization, language=Kotlin) }
在此示例中,自定义格式仅以二进制形式编码序列化的值,而不包含键或属性名称,并将其解码回 Project 对象。 这使得在需要紧凑表示以及对二进制编码进行精确控制的场景下,可以更轻松地调整格式。
添加对特定格式类型的支持
自定义格式可以支持无法直接映射到标准基本类型编码函数的类型。
为了支持此类类型,请在编码器中重写 encodeSerializableValue() 函数,并在解码器中重写 decodeSerializableValue() 函数。 这使你能够为特定格式类型定义自定义序列化逻辑,同时保持对非标准数据表示的高效处理和灵活性。
为了正确检测类型,请将 serializer.descriptor 属性与该类型的序列化器描述符进行比较,而不是检查值的运行时类型。 即使某个类型使用了自定义序列化器,或者与另一个类型共享相同的底层表示,这样做也可以保留声明的序列化形式。
让我们看一个示例,了解如何通过对 ByteArray 类型的专门支持来扩展紧凑二进制格式示例:
获取特定格式类型的序列化器,以便编码器可以通过描述符检测到它:
kotlinprivate val byteArraySerializer = serializer<ByteArray>()你也可以使用内置的
ByteArraySerializer()函数获得类似的结果。在编码器中重写
encodeSerializableValue()函数,以便通过描述符检测ByteArray值并使用专门的编码路径。然后定义辅助函数来编码字节数组:kotlinoverride fun <T> encodeSerializableValue(serializer: SerializationStrategy<T>, value: T) { if (serializer.descriptor == byteArraySerializer.descriptor) encodeByteArray(value as ByteArray) else super.encodeSerializableValue(serializer, value) } // 使用大小的紧凑表示来编码 ByteArray private fun encodeByteArray(bytes: ByteArray) { encodeCompactSize(bytes.size) output.write(bytes) } // 用单个字节编码最大为 254 的大小 private fun encodeCompactSize(value: Int) { if (value < 0xff) { output.writeByte(value) } else { output.writeByte(0xff) output.writeInt(value) } }在解码器中重写
decodeSerializableValue()函数,以便通过描述符检测ByteArray值并使用匹配的紧凑大小格式反序列化它们:override fun <T> decodeSerializableValue(deserializer: DeserializationStrategy<T>, previousValue: T?) {...}
kotlin@Suppress("UNCHECKED_CAST") override fun <T> decodeSerializableValue(deserializer: DeserializationStrategy<T>, previousValue: T?): T = if (deserializer.descriptor == byteArraySerializer.descriptor) decodeByteArray() as T else super.decodeSerializableValue(deserializer, previousValue) // 解码 ByteArray 数据 private fun decodeByteArray(): ByteArray { val bytes = ByteArray(decodeCompactSize()) input.readFully(bytes) return bytes } // 使用紧凑格式高效解码大小 private fun decodeCompactSize(): Int { val byte = input.readByte().toInt() and 0xff if (byte < 0xff) return byte return input.readInt() }序列化和反序列化带有嵌入
ByteArray数据的对象:data class Project(val name: String, val attachment: ByteArray) {...}
kotlin@Serializable data class Project(val name: String, val attachment: ByteArray) @OptIn(ExperimentalSerializationApi::class) fun main() { val data = Project("kotlinx.serialization", byteArrayOf(0x0A, 0x0B, 0x0C, 0x0D)) val output = ByteArrayOutputStream() encodeTo(DataOutputStream(output), data) val bytes = output.toByteArray() println(bytes.toAsciiHexString()) // {00}{15}kotlinx.serialization{04}{0A}{0B}{0C}{0D} val input = ByteArrayInputStream(bytes) val obj = decodeFrom<Project>(DataInputStream(input)) println(obj) // Project(name=kotlinx.serialization, attachment=[10, 11, 12, 13]) }
以下是完整的示例,展示了如何使用专门的编码和解码路径序列化和反序列化带有 ByteArray 属性的类:
import kotlinx.serialization.*
import kotlinx.serialization.Serializable
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.modules.*
import kotlinx.serialization.encoding.*
import java.io.*
// 声明用于按描述符检测 ByteArray 的序列化器
private val byteArraySerializer = serializer<ByteArray>()
@ExperimentalSerializationApi
class DataOutputEncoder(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 encodeShort(value: Short) = output.writeShort(value.toInt())
override fun encodeInt(value: Int) = output.writeInt(value)
override fun encodeLong(value: Long) = output.writeLong(value)
override fun encodeFloat(value: Float) = output.writeFloat(value)
override fun encodeDouble(value: Double) = output.writeDouble(value)
override fun encodeChar(value: Char) = output.writeChar(value.code)
override fun encodeString(value: String) = output.writeUTF(value)
override fun encodeEnum(enumDescriptor: SerialDescriptor, index: Int) = output.writeInt(index)
override fun beginCollection(descriptor: SerialDescriptor, collectionSize: Int): CompositeEncoder {
encodeInt(collectionSize)
return this
}
override fun encodeNull() = encodeBoolean(false)
override fun encodeNotNullMark() = encodeBoolean(true)
// 通过描述符检测 ByteArray 并使用专门的编码路径
override fun <T> encodeSerializableValue(serializer: SerializationStrategy<T>, value: T) {
if (serializer.descriptor == byteArraySerializer.descriptor)
encodeByteArray(value as ByteArray)
else
super.encodeSerializableValue(serializer, value)
}
// 使用紧凑大小表示编码 ByteArray
private fun encodeByteArray(bytes: ByteArray) {
encodeCompactSize(bytes.size)
output.write(bytes)
}
// 用单个字节编码最大为 254 的大小
private fun encodeCompactSize(value: Int) {
if (value < 0xff) {
output.writeByte(value)
} else {
output.writeByte(0xff)
output.writeInt(value)
}
}
}
@ExperimentalSerializationApi
fun <T> encodeTo(output: DataOutput, serializer: SerializationStrategy<T>, value: T) {
val encoder = DataOutputEncoder(output)
encoder.encodeSerializableValue(serializer, value)
}
@ExperimentalSerializationApi
inline fun <reified T> encodeTo(output: DataOutput, value: T) = encodeTo(output, serializer(), value)
@ExperimentalSerializationApi
class DataInputDecoder(val input: DataInput, var elementsCount: Int = 0) : AbstractDecoder() {
private var elementIndex = 0
override val serializersModule: SerializersModule = EmptySerializersModule()
// 这些函数用于解码基本类型
override fun decodeBoolean(): Boolean = input.readByte().toInt() != 0
override fun decodeByte(): Byte = input.readByte()
override fun decodeShort(): Short = input.readShort()
override fun decodeInt(): Int = input.readInt()
override fun decodeLong(): Long = input.readLong()
override fun decodeFloat(): Float = input.readFloat()
override fun decodeDouble(): Double = input.readDouble()
override fun decodeChar(): Char = input.readChar()
override fun decodeString(): String = input.readUTF()
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 beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
DataInputDecoder(input, descriptor.elementsCount)
override fun decodeSequentially(): Boolean = true
override fun decodeCollectionSize(descriptor: SerialDescriptor): Int =
decodeInt().also { elementsCount = it }
override fun decodeNotNullMark(): Boolean = decodeBoolean()
// 通过描述符检测 ByteArray 并使用专门的解码路径
@Suppress("UNCHECKED_CAST")
override fun <T> decodeSerializableValue(deserializer: DeserializationStrategy<T>, previousValue: T?): T =
if (deserializer.descriptor == byteArraySerializer.descriptor)
decodeByteArray() as T
else
super.decodeSerializableValue(deserializer, previousValue)
// 解码数组大小,然后解码字节数组内容
private fun decodeByteArray(): ByteArray {
val bytes = ByteArray(decodeCompactSize())
input.readFully(bytes)
return bytes
}
// 从单个字节解码最大为 254 的大小
private fun decodeCompactSize(): Int {
val byte = input.readByte().toInt() and 0xff
if (byte < 0xff) return byte
return input.readInt()
}
}
@ExperimentalSerializationApi
fun <T> decodeFrom(input: DataInput, deserializer: DeserializationStrategy<T>): T {
val decoder = DataInputDecoder(input)
return decoder.decodeSerializableValue(deserializer)
}
@ExperimentalSerializationApi
inline fun <reified T> decodeFrom(input: DataInput): T = decodeFrom(input, serializer())
fun ByteArray.toAsciiHexString() = joinToString("") {
if (it in 32..127) it.toInt().toChar().toString() else
"{${it.toUByte().toString(16).padStart(2, '0').uppercase()}}"
}
@Serializable
data class Project(val name: String, val attachment: ByteArray)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Project("kotlinx.serialization", byteArrayOf(0x0A, 0x0B, 0x0C, 0x0D))
val output = ByteArrayOutputStream()
encodeTo(DataOutputStream(output), data)
val bytes = output.toByteArray()
println(bytes.toAsciiHexString())
// {00}{15}kotlinx.serialization{04}{0A}{0B}{0C}{0D}
val input = ByteArrayInputStream(bytes)
val obj = decodeFrom<Project>(DataInputStream(input))
println(obj)
// Project(name=kotlinx.serialization, attachment=[10, 11, 12, 13])
}定义特定格式的 @Serializable 注解
你可以使用 @MetaSerializable 注解来定义特定格式的 @Serializable 注解。 将特定格式的注解添加到类上以替代 @Serializable,可使该类可序列化,并将注解数据包含在生成的序列描述符中。
以下是定义 @BinarySerializable 注解的示例:
import kotlinx.serialization.ExperimentalSerializationApi
import kotlinx.serialization.MetaSerializable
@OptIn(ExperimentalSerializationApi::class)
// 定义使被注解类可序列化的特定格式注解
@MetaSerializable
@Target(AnnotationTarget.CLASS)
annotation class BinarySerializable(val typeId: Int)
@BinarySerializable(typeId = 1)
data class Project(val name: String, val language: String)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
// 序列化插件为 Project 生成序列化器的方式
// 与使用 @Serializable 注解的类相同
val descriptor = Project.serializer().descriptor
// 从序列描述符的注解中检索类标识符
val typeId = descriptor.annotations
.filterIsInstance<BinarySerializable>()
.first()
.typeId
println(typeId)
// 1
}后续步骤
- 了解如何以 CBOR 格式序列化数据。
- 探索以 ProtoBuf 格式进行的 Protocol Buffers 序列化。
