稳定 API

本页内容

概述

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

重要

要使用稳定 API 功能，您必须连接到运行 MongoDB Server 5.0 或更高版本的应用程序。

只有在您连接的所有 MongoDB 服务器都支持此功能时，才应使用稳定 API 功能。

概述

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

稳定API功能强制服务器使用与您指定的API版本兼容的行为。API版本定义了其覆盖的操作的预期行为和服务器响应的格式。根据您指定的API版本，操作和服务器响应可能会有所不同。

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

要了解服务器覆盖的命令，请参阅稳定API，在服务器手册中。

指定API版本

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

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

注意

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

API版本指定示例

以下示例在创建Client实例时设置稳定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结构体中设置字段来修改稳定API特性的行为。

虽然您可以直接在ServerApi结构体中设置字段，但您可以使用构建器设计模式更高效地定义结构体。

注意

设置选项

Rust驱动为创建一些结构体类型实现了构建器设计模式，包括ServerApi结构体。您可以使用每种类型的builder()方法，通过逐个链式调用选项构建器函数来构造选项实例。

字段	描述
`version`	(必需) 要使用的稳定API版本。使用`ServerApiVersion`枚举指定。唯一接受值为`V1`。类型: `ServerApiVersion`
`strict`	指示服务器是否对不属于API版本的特性返回错误。类型: `bool` 默认值: `false`
`deprecation_errors`	指示服务器是否对已弃用的特性返回错误。类型: `bool` 默认值: `false`

稳定API选项示例

此示例使用以下规范启用稳定API特性

使用稳定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)?;

重要

概述

指定API版本

注意

API版本指定示例

修改行为

注意

设置选项

稳定API选项示例

更多信息

API 文档