数据建模和序列化

Overview

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

Rust语言使用静态类型系统，但BSON具有动态模式。为了处理Rust类型和BSON之间的转换，驱动程序和 bson crate 集成了 Serde框架的功能。

提示

bson crate 与 mongodb crate 一起导出。要学习；了解如何安装包，请参阅serde crates.io包注册表中的 serde。

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

本指南包括以下部分：

通用类型参数描述了集合参数化和数据建模
自定义数据模型描述了如何定义自定义 Rust 类型来对集合中的数据进行建模
自定义序列化描述了如何使用属性修改默认序列化和反序列化行为，并提供了示例
附加信息提供了本指南中提到的类型和方法的资源和 API 文档链接

泛型类型参数

创建Collection实例时，必须指定泛型类型参数来表示对集合中的文档进行建模的数据类型。要学习；了解有关指定泛型类型参数的更多信息，请参阅数据库和集合指南中的集合参数化部分。

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

自定义数据模型

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

#[derive(Serialize, Deserialize)]

自定义结构示例

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

#[derive(Serialize, Deserialize)]
struct Article {
    title: String,
    date: DateTime,
    content: String,
    content_embeddings: Vector,
}

提示

向量类型

从 bson 库 v2.14 开始，您可以使用 bson::binary::Vector 类型来表示数值向量。

由于此类型被序列化为BSON二进制向量，因此使用 Vector 可以提高存储效率。要学习；了解更多信息，请参阅BSON规范。

以下代码访问将 Article 结构作为泛型类型参数的 articles集合：

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

由于 Collection实例已使用 Article 结构进行参数化，因此您可以使用该类型执行增删改查操作。以下代码将一个 Article实例插入到集合中：

let article = Article {
    title: "Maintaining Your Garden in Winter".to_string(),
    date: DateTime::now(),
    content: "As fall winds down, you might be wondering what you should be doing in your garden in the coming months ...".to_string(),
    content_embeddings: Vector::Float32(vec! [0.01020927,-0.011224265,0.015686288,-0.018586276,-0.023160344])
};
my_coll.insert_one(article).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 库中的辅助工具类型实现常见序列化任务的示例。

这些示例展示了以下方法：

BSON 3.0：使用 serde_with crate 提供的 serde_as 注解，提供额外的灵活性和组合功能
BSON 2.x：使用传统的 serialize_with 辅助程序

BSON 2.15 是默认版本。选择与您的BSON crate版本匹配的方法。

要在应用程序中使用BSON 3.0，请在项目的 Cargo.toml 中将其作为一项功能启用，类似于以下内容：

[dependencies.mongodb]
version = "3.3.0"
features = ["bson-3"]

启用BSON 3.0 后，您可以使用 serde_as。要使用 serde_as，您必须将其导入应用程序，如以下代码所示：

use serde_with::serde_as;

要查看 Serde 辅助函数的完整列表，请参阅serde_helpers API 文档。

将字符串序列化为 ObjectId

您可能希望将文档中的 _id字段表示为结构体中的十六进制字符串。要将十六进制字符串转换为 ObjectId BSON类型，请根据您的BSON crate 版本选择 BSON 3.0 (serde_as) 或 BSON 2.x (serialize_with)标签页以获取相应的代码示例：

使用带有 serde_as 注解的 bson::serde_helpers::object_id::FromHexString 类型：

#[serde_as]
#[derive(Serialize, Deserialize)]
struct Order {
    #[serde_as(as = "object_id::FromHexString")]
    _id: String,
    item: String,
}

使用 serialize_hex_string_as_object_id 辅助程序函数：

#[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 格式的 string。选择 BSON 3.0(serde_as) 或 BSON 2.x (serialize_with)标签页，查看此转换的相应代码示例。

使用带有 serde_as 注解的 bson::serde_helpers::datetime::AsRfc3339String 类型：

#[serde_as]
#[derive(Serialize, Deserialize)]
struct Order {
    item: String,
    #[serde_as(as = "datetime::AsRfc3339String")]
    delivery_date: DateTime,
}

使用 serialize_bson_datetime_as_rfc3339_string 辅助程序函数：

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

选择 BSON 3.0(serde_as) 或 BSON 2.x (serialize_with)标签页，查看驱动程序如何将示例Order 结构序列化为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 类型。选择相应代码示例的 BSON 3.0(serde_as) 或 BSON 2.x (serialize_with)标签页，以指定此转换。

使用带有 serde_as 注解的 bson::serde_helpers::u32::AsF64 类型：

#[serde_as]
#[derive(Serialize, Deserialize)]
struct Order {
    item: String,
    #[serde_as(as = "u32::AsF64")]
    quantity: u32,
}

使用 serialize_u32_as_f64 辅助程序函数：

#[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文档。