Docs Home → Node.js

Stable API

On this page本页内容

Note

The Stable API feature requires MongoDB Server 5.0 or later.Stable API功能需要MongoDB Server 5.0或更高版本。

You should only use the Stable API feature if all the MongoDB servers you are connecting to support this feature.如果您正在连接的所有MongoDB服务器都支持Stable API功能，则只应使用该功能。

Overview概述

In this guide, you can learn how to specify the Stable API when connecting to a MongoDB instance or replica set. 在本指南中，您可以学习如何在连接到MongoDB实例或副本集时指定Stable API。You can use the Stable API feature to force the server to run operations with behavior compatible with the specified API version. 您可以使用Stable API功能强一致性务器运行行为与指定API版本兼容的操作。An API version defines the expected behavior of the operations it covers and the format of server responses. API版本定义了它所涵盖的操作的预期行为以及服务器响应的格式。If you change to a different API version, the operations are not guaranteed to be compatible and the server responses are not guaranteed to be similar.如果更改为不同的API版本，则不能保证操作是兼容的，也不能保证服务器响应是相似的。

When you use the Stable API feature with an official MongoDB driver, you can update your driver or server without worrying about backward compatibility issues of the commands covered by the Stable API.当您将Stable API功能与官方MongoDB驱动程序一起使用时，您可以更新驱动程序或服务器，而无需担心Stable API所涵盖命令的向后兼容性问题。

See the MongoDB reference page on the Stable API for more information including a list of commands it covers.请参阅Stable API上的MongoDB参考页面，了解更多信息，包括它包含的命令列表。

The following sections describe how you can enable the Stable API for your MongoDB client and the options that you can specify.以下部分描述了如何为MongoDB客户端启用Stable API以及可以指定的选项。

Enable the Stable API on a MongoDB Client在MongoDB客户端上启用稳定的API

To enable the Stable API, you must specify an API version in the MongoClientOptions passed to your MongoClient. 要启用Stable API，必须在传递给MongoClient的MongoClientOptions中指定API版本。Once you instantiate a MongoClient instance with a specified API version, all commands you run with that client use that version of the Stable API.使用指定的API版本实例化MongoClient实例后，使用该客户端运行的所有命令都将使用该版本的Stable API。

Tip

If you need to run commands using more than one version of the Stable API, instantiate a separate client with that version.如果您需要使用一个以上版本的Stable API运行命令，请使用该版本实例化一个单独的客户端。

If you need to run commands not covered by the Stable API, make sure the "strict" option is disabled. 如果您需要运行Stable API未涵盖的命令，请确保禁用“严格”选项。See the section on Stable API Options for more information.有关更多信息，请参阅稳定API选项部分。

The example below shows how you can instantiate a MongoClient that sets the Stable API version and connects to a server by performing the following operations:下面的示例展示了如何实例化MongoClient，该客户端设置Stable API版本并通过执行以下操作连接到服务器：

  • Specify a server URI to connect to.指定要连接到的服务器URI。
  • Specify a Stable API version in the MongoClientOptions object, using a constant from the ServerApiVersion object.使用ServerApiVersion对象中的常量，在MongoClientOptions对象中指定稳定的API版本。
  • Instantiate a MongoClient, passing the URI and the MongoClientOptions to the constructor.实例化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 });
Warning

If you specify an API version and connect to a MongoDB server that does not support the Stable API, your application may throw an error when connecting to your MongoDB server with the following text:如果您指定了API版本并连接到不支持Stable API的MongoDB服务器，则您的应用程序在连接到MongoDB服务器时可能会抛出错误，并显示以下文本：

MongoParseError: Invalid server API version=...

For more information on the methods and classes referenced in this section, see the following API Documentation:有关本节中引用的方法和类的更多信息，请参阅以下API文档：

Stable API Options稳定的API选项

You can enable or disable optional behavior related to the Stable API as described in the following table.您可以启用或禁用与稳定API相关的可选行为，如下表所述。

Option Name选项名称Description描述
versionRequired. 必要的。Specifies the version of the Stable API.指定稳定API的版本。


Default: null
strictOptional. 可选的。When set, if you call a command that is not part of the declared API version, the driver raises an exception.设置时，如果调用的命令不是声明的API版本的一部分，则驱动程序将引发异常。


Default: false
deprecationErrorsOptional. 可选的。When set, if you call a command that is deprecated in the declared API version, the driver raises an exception.设置时，如果调用的命令在声明的API版本中不推荐使用，则驱动程序将引发异常。
Default: false

The following example shows how you can set the options of the ServerApi interface.以下示例显示了如何设置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,
        }
    });

For more information on the options in this section, see the following API Documentation:有关本节中选项的更多信息，请参阅以下API文档：