Stable API

Overview

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

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

如要了解更多详细信息，以及所涵盖的命令列表，请参阅关于 Stable API 的 MongoDB 参考页面。

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

在 MongoDB 客户端上启用稳定 API

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

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

• 使用 ServerApi.Builder 助手类构建一个 ServerApi 实例。

• 使用 ServerApiVersion 类中的常量指定 Stable 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);

'Unrecognized field 'apiVersion' on server...

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

• ServerApi

• ServerApi.Builder

• ServerApiVersion

• ServerAddress

• MongoClientSettings

• MongoClientSettings.Builder

• MongoClients.create()

• MongoClient

Stable API 选项

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

以下示例演示如何通过 ServerApi.Builder 上的链接方法为 ServerApi 的实例设置两个选项：

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

如需进一步了解这个部分中的选项，请参阅以下 API 文档：

• strict()

• deprecationErrors()