稳定的 API

在本页

概述

启用稳定API
配置稳定API
API 文档

注意

稳定API功能需要MongoDB服务器5.0或更高版本。

概述

在本指南中，您可以了解如何在连接到MongoDB部署时指定稳定API兼容性。

稳定API功能强制服务器以与您指定的API版本兼容的行为运行操作。当您更新驱动程序或服务器时，API版本会发生变化，这可能会改变这些操作的行为。使用稳定API确保服务器响应的一致性，并为您的应用程序提供长期API稳定性。

以下各节介绍了如何为您的MongoDB客户端启用和自定义稳定API。有关稳定API的更多信息，包括支持的命令列表，请参阅稳定API MongoDB服务器手册。

启用稳定API

要启用稳定API，请执行以下步骤

构造一个mongocxx::options::server_api对象并指定一个稳定API版本。您必须使用在mongocxx::options::server_api::version枚举中定义的稳定API版本。目前，驱动程序仅支持版本1（k_version_1）。
构造一个mongocxx::options::client对象。将此对象的server_api_opts字段设置为在上一步骤中创建的server_api对象。
构造一个mongocxx::client对象，传入您的mongocxx::uri对象和上一步骤中创建的mongocxx::options::client对象。

以下代码示例显示了如何指定稳定API版本1

#include <mongocxx/instance.hpp>
#include <mongocxx/uri.hpp>
#include <mongocxx/client.hpp>
int main()
{
    mongocxx::instance instance;
    mongocxx::uri uri("mongodb://<hostname>:<port>");
    mongocxx::options::server_api server_api_options(mongocxx::options::server_api::version::k_version_1);
    mongocxx::options::client client_options;
    client_options.server_api_opts(server_api_options);
    mongocxx::client client(uri, client_options);
}

注意

创建指定API版本的 mongocxx::client 实例后，您使用此客户端运行的所有命令都使用指定的版本。如果您需要使用稳定API的多个版本运行命令，请创建一个新的 mongocxx::client 实例。

配置稳定API

下表描述了 server_api_options 类的属性。您可以使用这些属性来自定义稳定API的行为。

选项名称	描述
strict	可选。当 `true` 时，如果您调用不属于声明API版本的命令，驱动程序会抛出异常。默认值：`false`
deprecation_errors	可选。当 `true` 时，如果您调用已弃用的声明API版本的命令，驱动程序会抛出异常。默认值：`false`

以下代码示例显示了如何在使用 ServerApi 对象时使用这些参数

#include <mongocxx/instance.hpp>
#include <mongocxx/uri.hpp>
#include <mongocxx/client.hpp>
int main()
{
    mongocxx::instance instance;
    mongocxx::uri uri("mongodb://<hostname>:<port>");
    mongocxx::options::server_api server_api_options(mongocxx::options::server_api::version::k_version_1);
    server_api_options.strict(true);
    server_api_options.deprecation_errors(true);
    mongocxx::options::client client_options;
    client_options.server_api_opts(server_api_options);
    mongocxx::client client(uri, client_options);
}

API 文档

有关使用 C++ 驱动程序与稳定API的更多信息，请参阅以下 API 文档

压缩网络流量

下一步

连接池