Stable API

在此页面上

Overview

指定 API 版本
API 版本规范示例
修改行为
稳定的 API 选项示例
更多信息
API 文档

重要

要使用 stable API 功能，必须连接到运行 MongoDB Server 5.0 或更高版本的部署。

仅当您连接的所有 MongoDB 服务器都支持 Stable API 功能时，方可使用此功能。

Overview

在本指南中，您可以了解如何在连接 MongoDB 实例或副本集时指定“Stable API”兼容性。

Stable API 功能会强制服务器使用与您指定的API 版本兼容的行为来运行操作。 API 版本定义了其涵盖的操作的预期行为以及服务器响应的格式。操作和服务器响应可能会有所不同，具体取决于您指定的 API 版本。

当您将 Stable API 功能与官方 MongoDB 驱动程序一起使用时，您可以更新驱动程序或服务器，而不必担心 Stable API 所涵盖的命令的向后兼容性问题。

要了解有关服务器所涵盖命令的更多信息，请参阅stable API MongoDB Server手册中的。

指定 API 版本

要指定 API 版本，请定义一个 ServerApi结构并将ClientOptions实例的server_api字段设置为此结构。 ServerApi结构体包含 API 版本和选项。要了解有关设置选项的更多信息，请参阅本指南的修改行为部分。

指定 API 版本后，客户端仅运行与该版本兼容的操作。

注意

MongoDB Rust 驱动程序仅支持 Stable API 版本 1。

API 版本规范示例

以下示例在实例化Client并连接到服务器时设置 Stable API 版本。

let mut client_options = ClientOptions::parse(uri).await?;
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
client_options.server_api = Some(server_api);
let client = Client::with_options(client_options)?;

修改行为

您可以通过设置ServerApi结构中的字段来修改 Stable API 功能的行为。

虽然您可以手动设置 ServerApi 结构体中的字段，但可以使用构建器设计模式更有效地定义该结构体。

注意

设置选项

Rust驾驶员实现了用于创建某些结构体类型（包括ServerApi结构体）的 Builder 设计模式。您可以使用每种类型的builder()方法，通过逐个链接选项构建器函数来构造选项实例。

字段	说明
`version`	(Required) The Stable API version to use. Specified with the `ServerApiVersion` enum. The only accepted value is `V1`. Type: `ServerApiVersion`
`strict`	Indicates whether the server returns errors for features that aren't part of the API version. Type: `bool` Default: `false`
`deprecation_errors`	Indicates whether the server returns errors for deprecated features. Type: `bool` Default: `false`

稳定的 API 选项示例

此示例启用具有以下规范的 Stable API 功能：

使用 Stable API 版本 1
针对不属于版本 1 的功能返回错误
返回已弃用功能的错误

let mut client_options = ClientOptions::parse(uri).await?;
let server_api = ServerApi::builder()
    .version(ServerApiVersion::V1)
    .strict(true)
    .deprecation_errors(true)
    .build();
client_options.server_api = Some(server_api);
let client = Client::with_options(client_options)?;

重要