/ /

数据建模和序列化

Overview

在本指南中，您可以了解 Rust 驱动程序如何处理 BSON 和 Rust 类型之间的转换。将 Rust 类型转换为 BSON 的过程称为序列化，而相反的过程称为反序列化。

Rust语言使用静态类型系统，但BSON具有动态模式。为了处理Rust类型和BSON之间的转换，驱动程序和 bson 库集成了 Serde框架的功能。要学习；了解如何安装serde crate，请参阅 crates.iocrate 注册表中的 serde。

通过将 serde 库的功能整合到您的应用程序中，您可以使用自定义 Rust 类型（如结构体和枚举）来对数据进行建模。

本指南包括以下部分：

Generic Type Parameter describes collection parameterization and data modeling
Custom Data Model describes how to define custom Rust types to model data in your collections
Custom Serialization describes how to modify default serialization and deserialization behavior by using attributes and provides examples
附加信息提供了本指南中提到的类型和方法的资源和 API 文档链接

泛型类型参数

Collection创建instance实例时，必须指定泛型类型参数来表示对collection中的文档进行建模的数据类型。To learn more about specifying a generic type parameter, see the Collection Parameterization section of the guide on Databases and Collections.

我们建议您定义并使用自定义类型来对集合的数据进行建模，而不是使用Document类型。

自定义数据模型

您可以使用任何实现serde包中的Serialize和Deserialize特征的 Rust 数据类型作为Collection实例的泛型类型参数。要实现Serialize和Deserialize特征，您必须在定义 Rust 类型之前包含以下derive属性：

#[derive(Serialize, Deserialize)]

自定义结构示例

以下代码定义了一个示例Vegetable结构，用于实现serde序列化特征：

#[derive(Serialize, Deserialize)]
struct Vegetable {
    name: String,
    category: String,
    tropical: bool,
}

以下代码访问将Vegetable作为泛型类型参数的vegetables集合：

let my_coll: Collection<Vegetable> = client
    .database("db")
    .collection("vegetables");

由于Collection实例已使用Vegetable结构进行参数化，因此您可以使用该类型执行 CRUD 操作。 Vegetable以下代码将一个实例插入到collection中：

let calabash = Vegetable {
    name: "calabash".to_string(),
    category: "gourd".to_string(),
    tropical: true,
};
my_coll.insert_one(calabash, None).await?;

多个参数化

如果您的集合包含多个模式，则可以定义自定义类型来对每种数据类型进行建模，并为每种类型创建原始Collection实例的克隆。您可以使用clone_with_type()方法创建Collection实例的克隆。

假设您最初使用名为Square的结构体参数化了一个collection，但您后来意识到想要将由Circle结构体建模的不同类型的数据插入到该collection中。以下代码将Square类型的collection参数化，然后创建Circle类型参数化的collection的克隆：

let shapes_coll: Collection<Square> = client
    .database("db")
    .collection("shapes");
// ... perform some operations with Square
let shapes_coll: Collection<Circle> = shapes_coll.clone_with_type();
// ... perform some operations with Circle

自定义序列化

您可以使用serde crate 中的属性修改 Rust 驱动程序的默认序列化和反序列化行为。属性是附加到字段的结构体或枚举变体的可选元数据片段。

serde包提供serialize_with和deserialize_with属性，它们将辅助函数作为值。这些辅助函数可自定义特定字段和变体的序列化和反序列化。要在字段上指定属性，请在字段定义之前包含该属性：

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(serialize_with = "<helper function>")]
    field1: String,
    // ... other fields
}

在以下部分中，您可以找到使用 bson 库中的辅助函数实现常见序列化任务的示例。要查看这些辅助函数的完整列表，请参阅serde_helpers API文档。

将字符串序列化为 ObjectId

您可能希望将文档中的_id字段表示为结构体中的十六进制字符串。要将十六进制字符串转换为ObjectId BSON 类型，请使用serialize_hex_string_as_object_id辅助函数作为serialize_with属性的值。以下示例将serialize_with属性附加到_id字段，以便驱动程序将十六进制字符串序列化为ObjectId类型：

#[derive(Serialize, Deserialize)]
struct Order {
    #[serde(serialize_with = "serialize_hex_string_as_object_id")]
    _id: String,
    item: String,
}

要查看驱动程序如何将示例Order结构序列化为 BSON，请从以下Struct和BSON标签页中进行选择：

let order = Order {
    _id: "6348acd2e1a47ca32e79f46f".to_string(),
    item: "lima beans".to_string(),
};

{
  "_id": { "$oid": "6348acd2e1a47ca32e79f46f" },
  "item": "lima beans"
}

将 DateTime 序列化为字符串

您可能希望将文档中的DateTime字段值表示为 BSON 中的 ISO 格式的字符串。要指定此转换，请使用serialize_bson_datetime_as_rfc3339_string辅助函数作为附加到具有DateTime值的字段的serialize_with属性的值。以下示例将serialize_with属性附加到delivery_date字段，以便驱动程序将DateTime值序列化为字符串：

#[derive(Serialize, Deserialize)]
struct Order {
    item: String,
    #[serde(serialize_with = "serialize_bson_datetime_as_rfc3339_string")]
    delivery_date: DateTime,
}

要查看驱动程序如何将示例Order结构序列化为 BSON，请从以下Struct和BSON标签页中进行选择：

let order = Order {
    item: "lima beans".to_string(),
    delivery_date: DateTime::now(),
};

{
  "_id": { ... },
  "item": "lima beans",
  "delivery_date": "2023-09-26T17:30:18.181Z"
}

将 u32 序列化为 f64

您可能希望将文档中的u32字段值表示为 BSON 中的f64或Double类型。要指定此转换，请使用serialize_u32_as_f64辅助函数作为附加到具有u32值的字段的serialize_with属性的值。以下示例将serialize_with属性附加到quantity字段，以便驱动程序将u32值序列化为Double类型：

#[derive(Serialize, Deserialize)]
struct Order {
    item: String,
    #[serde(serialize_with = "serialize_u32_as_f64")]
    quantity: u32,
}

注意

u32值的 BSON Double表示形式与原始值相同。

其他属性和模块

除辅助函数外， bson库还提供处理序列化和反序列化的模块。要选择用于特定字段或变体的模块，请将with属性的值设置为模块的名称：

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(with = "<module>")]
    field1: u32,
    // ... other fields
}

有关这些模块的完整列表，请参阅 serde_helpers API文档。

serde 库提供了许多其他属性来自定义序列化。以下列表描述了一些常见属性及其功能：

rename：使用指定名称而不是 Rust 结构或变体名称对字段进行序列化和反序列化
skip：不对指定字段进行序列化或反序列化
default：如果反序列化期间不存在任何值，则使用以下内容中的默认值： Default::default()

有关 serde 属性的完整列表，请参阅 serde 属性API文档。