稳定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涵盖的命令，请确保已禁用“strict”选项。有关更多信息，请参阅稳定API选项部分。

以下示例展示了您可以通过执行以下操作来实例化一个 MongoClient，该客户端设置稳定API版本并连接到服务器：

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

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

警告

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

'Unrecognized field 'apiVersion' on server...

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

稳定API选项

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

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

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

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

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

企业身份验证

下一步

数据库 & 集合