Kotlin 序列化

此版本的文档已存档，不再提供支持。查看最新文档，学习；了解当前支持的Kotlin驾驶员版本。

Overview

Kotlin 驱动程序支持用于序列化和反序列化 Kotlin 对象的 kotlinx.serialization 库。

驱动程序提供了高效的 Bson 序列化器，您可以将其与标记为 @Serializable 的类一起使用，将 Kotlin 对象序列化为 BSON 数据。

您还可以安装 bson-kotlinx 库来支持自定义编解码器，并配置编码默认值、编码空值和定义类鉴别器。

注意

要学习；了解如何使用Codec接口而不是Kotlin序列化库来指定将Kotlin对象自定义编码和解码为BSON数据，请参阅编解码器指南。

如果您已熟悉此框架或更想使用惯用的 Kotlin 方法，则可选择 Kotlin 序列化。

虽然您可以将 Kotlin 驱动程序与 Kotlin 序列化 Json 库一起使用，但 Json 序列化器并不直接支持 BSON 值类型（如 ObjectId）。您必须提供能处理 BSON 和 JSON 之间转换的自定义序列化器。

支持的类型

Kotlin 驱动程序支持：

Kotlin 序列化库支持的所有 Kotlin 类型
所有可用的 BSON 类型

将 Kotlin 序列化添加到您的项目中

Kotlin驾驶员对序列化的支持取决于官方Kotlin序列化库。

从以下标签页中进行选择，以了解如何使用 Gradle 和 Maven 包管理器将序列化依赖项添加到项目中：

如果您使用 Gradle 要管理依赖项，请将以下内容添加到build.gradle.kts 依赖项列表中：

build.gradle.kts

implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.6.0")
implementation("org.mongodb:bson-kotlinx:5.0.0")

如果您使用的是 Maven 要管理依赖项，请将以下内容添加到pom.xml 依赖项列表中：

pom.xml

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-serialization-core</artifactId>
    <version>1.6.0</version>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.0.0</version>
</dependency>

为数据类添加注释

要将类声明为可序列化，请使用 Kotlin 序列化框架中的 @Serializable 注释来注释 Kotlin 数据类。

在将数据类标记为可序列化后，您可以在代码中正常使用这些类。Kotlin 驱动程序和 Kotlin 序列化框架处理 BSON 序列化和反序列化。

此示例展示的是带有以下注释的简单数据类：

@Serializable 来将类标记为可序列化。
@SerialName 来指定 BSON 文档中 id 和 manufacturer 属性的名称。这样就可以用来代替 @BsonId 和 @BsonProperty 注解，可序列化类不支持这两种注解。
@Contextual 将 BSON id 属性标记为使用内置的 ObjectIdSerializer。要正确序列化 BSON 类型，需要此注释。

@Serializable
data class PaintOrder(
    @SerialName("_id") // Use instead of @BsonId
    @Contextual val id: ObjectId?,
    val color: String,
    val qty: Int,
    @SerialName("brand")
    val manufacturer: String = "Acme" // Use instead of @BsonProperty
)

注意

您不能在 @Serializable 数据类上使用 org.bson.codecs.pojo.annotations 包中的注释。

有关可序列化类和可用注解类的更多信息，请参阅 Kotlin 序列化官方文档。

自定义序列化器示例

您可以创建自定义序列化器以处理如何在 BSON 中表示数据。Kotlin 驱动程序使用 kotlinx.serialization 包中的 KSerializer 接口实施自定义序列化器。您可以将自定义序列化器指定为特定字段的 @Serializable 注解的参数。

以下示例介绍如何创建自定义 KSerializer 实例，以将 kotlinx.datetime.Instant 转换为 BsonDateTime：

object InstantAsBsonDateTime : KSerializer<Instant> {
    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("InstantAsBsonDateTime", PrimitiveKind.LONG)
    override fun serialize(encoder: Encoder, value: Instant) {
        when (encoder) {
            is BsonEncoder -> encoder.encodeBsonValue(BsonDateTime(value.toEpochMilliseconds()))
            else -> throw SerializationException("Instant is not supported by ${encoder::class}")
        }
    }
    override fun deserialize(decoder: Decoder): Instant {
        return when (decoder) {
            is BsonDecoder -> Instant.fromEpochMilliseconds(decoder.decodeBsonValue().asDateTime().value)
            else -> throw SerializationException("Instant is not supported by ${decoder::class}")
        }
    }
}

以下代码显示 PaintOrder 数据类，其中 orderDate 字段具有指定前面代码中定义的自定义序列化器类的注解：

@Serializable
data class PaintOrder(
    val color: String,
    val qty: Int,
    @Serializable(with = InstantAsBsonDateTime::class)
    val orderDate: Instant,
)

有关本节中提到的方法和类的详情，请参阅以下 API 文档：

自定义序列化程序配置

您可以使用 org.bson.codecs.kotlinx 包中的 KotlinSerializerCodec 类为 @Serializable 数据类创建编解码器并自定义存储的内容。

使用 BsonConfiguration 类定义配置，包括是否对默认值进行编码、对 null 进行编码或定义类鉴别器。

要创建自定义编解码器，请在项目中安装 bson-kotlinx 依赖项。从以下标签页中进行选择，以了解如何使用 Gradle 和 Maven 包管理器将依赖项添加到项目中：

如果您使用 Gradle 要管理依赖项，请将以下内容添加到build.gradle.kts 依赖项列表中：

build.gradle.kts

implementation("org.mongodb:bson-kotlinx:5.0.0")

如果您使用的是 Maven 要管理依赖项，请将以下内容添加到pom.xml 依赖项列表中：

pom.xml

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.0.0</version>
</dependency>

注意

bson-kotlin 依赖项

您还可以选择通过默认编解码器注册表安装bson-kotlin依赖项。此依赖项使用反射和编解码器注册表来支持 Kotlin 数据类，但不支持某些 POJO 注解，例如BsonDiscriminator 、 BsonExtraElements和BsonConstructor 。要了解更多信息，请参阅 bson-kotlin API 文档。

一般来说，我们建议您安装并使用速度更快的 bson-kotlinx 库进行编解码器配置。

然后，您可以使用 KotlinSerializerCodec.create() 定义您的编解码器。方法并将其添加到注册表中。

自定义编解码器示例

以下示例展示了如何使用 KotlinSerializerCodec.create() 方法创建编解码器，并将其配置为不对默认值编码：

import org.bson.codecs.configuration.CodecRegistries
import org.bson.codecs.kotlinx.BsonConfiguration
import org.bson.codecs.kotlinx.KotlinSerializerCodec

val myCustomCodec = KotlinSerializerCodec.create<PaintOrder>(
    bsonConfiguration = BsonConfiguration(encodeDefaults = false)
)
val registry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(myCustomCodec), collection.codecRegistry
)

有关本节中提到的方法和类的详情，请参阅以下 API 文档：

后退

文档 (Document）

来年

编解码器