Jongo对象映射指南Jackson让POJO与MongoDB文档无缝互转【免费下载链接】jongoQuery in Java as in Mongo shell项目地址: https://gitcode.com/gh_mirrors/jo/jongoJongo 是一个轻量级 Java 框架它的核心能力是通过内置的 Jackson 对象映射让你的 POJO 与 MongoDB 文档实现无缝互转——保存对象时自动序列化为 BSON查询时自动反序列化回 Java 对象全程零样板代码。本文带你快速掌握 Jongo 对象映射的完整用法。为什么需要 Jongo 对象映射在传统 Mongo Java Driver 中读写数据往往要手动组装DBObject、手工put/get字段代码冗长且容易出错。Jongo 解决了这个问题痛点Jongo 的解决方案手动组装 DBObjectPOJO 自动序列化为 BSON结果集手工转换查询结果自动反序列化为对象_id字段难处理自动填充与映射主键查询语言不直观直接复制粘贴 Mongo shell 查询语句 核心理念Query in Java as in Mongo shell——用 Java 写出和 Mongo shell 一样的查询体验。快速上手三步完成对象映射第 1 步引入依赖在pom.xml中添加依赖说明见项目根目录 pom.xmldependency groupIdorg.jongo/groupId artifactIdjongo/artifactId version1.5.2/version /dependencyJongo 内置了 Jackson支持 2.9 ~ 2.19 版本区间无需额外配置序列化库。第 2 步创建 Jongo 实例构造 Jongo 时如果不指定 Mapper它会自动使用 Jackson 映射器见src/main/java/org/jongo/Jongo.javaJongo jongo new Jongo(db); MongoCollection users jongo.getCollection(users);第 3 步直接保存和查询对象users.save(user); User u users.findOne(name, Alice).as(User.class);就这么简单——保存时 Jongo 将User对象序列化为 BSON 文档查询时再把文档还原为User对象。核心机制Jackson 映射引擎的工作原理对象映射的核心是 JacksonMapper它实现 Mapper 接口提供四类能力Marshaller序列化器POJO → BSON 文档Unmarshaller反序列化器BSON 文档 → POJOObjectIdUpdater写入前自动为主键字段填充 ObjectIdQueryFactory把 Mongo shell 风格查询字符串编译为查询对象真正执行转换的是 JacksonEngine它通过自定义的MongoBsonFactory让 Jackson 直接读写 BSON 字节流而不经过 JSON 字符串中转性能与原生驱动相当。主键映射MongoId 注解的用法MongoDB 文档默认以_id字段作为主键。在 POJO 中用MongoId注解见src/main/java/org/jongo/marshall/jackson/oid/MongoId.java标记对应属性即可public class User { MongoId private ObjectId id; private String name; // getter / setter }保存时 Jongo 会自动生成 ObjectId 填入该字段读取时自动把文档的_id映射回来。⚠️ 注意旧版Id注解src/main/java/org/jongo/marshall/jackson/oid/Id.java已被标记为废弃与外部 ObjectMapper 混用时可能产生副作用新项目请直接使用MongoId。自定义配置灵活定制映射行为通过jacksonMapper()构建器见 AbstractMappingBuilder可以深度定制映射规则Mapper mapper jacksonMapper() .enable(DeserializationFeature.READ_UNKNOWN_PROPERTIES) .withView(View.Public.class) // 基于视图控制序列化字段 .build(); Jongo jongo new Jongo(db, mapper);常用配置项registerModule注册自定义 Jackson 模块addSerializer/addDeserializer为特定类型添加自定义序列化/反序列化器withView使用 Jackson 视图机制控制哪些字段被读写setVisibilityChecker调整字段可见性规则enable/disable开关 Jackson 各项特性配置类的完整实现位于src/main/java/org/jongo/marshall/jackson/configuration/目录包含PropertyModifier、AnnotationModifier、VisibilityModifier等组件都遵循单一职责设计便于阅读和扩展。实战场景典型对象映射用法场景一查询返回 List 对象ListUser result users.find(age #, 30).asList(User.class);查询语句可以直接使用 Mongo shell 的 EJSON 语法无需学习新的查询 API。场景二按主键查询与更新User u users.findOne(objectId).as(User.class); users.update(objectId).set(name, Bob);相关方法实现见 MongoCollectionfindOne、update、save、insert、remove全部支持直接传 ObjectId。场景三嵌套对象与多态POJO 中的嵌套对象和集合字段会被递归映射。多态场景父类引用指向子类实例的映射测试参考src/test/java/org/jongo/PolymorphismTest.java和NestedPolymorphismTest.javaJongo 对这类复杂结构的处理均有完整保障。对象映射行为测试如何验证你的映射配置项目测试目录提供了大量映射行为的参考用例测试文件验证内容src/test/java/org/jongo/DocumentMarshallingTest.java文档序列化的基础行为src/test/java/org/jongo/marshall/jackson/JacksonEngineTest.java引擎序列化/反序列化src/test/java/org/jongo/marshall/jackson/JacksonAnnotationsHandlingTest.javaJackson 注解处理src/test/java/org/jongo/JacksonAnnotationsHandlingTest.java注解映射场景src/test/java/org/jongo/InsertTest.java保存时的主键自动填充 建议修改映射配置后运行这些测试能快速验证行为是否符合预期。常见问题速查Q保存对象时_id没有自动填充检查主键字段类型是否为ObjectId并确认已加MongoId注解且未使用废弃的Id。Q查询结果反序列化报 MarshallingException查看src/main/java/org/jongo/marshall/MarshallingException.java中的异常信息通常是 POJO 字段类型与文档中存储的类型不匹配。Q能用自己的 ObjectMapper 吗可以。构建jacksonMapper()时传入自定义ObjectMapper即可但需注意此时不会自动注册内置的 BSON 模块可能需要手动registerModule(new BsonModule())见src/main/java/org/jongo/marshall/jackson/bson4jackson/BsonModule.java。总结Jongo 的对象映射体系让 Java 开发者可以彻底告别手动组装 DBObject 的苦役零配置起步——默认 Jackson 映射器开箱即用注解驱动——MongoId一个注解搞定主键深度可定制——构建器模式覆盖序列化、视图、可见性等所有场景性能可靠——直接操作 BSON 字节流与原生驱动同速从 README.md 可以看到Jongo 的三大支柱正是忠实地还原 Mongo shell 查询体验、面向对象的读写、以及基于成熟开源库的稳健性能。现在就可以在你的项目中引入 Jongo让 POJO 与 MongoDB 文档的互转变得轻松自然。【免费下载链接】jongoQuery in Java as in Mongo shell项目地址: https://gitcode.com/gh_mirrors/jo/jongo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jongo对象映射指南Jackson让POJO与MongoDB文档无缝互转【免费下载链接】jongoQuery in Java as in Mongo shell项目地址: https://gitcode.com/gh_mirrors/jo/jongoJongo 是一个轻量级 Java 框架它的核心能力是通过内置的 Jackson 对象映射让你的 POJO 与 MongoDB 文档实现无缝互转——保存对象时自动序列化为 BSON查询时自动反序列化回 Java 对象全程零样板代码。本文带你快速掌握 Jongo 对象映射的完整用法。为什么需要 Jongo 对象映射在传统 Mongo Java Driver 中读写数据往往要手动组装DBObject、手工put/get字段代码冗长且容易出错。Jongo 解决了这个问题痛点Jongo 的解决方案手动组装 DBObjectPOJO 自动序列化为 BSON结果集手工转换查询结果自动反序列化为对象_id字段难处理自动填充与映射主键查询语言不直观直接复制粘贴 Mongo shell 查询语句 核心理念Query in Java as in Mongo shell——用 Java 写出和 Mongo shell 一样的查询体验。快速上手三步完成对象映射第 1 步引入依赖在pom.xml中添加依赖说明见项目根目录 pom.xmldependency groupIdorg.jongo/groupId artifactIdjongo/artifactId version1.5.2/version /dependencyJongo 内置了 Jackson支持 2.9 ~ 2.19 版本区间无需额外配置序列化库。第 2 步创建 Jongo 实例构造 Jongo 时如果不指定 Mapper它会自动使用 Jackson 映射器见src/main/java/org/jongo/Jongo.javaJongo jongo new Jongo(db); MongoCollection users jongo.getCollection(users);第 3 步直接保存和查询对象users.save(user); User u users.findOne(name, Alice).as(User.class);就这么简单——保存时 Jongo 将User对象序列化为 BSON 文档查询时再把文档还原为User对象。核心机制Jackson 映射引擎的工作原理对象映射的核心是 JacksonMapper它实现 Mapper 接口提供四类能力Marshaller序列化器POJO → BSON 文档Unmarshaller反序列化器BSON 文档 → POJOObjectIdUpdater写入前自动为主键字段填充 ObjectIdQueryFactory把 Mongo shell 风格查询字符串编译为查询对象真正执行转换的是 JacksonEngine它通过自定义的MongoBsonFactory让 Jackson 直接读写 BSON 字节流而不经过 JSON 字符串中转性能与原生驱动相当。主键映射MongoId 注解的用法MongoDB 文档默认以_id字段作为主键。在 POJO 中用MongoId注解见src/main/java/org/jongo/marshall/jackson/oid/MongoId.java标记对应属性即可public class User { MongoId private ObjectId id; private String name; // getter / setter }保存时 Jongo 会自动生成 ObjectId 填入该字段读取时自动把文档的_id映射回来。⚠️ 注意旧版Id注解src/main/java/org/jongo/marshall/jackson/oid/Id.java已被标记为废弃与外部 ObjectMapper 混用时可能产生副作用新项目请直接使用MongoId。自定义配置灵活定制映射行为通过jacksonMapper()构建器见 AbstractMappingBuilder可以深度定制映射规则Mapper mapper jacksonMapper() .enable(DeserializationFeature.READ_UNKNOWN_PROPERTIES) .withView(View.Public.class) // 基于视图控制序列化字段 .build(); Jongo jongo new Jongo(db, mapper);常用配置项registerModule注册自定义 Jackson 模块addSerializer/addDeserializer为特定类型添加自定义序列化/反序列化器withView使用 Jackson 视图机制控制哪些字段被读写setVisibilityChecker调整字段可见性规则enable/disable开关 Jackson 各项特性配置类的完整实现位于src/main/java/org/jongo/marshall/jackson/configuration/目录包含PropertyModifier、AnnotationModifier、VisibilityModifier等组件都遵循单一职责设计便于阅读和扩展。实战场景典型对象映射用法场景一查询返回 List 对象ListUser result users.find(age #, 30).asList(User.class);查询语句可以直接使用 Mongo shell 的 EJSON 语法无需学习新的查询 API。场景二按主键查询与更新User u users.findOne(objectId).as(User.class); users.update(objectId).set(name, Bob);相关方法实现见 MongoCollectionfindOne、update、save、insert、remove全部支持直接传 ObjectId。场景三嵌套对象与多态POJO 中的嵌套对象和集合字段会被递归映射。多态场景父类引用指向子类实例的映射测试参考src/test/java/org/jongo/PolymorphismTest.java和NestedPolymorphismTest.javaJongo 对这类复杂结构的处理均有完整保障。对象映射行为测试如何验证你的映射配置项目测试目录提供了大量映射行为的参考用例测试文件验证内容src/test/java/org/jongo/DocumentMarshallingTest.java文档序列化的基础行为src/test/java/org/jongo/marshall/jackson/JacksonEngineTest.java引擎序列化/反序列化src/test/java/org/jongo/marshall/jackson/JacksonAnnotationsHandlingTest.javaJackson 注解处理src/test/java/org/jongo/JacksonAnnotationsHandlingTest.java注解映射场景src/test/java/org/jongo/InsertTest.java保存时的主键自动填充 建议修改映射配置后运行这些测试能快速验证行为是否符合预期。常见问题速查Q保存对象时_id没有自动填充检查主键字段类型是否为ObjectId并确认已加MongoId注解且未使用废弃的Id。Q查询结果反序列化报 MarshallingException查看src/main/java/org/jongo/marshall/MarshallingException.java中的异常信息通常是 POJO 字段类型与文档中存储的类型不匹配。Q能用自己的 ObjectMapper 吗可以。构建jacksonMapper()时传入自定义ObjectMapper即可但需注意此时不会自动注册内置的 BSON 模块可能需要手动registerModule(new BsonModule())见src/main/java/org/jongo/marshall/jackson/bson4jackson/BsonModule.java。总结Jongo 的对象映射体系让 Java 开发者可以彻底告别手动组装 DBObject 的苦役零配置起步——默认 Jackson 映射器开箱即用注解驱动——MongoId一个注解搞定主键深度可定制——构建器模式覆盖序列化、视图、可见性等所有场景性能可靠——直接操作 BSON 字节流与原生驱动同速从 README.md 可以看到Jongo 的三大支柱正是忠实地还原 Mongo shell 查询体验、面向对象的读写、以及基于成熟开源库的稳健性能。现在就可以在你的项目中引入 Jongo让 POJO 与 MongoDB 文档的互转变得轻松自然。【免费下载链接】jongoQuery in Java as in Mongo shell项目地址: https://gitcode.com/gh_mirrors/jo/jongo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
