稳定 API
注意
稳定API功能需要MongoDB服务器5.0或更高版本。
概述
在本指南中，您可以了解如何在连接到MongoDB部署时指定稳定API兼容性。
稳定API功能强制服务器以与您指定的API版本兼容的行为运行操作。使用稳定API确保服务器响应的一致性，并为您的应用程序提供长期API稳定性。
以下部分描述了如何为您的MongoDB客户端启用和自定义稳定API。有关稳定API的更多信息，包括它支持的命令列表，请参阅稳定API在MongoDB服务器手册中。
启用稳定API
要启用稳定API，请执行以下步骤
构建一个
ServerApi对象并指定一个稳定API版本。您必须使用在ServerApiVersion枚举中定义的稳定API版本。使用
MongoClientSettings.Builder类构建一个MongoClientSettings对象。使用
MongoClient.create()方法实例化一个MongoClient，并将您的MongoClientSettings实例作为参数传递。
以下代码示例展示了如何指定稳定API版本1
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版本的MongoClient实例，您使用该客户端运行的所有命令都将使用指定的版本。如果您必须使用多个稳定API版本运行命令，请创建一个新的MongoClient。
配置稳定API
以下表格描述了ServerApi类的参数。您可以使用这些参数来自定义稳定API的行为。
选项名称 | 描述 |
|---|---|
strict | 可选。当设置为 True时，如果调用不属于声明API版本的命令，驱动程序将引发异常。默认值：False |
deprecationErrors | 可选。当设置为 True时，如果调用在声明API版本中已弃用的命令，驱动程序将引发异常。默认值：False |
以下代码示例显示了如何通过在ServerApi.Builder上链式调用方法来设置ServerApi实例上的两个选项：
val serverApi = ServerApi.builder() .version(ServerApiVersion.V1) .strict(true) .deprecationErrors(true) .build()
故障排除
服务器上未识别的字段 'apiVersion'
Kotlin Sync 驱动程序如果指定了API版本并连接到一个不支持稳定API的MongoDB服务器，将引发此异常。请确保您连接到一个运行MongoDB Server v5.0或更高版本的部署。
提供apiStrict：true，但命令计数不在API版本中
如果您的MongoClient运行的操作不在您指定的稳定API版本中，Kotlin Sync驱动程序会引发此异常。为了避免此错误，请使用由指定的稳定API版本支持的替代操作，或者在构建您的ServerApi对象时将strict选项设置为False。
API文档
有关使用Kotlin Sync驱动程序与稳定API的更多信息，请参阅以下API文档