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。
提示
如果需要使用多个 Stable API 版本运行命令，请使用该版本实例化一个单独的客户端。
如果您需要运行stable API未涵盖的命令，请确保禁用“strict”选项。 有关更多信息，请参阅有关stable API选项的部分。
以下示例展示了如何实例化一个MongoClient ，它会通过执行以下操作来设置 Stable API 版本并连接到服务器：
使用
ServerApi.Builder助手类构建一个ServerApi实例。使用
ServerApiVersion类中的常量指定 Stable 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 版本并连接到不支持 stable API 的 MongoDB Server，则您的应用程序在 MongoDB Server 上执行命令时可能会引发异常。如果使用指定 API 版本的MongoClient来查询不支持它的服务器，则查询可能会失败，并显示包含以下文本的异常消息：
'Unrecognized field 'apiVersion' on server...
有关本节中提到的方法和类的详细信息，请参阅以下 API 文档：
Stable API 选项
您可以启用或禁用与 Stable API 相关的可选行为，如下表所述。
选项名称 | 说明 |
|---|---|
严格 | 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.Builder 上的链接方法为 ServerApi 的实例设置两个选项：
val serverApi = ServerApi.builder() .version(ServerApiVersion.V1) .strict(true) .deprecationErrors(true) .build()
有关本节中的选项的更多信息，请参阅以下 API 文档：