Stable API

什么是 Stable API 以及是否应使用它？

MongoDB Stable API（以前标记为 Versioned API）允许随意升级 MongoDB Server，并确保不同 MongoDB 版本之间的行为更改不会破坏您的应用程序。

MongoDB 5.0 将引入 Stable API，以便应用程序与 MongoDB Server 产品进行通信。Stable API 允许指定应用程序要对其运行的 MongoDB API 版本。

Stable API 可为应用程序提供长期 API 稳定性，并支持更频繁的发布和自动服务器升级。如此一来，您的应用程序便可利用快速发布的功能，而无需冒险执行会破坏向后兼容性的更改。

即使您没有显式指定 apiVersion，驱动程序连接的默认行为将继续按预期运行。

Stable API 包含应用程序用于读写数据、创建集合和索引以及执行其他常见任务的部分 MongoDB 命令。

向后兼容性保证

您的应用程序不会因服务器升级而发生重大行为变化。只要新服务器支持您指定的 API 版本，该保证就有效。

为保证向后兼容性，应用程序必须：

• 声明 API 版本

• 只能使用指定 API 版本支持的命令和功能

• 使用受支持的官方驱动程序版本进行部署

声明 API 版本

➤ 使用右上角的选择语言下拉菜单来设置本页面上示例的语言。

要使用稳定版 API，请升级到最新的驱动程序并创建应用程序的 MongoClient：

"1" 是目前唯一可用的 API 版本。

默认情况下，客户端是 非严格的。 非严格客户端允许您运行任何命令，无论它是否属于稳定 API。

检查客户端 API 版本

使用 serverStatus 命令检查是否存在应用程序的已配置 API 版本。对于连接到 MongoDB 实例的每个应用程序，apiVersions 文档中均会显示一个 appname。

有关更多信息，请参阅 metrics.apiVersions。

db.runCommand( { serverStatus: 1 } ).metrics.apiVersions

创建严格的客户端

严格的客户端会拒绝 Stable API 之外的所有命令。尝试使用 Stable API 之外的命令将收到APIVersionError响应。

使用示例代码创建严格的客户端：

迁移到稳定版 API 命令

要迁移应用程序以使用稳定版 API，您必须：

1. 使用新的 MongoClient 选项运行应用程序的测试套件。

2. 确定您正在使用的哪些命令和功能不属于 Stable API。

3. 迁移到稳定 API 中的替代命令和功能。

一旦您的应用程序仅使用 Stable API 中定义的命令和功能，便可使用新的 MongoClient 选项重新部署它，并确信未来的服务器升级不会对您的应用程序产生负面影响。

如何使用 Stable API 之外的命令和功能

要使用 Stable API 之外的命令和功能，可使用非严格客户端连接到您的部署。默认情况下，客户端为非严格客户端。

要创建非严格客户端，请使用以下示例代码：

通过使用此非严格客户端，可运行 Stable API 之外的命令。例如，此非严格客户端允许运行 createUser 命令。

Stable API 命令

Stable API V1 中包含的数据库命令取决于您使用的 MongoDB 版本。要查看 Stable API 中包含的数据库命令及其引入的 MongoDB 版本，请参阅 Stable API 变更日志。

参数

您可以在应用程序的 MongoDB 驱动程序连接代码中为 Stable API 指定以下可选参数。如需获取更多信息，请查看您在应用程序中使用的驱动程序的 MongoDB 驱动程序文档：

行为

Stable API 错误响应

此表显示了针对有问题 Stable API 请求的错误响应。