Docs 菜单
Docs 主页
/
语言
/
Javascript
/
Node.js
/
Fundamentals

Stable API

在此页面上

  • Overview
  • 在 MongoDB 客户端上启用稳定 API
  • Stable API 选项

注意

Stable API 功能需要 MongoDB Server 5.0 或更高版本。

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

Overview

在本指南中，您可以了解如何在连接 MongoDB 实例或副本集时指定 Stable API。您可以使用 Stable API 功能，强制服务器以与您指定的 API Version 相兼容的行为运行操作。API 版本定义了其涵盖的操作的预期行为以及服务器响应的格式。如您更改为其他 API 版本，操作的兼容性将不能被保证，服务器的响应也将无法保证相似。

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

请参阅 MongoDB 参考页面中与 Stable API 相关的部分，了解包括涵盖命令列表在内的更多信息。

以下部分介绍如何为 MongoDB 客户端启用 Stable API 以及您可以指定的选项。

在 MongoDB 客户端上启用稳定 API

要启用 Stable API，您必须在传递给 MongoClient 的 MongoClientOptions 中指定 API 版本。一旦您使用指定的 API 版本来实例化 MongoClient 实例，您使用该客户端运行的所有命令都将使用该版本的 Stable API。

提示

必须在以下位置为 Stable API 的每个版本创建新客户端：
要运行命令。

如要运行 Stable API 未涵盖的命令，请确保禁用“strict”选项。有关更多信息，请参阅 Stable API 选项 部分。

以下示例展示如何实例化 MongoClient ，它会通过执行以下操作设置 Stable API 版本并连接到服务器：

  • 指定要连接的服务器 URI。

  • 使用 ServerApiVersion 对象中的常量在 MongoClientOptions 对象中指定 Stable API 版本。

  • 实例化 MongoClient，从而将 URI 和 MongoClientOptions 传递给构造函数。

const { MongoClient, ServerApiVersion } = require("mongodb");
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
const client = new MongoClient(uri, { serverApi: ServerApiVersion.v1 });

警告

如果您指定 API 版本并连接到不支持 Stable API 的 MongoDB 服务器，则当连接到 MongoDB 服务器时，您的应用程序可能会抛出错误，并显示以下文本：

MongoParseError: Invalid server API version=...

有关本节中提到的方法和类的详细信息，请参阅以下 API 文档：

Stable API 选项

您可以启用或禁用与 Stable API 相关的可选行为，如下表所述。

选项名称
说明
版本
Required. Specifies the version of the Stable API.

Default: null
strict
Optional. When set, if you call a command that is not part of the declared API version, the driver raises an exception.

Default: false
deprecationErrors
Optional. When set, if you call a command that is deprecated in the declared API version, the driver raises an exception.

Default: false

以下示例展示如何设置 ServerApi 接口的选项。

const { MongoClient, ServerApiVersion } = require("mongodb");
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
const client = new MongoClient(uri,
    {
        serverApi: {
            version: ServerApiVersion.v1,
            strict: true,
            deprecationErrors: true,
        }
    });

有关本节中的选项的更多信息，请参阅以下 API 文档：

后退

为连接启用 TLS