Morphia：MongoDB 的 Java 对象映射库

数据分析 1.7k 449 Java 2026-11-15 在 GitHub 打开

将 Java 对象映射到 MongoDB 文档的对象文档映射（ODM）库，README 主要指向官方文档与路线图。

Morphia 是一个 Java 生态的 MongoDB 对象映射库，README 中的正文内容较少，主要提供官方文档、路线图、已解决问题列表和 Discord 社区的链接入口，并包含商标声明。具体 API、用法与版本信息需查阅其官方文档。

Star 趋势2026-11-07 — 2026-11-14当前 Stars 1.7k

#java #kotlin #mongodb #odm

项目信息

所有者: MorphiaOrg
Star: 1.7k
Fork: 449
开源协议: —
主要语言: Java
发布时间: 2013-04-25
最近更新: 2026-11-14

项目更新

Release 2.3.82023-09-09
本次更新以依赖升级为主，没有新增功能。核心变化是 MongoDB Java 驱动从 4.8.1 升到 4.10.2，意味着可对接更新的服务器特性与修复；Jackson 升至 2.15.2，SLF4J 升至 2.0.9，运行时日志与序列化依赖同步跟进。构建侧同步更新了 Maven 3.9.4、Dokka 1.9.0、Hibernate Validator 8.0.1 等插件与工具链。对使用者而言，升级后建议留意驱动版本变化带来的行为差异，其余属于例行维护。
Release 2.4.42023-09-09
v2.4.4 是一次依赖维护更新，没有功能改动：logback-classic 升到 1.4.11，asciidoctorj 升到 2.5.10，jsoup 升到 1.16.1。主要收益是拿到 jsoup 1.16 系列的解析修复与安全补丁，对使用者而言升级即可，无需改动任何代码。
Release 2.4.32023-09-07
Morphia 2.4.3（2023-08-27）是一个小版本修复。核心改动只有一处：修复 #2488 报告的 Bug——隐式复用 client session 导致抛出 IllegalStateException。此前在某些场景下框架会不经意地重复使用同一个会话，进而触发该异常，升级后即可规避。除此之外，本版主要做依赖升级：MongoDB 驱动从 4.9.0 升至 4.10.2，Kotlin 1.9.10、Jackson 2.15.2、byte-buddy 1.14.6、classgraph 4.8.162、hibernate-validator 8.0.1.Final、Testcontainers 1.19.0、Maven 3.9.4 也一并跟进。没有新增功能，也没有破坏性变更，受会话复用问题困扰的用户可以直接升级。完整变更记录：https://github.com/MorphiaOrg/morphia/compare/v2.4.2...v2.4.3
Version 2.4.02023-08-24
Morphia 2.4.0 发布，共修复 34 个问题。核心变化是引入了配置文件机制，原有的 MapperOptions 及一系列 API 随之弃用，包括 Mapper#mapPackage()、Datastore#enableDocumentValidation()、ensureCaps()、ensureIndexes()，以及字段/方法属性发现相关的配置项，后续版本会按新配置方式迁移。功能上，正则过滤 API 改为同时接收字段名和模式串；FindOptions 新增支持 Meta 与 Sort 参数的排序方法。修复方面值得一提：Conversions 工具类此前非线程安全，已解决；自定义枚举 Codec 大多数场景下不被调用、属性 Codec 通过 ServiceLoader 注册失效、实体子类的生命周期回调中断、Map 子类未校验键类型、嵌套路径解析误报未知元素等问题均已处理。生成的配置内容中 null 值显示问题也一并修掉。二进制已发布至 Maven Central，文档见 https://morphia.dev/morphia/2.4 。
Version 2.3.62023-08-24
Morphia 2.3.6 是 2.3 分支的一个小修版本，主要把 2.4 分支上的 #2447 修复回移到了 2.3 系列（#2449），用于解决对应的 bug。内容不多，适合仍在 2.3 分支上维护、暂时不想升级大版本的用户跟进。二进制包已发布至 Maven Central，完整文档与 Javadoc 可在 morphia.dev/morphia/2.3 获取。
Version 2.4.12023-08-24
Morphia 2.4.1 是 2.4 系列的首个补丁版本，主要解决两个遗留问题：此前 2.3.x 分支上的若干修复没有同步合入 2.4，本次补齐；同时把 2.3 上的索引错误处理逻辑前向移植过来，使索引创建出错时能给出更明确的反馈，而不是静默失败。如果你一直在用 2.3.x 并因为升级而丢过这些修复，可以直接升到这一版。二进制包已发布到 Maven Central，完整文档见 https://morphia.dev/morphia/2.4。
Version 2.3.72023-08-24
Morphia 2.3.7（2023-07-30）是个补丁版本，重点是把此前遗漏的修复同步到 2.3.x 分支：#2450 补上了未合并进该分支的修复，#2453 则将索引错误处理的改动前向移植过来——此前索引相关异常在 2.3.x 上的处理并不完整。另外例行把 maven.version 从 3.9.2 升到 3.9.3。二进制包已发布到 Maven Central，完整文档与 Javadoc 见 morphia.dev/morphia/2.3。
Version 2.4.22023-08-24
Morphia 2.4.2 是一个纯修复版本，只解决了一个问题：使用 update 相关功能时可能抛出 NullPointerException（#2472）。如果你之前在更新操作中碰到过这个崩溃，升级即可解决。二进制包已发布到 Maven Central，完整文档和 Javadoc 见 morphia.dev 的 2.4 版本页面。
Version 2.3.52023-06-24
Morphia 2.3.5 是一个修复版，共解决三个问题。最重要的一条是自定义枚举 Codec 在大多数场景下没有被调用（#2412），导致开发者为枚举注册的序列化逻辑形同虚设，本次修复后可正常生效。另一条是查找引用了已删除实体的对象时会触发 StackOverflow（#2382），这类残留引用此前会让应用直接崩溃，现在能被正确处理。#2412 同时作为回补修复合入 2.2 分支。建议升级到此版本。
Version 2.3.12023-06-01
Morphia 2.3.1（2023-04-18）共修复 13 个问题，主线是线程安全与查询校验。dev.morphia.mapping.codec.Conversions 此前并非线程安全，多线程下存在隐患；校验失败的查询现在会直接拒绝执行，Query.disableValidation() 对 update 操作也真正生效，Filters.where(javascriptExpr) 则不再校验 JS 表达式本身。崩溃类问题一并处理：泛型多态类型会触发 EntityModel 的 ArrayIndexOutOfBounds，嵌入实体中同一属性混存 string 与 long（2.2 可用、2.3 报错），以及 Datastore.merge 配合 unsetMissing 时数组含 null 元素导致的崩溃。功能上，UpdateOperation<T>.disableValidation() 回归；保存新文档时 @Id 会在 @PrePersist 之前填充。另修了 Filters.eq 缺少 @Nullable、null 值过滤问题，testcontainers 依赖不再泄漏给库使用者，核心生命周期注解的文档也做了补全。文档见 https://morphia.dev/morphia/2.3。