稳定API

本页内容

概述

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

注意

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

如果您连接的所有MongoDB服务器都支持此功能，则应仅使用稳定API功能。

概述

在本指南中，您可以了解如何在连接到MongoDB实例或副本集时指定稳定API。您可以使用稳定API功能强制服务器使用与指定API版本兼容的行为。API版本定义了它所涵盖的操作的预期行为和服务器响应的格式。如果您更改到不同的API版本，操作不一定兼容，服务器响应也不一定相似。

当您使用官方MongoDB驱动程序中的稳定API功能时，您可以在不担心稳定API所涵盖的命令的向后兼容性问题的情况下更新您的驱动程序或服务器。

有关更多信息（包括它所涵盖的命令列表），请参阅MongoDB参考页面上的稳定API

以下各节描述了如何为您 MongoDB 客户端启用稳定API以及您可以指定的选项。

在MongoDB客户端上启用稳定API

要启用稳定API，您必须在MongoDB客户端的设置中指定一个API版本。一旦您使用指定的API版本实例化一个MongoClient实例，您使用该客户端运行的所有命令都将使用该版本的稳定API。

提示

要运行使用多个稳定API版本的命令，请使用该版本实例化一个单独的客户端。

要运行不被稳定API覆盖的命令，请确保禁用了“严格”选项。有关更多信息，请参阅有关稳定API选项的部分。

以下示例展示了如何通过以下操作实例化一个设置稳定API版本并连接到服务器的MongoClient：

使用ServerApi.Builder辅助类构建一个ServerApi实例。
使用ServerApiVersion类中的常量指定一个稳定API版本。
使用MongoClientSettings.Builder类构建一个MongoClientSettings实例。
使用ServerAddress实例指定要连接的服务器。
使用MongoClients.create()方法实例化一个MongoClient，并将您的MongoClientSettings实例作为参数传递。

ServerApi serverApi = ServerApi.builder()
        .version(ServerApiVersion.V1)
        .build();
// Replace the uri string with your MongoDB deployment's connection string
String uri = "<connection string uri>";
MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(uri))
        .serverApi(serverApi)
        .build();
MongoClient client = MongoClients.create(settings);

警告

如果您指定了一个API版本并连接到一个不支持稳定API的MongoDB部署，当在您的MongoDB部署上执行命令时，您的应用程序可能会抛出异常。如果您使用了一个指定了API版本以查询不支持它的服务器的MongoClient，则您的查询可能会因包含以下文本的异常消息而失败：

'Unrecognized field 'apiVersion' on server...

有关本节中引用的方法和类的更多信息，请参阅以下API文档

稳定API选项

您可以根据以下表格启用或禁用与稳定API相关的可选行为。

选项名称	描述
严格	可选。当设置时，如果您调用不属于声明API版本的命令，驱动程序将抛出异常。默认值：false
DeprecationErrors	可选。当设置时，如果您调用在声明API版本中已弃用的命令，驱动程序将抛出异常。默认值：false

以下示例展示了如何通过在ServerApi.Builder上链式调用方法来设置ServerApi实例上的这两个选项

ServerApi serverApi = ServerApi.builder()
        .version(ServerApiVersion.V1)
        .strict(true)
        .deprecationErrors(true)
        .build();

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

企业身份验证

数据库和集合