ProtoBuf 格式
Protocol Buffers (ProtoBuf) 是一种语言中立的二进制格式,通常使用单独的 .proto 文件来定义协议架构。 它比 CBOR 更紧凑,因为它是为字段分配整数编号而不是名称。
Kotlin 序列化使用 proto2 语义,其中所有字段都显式指定为必填(required)或可选(optional)。
为 ProtoBuf 添加依赖项
要在项目中使用 ProtoBuf,请在构建文件中添加 ProtoBuf 序列化库依赖项:
// build.gradle(.kts)
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-protobuf:1.11.0")
}<!-- pom.xml -->
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-serialization-protobuf</artifactId>
<version>1.11.0</version>
</dependency>
</dependencies>使用 ProtoBuf 进行二进制序列化
要使用 ProtoBuf 序列化对象,请使用 ProtoBuf 类以及 .encodeToByteArray() 和 .decodeFromByteArray() 函数:
import kotlinx.serialization.*
import kotlinx.serialization.protobuf.*
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")
// 将 Project 实例序列化为 ProtoBuf 字节数组
val bytes = ProtoBuf.encodeToByteArray(data)
// 以可读的混合格式打印字节数组
println(bytes.toAsciiHexString())
// {0A}{15}kotlinx.serialization{12}{06}Kotlin
// 将 ProtoBuf 字节数组反序列化回对象
val obj = ProtoBuf.decodeFromByteArray<Project>(bytes)
println(obj)
// Project(name=kotlinx.serialization, language=Kotlin)
}在此示例中,输出将字符串值打印为可读文本,其余字节打印为十六进制形式。 这些字节对应于 ProtoBuf 十六进制表示法中的以下值:
Field #1: 0A String Length = 21, Hex = 15, UTF8 = "kotlinx.serialization"
Field #2: 12 String Length = 6, Hex = 06, UTF8 = "Kotlin"为 ProtoBuf 序列化分配字段编号
默认情况下,ProtoBuf 会自动分配字段编号。
为了保持架构随着时间的推移保持稳定,可以使用 @ProtoNumber 注解显式分配字段编号,而无需单独的 .proto 文件。 例如,@ProtoNumber(1) 为属性分配字段编号 1,因此 Kotlin 序列化的 ProtoBuf 格式在编码和解码期间会使用该编号,而不是自动分配一个编号。
如果您计划重新排列属性顺序,显式分配字段编号可以保持架构稳定,并符合 Protobuf 用于演化架构的兼容性规则。
示例如下:
import kotlinx.serialization.*
import kotlinx.serialization.protobuf.*
@OptIn(ExperimentalSerializationApi::class)
@Serializable
data class Project(
// 为 name 属性分配字段编号 1
@ProtoNumber(1)
val name: String,
// 为 language 属性分配字段编号 3
@ProtoNumber(3)
val language: String
)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Project("kotlinx.serialization", "Kotlin")
val bytes = ProtoBuf.encodeToByteArray(data)
println(bytes.toAsciiHexString())
// {0A}{15}kotlinx.serialization{1A}{06}Kotlin
val obj = ProtoBuf.decodeFromByteArray<Project>(bytes)
println(obj)
// Project(name=kotlinx.serialization, language=Kotlin)
}在此示例中,name 属性使用字段编号 1,其编码后的 tag 为 0A。 language 属性使用字段编号 3,其编码后的 tag 为 1A。
在 ProtoBuf 十六进制表示法中,输出等同于以下内容:
Field #1: 0A String Length = 21, Hex = 15, UTF8 = "kotlinx.serialization" (total 21 chars)
Field #3: 1A String Length = 6, Hex = 06, UTF8 = "Kotlin"有关 Protobuf 字段编号的更多信息,请参阅官方 Protobuf 语言指南。
在 ProtoBuf 中指定整数编码
ProtoBuf 默认使用 varint 编码对整数属性进行编码。
要对属性使用不同的整数编码,请应用带有 ProtoIntegerType 值的 @ProtoType 注解。 该注解影响 Byte、Short、Int、Long 和 Char 属性。
ProtoIntegerType 枚举支持三个选项:
DEFAULT选项使用 varint 编码(intXX),该编码针对较小的非负数进行了优化。例如,值1会被编码为单字节01。SIGNED选项使用带符号的 ZigZag 编码(sintXX),适用于较小的有符号整数。例如,它将值-2编码为单字节03。FIXED选项使用定长编码(fixedXX),始终使用固定数量的字节。例如,它将值3编码为四个字节03 00 00 00。
不支持 uintXX 和 sfixedXX Protocol Buffer 类型。
以下示例展示了所有三种支持的选项:
import kotlinx.serialization.*
import kotlinx.serialization.protobuf.*
@OptIn(ExperimentalSerializationApi::class)
@Serializable
class Data(
// 使用 DEFAULT 编码,针对较小的非负数进行了优化
@ProtoType(ProtoIntegerType.DEFAULT)
val a: Int,
// 使用 SIGNED 编码,针对较小的有符号整数进行了优化
@ProtoType(ProtoIntegerType.SIGNED)
val b: Int,
// 使用 FIXED 编码,始终使用固定数量的字节
@ProtoType(ProtoIntegerType.FIXED)
val c: Int
)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Data(1, -2, 3)
println(ProtoBuf.encodeToByteArray(data).toAsciiHexString())
// {08}{01}{10}{03}{1D}{03}{00}{00}{00}
}将数值集合编码为 packed 字段
在 ProtoBuf 中,packed 字段通过将列表作为单个带长度界定的条目写入,而不是为每个元素重复字段 tag,从而更高效地存储重复的基本数值。
可以使用 @ProtoPacked 注解以这种形式序列化除 Map 之外的集合类型。 Packed 编码仅适用于重复的基本数值字段,对于其他元素类型,该注解将被忽略。
根据 Protobuf 编码规范,解析器既接受 packed 也接受 unpacked 重复数值字段,因此解码不依赖于是否存在 @ProtoPacked。
示例如下:
import kotlinx.serialization.*
import kotlinx.serialization.protobuf.*
@OptIn(ExperimentalSerializationApi::class)
@Serializable
data class DataPacked(
// 对 values 列表使用 packed 编码
@ProtoPacked
val values: List<Int>
)
@Serializable
data class DataRepeated(
val values: List<Int>
)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val packed = ProtoBuf.encodeToByteArray(
DataPacked.serializer(),
DataPacked(listOf(1, 2, 3))
)
println(packed.toAsciiHexString())
// {0A}{03}{01}{02}{03}
val repeated = ProtoBuf.encodeToByteArray(
DataRepeated.serializer(),
DataRepeated(listOf(1, 2, 3))
)
println(repeated.toAsciiHexString())
// {08}{01}{08}{02}{08}{03}
println(ProtoBuf.decodeFromByteArray(DataRepeated.serializer(), packed))
// DataRepeated(values=[1, 2, 3])
println(ProtoBuf.decodeFromByteArray(DataPacked.serializer(), repeated))
// DataPacked(values=[1, 2, 3])
}表示 oneof 字段
oneof 字段定义了一组字段,其中一次只能设置一个值。
在 Kotlin 序列化中,可以使用多态类型来表示这种结构。
考虑以下 ProtoBuf 消息定义:
message Data {
required string name = 1;
oneof phone {
string home_phone = 2;
string work_phone = 3;
}
}要在 Kotlin 中表示此消息:
创建一个
sealed interface或abstract class来表示oneof声明内的字段:kotlin@Serializable sealed interface IPhoneType为整个消息定义一个类。添加一个
name属性并使用@ProtoNumber(1)进行注解。 添加一个多态IPhoneType类型的phone属性,并使用@ProtoOneOf进行注解:kotlin@Serializable data class Data( @ProtoNumber(1) val name: String, @ProtoOneOf val phone: IPhoneType?, )对于
oneof声明中的每个字段,创建一个仅包含与该字段对应的单个属性的子类。每个子类可以是普通类、数据类或值类(value class):kotlin@Serializable @JvmInline value class HomePhone( val number: String ) : IPhoneType @Serializable data class WorkPhone( val number: String ) : IPhoneType使用
oneof声明中的字段编号,通过@ProtoNumber为每个子类属性添加注解:kotlin@Serializable @JvmInline value class HomePhone( @ProtoNumber(2) val number: String ) : IPhoneType @Serializable data class WorkPhone( @ProtoNumber(3) val number: String ) : IPhoneType
下面是一个更详细的示例,其中 oneof 用于存储家庭电话或工作电话:
import kotlinx.serialization.*
import kotlinx.serialization.protobuf.*
// 表示 oneof 组
@Serializable
sealed interface IPhoneType
// 表示 home_phone 字段
@OptIn(ExperimentalSerializationApi::class)
@Serializable @JvmInline value class HomePhone(@ProtoNumber(2) val number: String): IPhoneType
// 将 work_phone 字段表示为数据类
@OptIn(ExperimentalSerializationApi::class)
@Serializable data class WorkPhone(@ProtoNumber(3) val number: String): IPhoneType
// 定义包含 oneof 属性的数据类
@OptIn(ExperimentalSerializationApi::class)
@Serializable
data class Data(
// 为 name 属性分配字段编号 1
@ProtoNumber(1) val name: String,
// 将多态属性映射到 oneof 声明
@ProtoOneOf val phone: IPhoneType?,
)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val dataTom = Data("Tom", HomePhone("123"))
val stringTom = ProtoBuf.encodeToHexString(dataTom)
val dataJerry = Data("Jerry", WorkPhone("789"))
val stringJerry = ProtoBuf.encodeToHexString(dataJerry)
println(stringTom)
// 0a03546f6d1203313233
println(stringJerry)
// 0a054a657272791a03373839
println(ProtoBuf.decodeFromHexString<Data>(stringTom))
// Data(name=Tom, phone=HomePhone(number=123))
println(ProtoBuf.decodeFromHexString<Data>(stringJerry))
// Data(name=Jerry, phone=WorkPhone(number=789))
}输出表明 ProtoBuf 在每条消息中仅编码了 oneof 声明中的一个字段:
0a03546f6d1203313233表示带有home_phone的"Tom"。0a054a657272791a03373839表示带有work_phone的"Jerry"。
为了防止潜在的字段编号冲突或运行时的 IllegalArgumentException,请将每个 oneof 类型层次结构仅映射到一个数据类。
如果只需要反序列化数据,也可以定义一个不带 @ProtoOneOf 注解的类。
例如:
@Serializable
data class Data(
@ProtoNumber(1) val name: String,
@ProtoNumber(2) val homeNumber: String? = null,
@ProtoNumber(3) val workNumber: String? = null,
)通过这种方式,无需使用密封层次结构即可反序列化 oneof 字段。
但是,它在序列化期间不强制 homeNumber 和 workNumber 之间的互斥性。 如果这两个字段都有值,序列化输出可能与原始的 oneof 架构不匹配,并且另一个 ProtoBuf 解析器可能仅保留它读取的最后一个字段。
生成 ProtoBuf 架构
通常,使用 ProtoBuf 涉及使用 .proto 文件和代码生成器来创建用于序列化和反序列化的代码。 然而,借助 Kotlin 序列化,可以使用带有 @Serializable 注解的 Kotlin 类作为架构的源,从而使 .proto 文件变为可选项。
当涉及的所有代码都是用 Kotlin 编写时,这种方法简化了流程,但与其他语言的互操作性通常仍需要 .proto 架构。
要生成此架构,请使用 ProtoBufSchemaGenerator。 它从一个或多个 SerialDescriptor 实例生成兼容 Proto2 的架构。
这为您提供了一个可与其他 ProtoBuf 工具一起使用的 .proto 架构。
以下是从 Kotlin 数据类生成 .proto 架构的示例:
import kotlinx.serialization.*
import kotlinx.serialization.protobuf.*
import kotlinx.serialization.protobuf.schema.ProtoBufSchemaGenerator
@Serializable
data class SampleData(
val amount: Long,
val description: String?,
val department: String = "QA"
)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val descriptors = listOf(SampleData.serializer().descriptor)
val schemas = ProtoBufSchemaGenerator.generateSchemaText(descriptors)
println(schemas)
}此代码生成以下 .proto 架构:
syntax = "proto2";
// serial name 'example.exampleFormats09.SampleData'
message SampleData {
required int64 amount = 1;
optional string description = 2;
// WARNING: a default value decoded when value is missing
optional string department = 3;
}Kotlin 默认值不会在 .proto 文件中表示,因此生成的架构会为具有默认值的属性添加警告注释。
