从旧版 API 迁移

在此页面上

概述

在此页面上，您可了解从旧版 API 迁移到当前 API 时必须执行的更改。此外，您还可了解当前 Java 驱动程序的独特功能，以及迁移到新 API 的好处。

打包为 mongodb-driver-legacy JAR 的旧版 API 包含传统旧版 Java 驱动程序，并使用该驱动程序早期版本中使用的命名规范。

当前 API（封装为 mongodb-driver-sync JAR）包含当前的同步 Java 驱动程序。它将 MongoCollection 接口作为 CRUD 操作的入口点。它不包含旧版 API。

要从旧版 API 迁移到当前 API，请确保代码不再引用旧版 API，必要时更新代码。然后，在应用程序依赖项中，用当前 API JAR 替换旧版 API 以及任何包含它的 uber JAR。

除更新应用程序以处理所有必要的更改之外，在将其投入到生产环境之前，请务必检查各选项和返回值中是否存在任何其他差异。

您可以继续在新的 MongoDB Server 版本中使用旧版 API。不过，旧版 API 不支持 MongoDB Server 3.0 或更高版本所引入的任何更新。此外，旧版 API 不支持当前 Java 驱动程序的某些功能。一些仅在非旧版 API 中提供的功能包括：

要了解当前 API 的更多功能，请参阅新增功能。

下表显示了旧版 API 和当前 API 中类和方法名称的大部分变更。

遗留	Current
MongoClientOptions	MongoClientSettings
new MongoClient()	MongoClients.create()
MongoClient.getDB()	MongoClient.getDatabase()
db	MongoDatabase
DBCollection	MongoCollection<>
DBCursor	MongoCursor
DBCollection.findOne()	`MongoCollection.find().first()` 有关这些方法，请参阅以下 API 文档页面： find() first()
DBCollection.insert()	使用以下方法之一： MongoCollection.insertOne() MongoCollection.insertMany()
DBCollection.update()	使用以下方法之一： MongoCollection.updateOne() MongoCollection.updateMany() MongoCollection.replaceOne()
DBCollection.remove()	使用以下方法之一： MongoCollection.deleteOne() MongoCollection.deleteMany()
DBCollection.count()	使用以下方法之一： MongoCollection.countDocuments() MongoCollection.estimatedDocumentCount()
DBCollection.findAndModify()	使用以下方法之一： MongoCollection.findOneAndUpdate() MongoCollection.findOneAndReplace() MongoCollection.findOneAndDelete()
查询构建器	筛选器

除上述列项外，还可考虑以下变更：

当前 API 使用 Options 类和方法链，而不是重载方法。
当前 API 在驱动程序版本 4.0 及更高版本中默认使用宽松 JSON 格式。如果应用程序依赖于严格 JSON 格式，请在读取或写入数据时使用严格模式。请参阅文档数据格式：扩展 JSON 指南，了解如何在当前 API 中指定 JSON 格式。
对于当前 API 中的 MongoCollection，默认通用类型是 org.bson.Document。如果 BasicDBObject 可以简化迁移，则您可以将其指定为类型参数。
在当前 API 中，您传递给 aggregate() 方法的聚合管道接受扩展 Bson 接口的对象列表，而在旧版 API 中，它接受扩展 DBObject 接口的对象列表。
API 之间的方法签名也有所不同。请参阅以下 API 文档了解更多信息：
- aggregate() 当前 API 中的方法
- aggregate() 旧版 API 中的方法
- Bson 接口
- DBObject 接口