本文详解如何解决 Morphia 1.x 与新版 MongoDB Java 同步驱动（mongodb-driver-sync 4.6.1+）不兼容的问题：核心方案是升级至 Morphia 2.x，并改用 morphia-core 模块及新 API，彻底告别已废弃的 com.mongodb.MongoClient。
本文详解如何解决 morphia 1.x 与新版 mongodb java 同步驱动（mongodb-driver-sync 4.6.1+）不兼容的问题：核心方案是升级至 morphia 2.x，并改用 `morphia-core` 模块及新 api，彻底告别已废弃的 `com.mongodb.mongoclient`。
MongoDB 官方自 4.0 版本起逐步重构 Java 驱动架构，于 4.3+ 版本正式弃用旧版 mongo-java-driver（含 com.mongodb.MongoClient），全面转向模块化新驱动（如 mongodb-driver-sync），其客户端类型统一为 com.mongodb.client.MongoClient。而 Morphia 1.x 系列（如 1.6.x）仍强依赖旧驱动中的 com.mongodb.MongoClient，导致调用 Morphia.createDatastore(client, dbName) 时编译失败或 ClassCastException —— 即使你正确初始化了 MongoClients.create()，也无法向下转型。
✅ 正确解法：升级到 Morphia 2.x
Morphia 自 2.0.0 版本起完全重写，原生支持新驱动 API，并拆分为 morphia-core（核心 ORM 功能）和 morphia-annotations（可选注解支持）等模块。它不再引用任何已废弃类，而是直接接受 com.mongodb.client.MongoClient 实例。
? 依赖配置（以 Gradle 为例）
// 移除旧依赖（如 morphia:1.6.1 或 mongo-java-driver） // 添加 Morphia 2.x 核心依赖（推荐使用最新稳定版） implementation 'dev.morphia.morphia:morphia-core:2.3.0' // 同时确保 MongoDB 同步驱动已引入（Morphia 2.x 不再自带驱动） implementation 'org.mongodb:mongodb-driver-sync:4.11.2' // 与 Morphia 2.3.0 兼容推荐版本
✅ 初始化 Datastore 的正确方式（Morphia 2.x）
import dev.morphia.Morphia;
import dev.morphia.Datastore;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.ConnectionString;
public class MorphiaConfig {
public static Datastore createDatastore() {
// 1. 创建新驱动 MongoClient（类型：com.mongodb.client.MongoClient）
MongoClient mongoClient = MongoClients.create(
new ConnectionString("mongodb://localhost:27017")
);
// 2. 构建 Morphia 实例（无需指定包扫描，可在后续注册实体）
Morphia morphia = new Morphia();
// 3. 注册实体类（可选，但推荐显式声明）
morphia.mapPackage("com.example.model"); // 扫描含 @Entity 的包
// 4. 创建 Datastore —— 直接传入 com.mongodb.client.MongoClient ✅
return morphia.createDatastore(mongoClient, "my_database");
}
}
⚠️ 关键注意事项：
- Morphia 2.x 不兼容 1.x 的 API：Mapper、Datastore.createQuery() 返回类型、查询语法（如 filter() 替代 criteria()）均有调整，需按 官方迁移指南 更新代码；
- morphia-core 是唯一必需模块；morphia-annotations 已整合进 core，无需额外引入；
- 若使用 Spring Boot，建议搭配 spring-boot-starter-data-mongodb + 手动集成 Morphia，或考虑直接使用 Spring Data MongoDB（Morphia 2.x 未提供官方 Starter）；
- 连接池、SSL、认证等高级配置仍通过 MongoClientSettings 设置，与驱动层解耦，Morphia 仅消费 MongoClient 实例。
? 总结：该问题本质是生态演进导致的版本断层。没有“绕过”方案（如反射或桥接封装），唯一健壮、可维护的路径是升级 Morphia 至 2.x 并同步更新驱动依赖。此举不仅解决兼容性问题，更能获得响应式支持（Morphia 2.2+ 提供实验性 Reactive API）、更优的泛型处理、以及持续的安全与性能更新。
