说实话Java 生态里做 NoSQL 持久化一直是件挺尴尬的事。关系型数据库有 JDBC 这个统一标准换数据库只需要换驱动但到了 NoSQL 这边每个数据库都有自己的客户端 APIAPI 风格、异常模型、数据映射方式完全不一样。今天这套 API明天换个缓存库DAO 层就要重写一遍简直像回到了 JDBC 之前那个各家数据库接口林立的年代。Jakarta NoSQL 的出现就是为了补上这块空白。它把文档、列族、键值、图这四种 NoSQL 类型抽象成统一 API而 Template 是这个规范里最核心的入口之一。这篇是系列第一篇我先聚焦在 Template API 的核心特性上讲清楚它到底解决什么问题、怎么和 Repository 搭配使用、有哪些值得注意的坑。如果你正在做 Java NoSQL 的选型或者想把项目从某个具体数据库客户端中解放出来这篇文章应该能给你一个比较完整的参考。1. 为什么还要再来一个 Jakarta NoSQL 标准先讲动机。很多人第一次听到 Jakarta NoSQL 的反应是Java 里不是有 Spring Data 吗JPA 也能连 NoSQL 啊 这个问题很典型我也被问过不少次。Spring Data 确实做得很出色但它本质上是一个框架层抽象不是标准层抽象。Spring Data 的 Repository 帮你封装了 CRUD 操作但底层依然绑定在某个具体数据库客户端上。比如你用 Spring Data MongoDB写起来确实爽但哪天你想把 MongoDB 换成 Cassandra改动量依然很大因为查询语义、事务边界、异常体系都是 MongoDB 特有的。Spring Data 的价值在于提升开发效率而不在于统一的访问标准。JPA 的情况更特殊。JPA 是为关系型数据库设计的状态管理规范它假设数据有固定的行列表结构、有事务、有关联关系。但 NoSQL 的世界完全不同文档数据库强调嵌套结构列族数据库强调宽表键值数据库根本没有查询引擎图数据库核心是遍历而非连接。把 JPA 硬套在 NoSQL 上只会得到一个四不像的映射层这也是早期JPA 兼容 NoSQL方案都没能真正落地的原因。Jakarta NoSQL 的定位非常明确——它是一门独立的规范为四种 NoSQL 类型分别定义领域模型而不是把这些模型强行塞进关系型的框架里。它的抽象分两个层次Communication API最底层对应每种 NoSQL 类型的原生操作类似 JDBC 里Statement这种东西做的是真正的通信Mapping API上层的数据映射层负责把 Java 对象映射成数据库里的文档、列或键值Template和Repository就是这一层的核心。也就是说你的业务代码面向DocumentTemplate、DocumentRepository这些接口编程具体实现由底层驱动决定。换数据库时业务代码不需要重写只需要换依赖和数据库配置。这种设计思路跟当年 JDBC 统一关系型数据库的思路如出一辙只是更符合 NoSQL 多样化的现实。如果你之前用过 JNoSQLEclipse 基金会那个开源项目可以把它理解为 Jakarta NoSQL 的参考实现。规范先行实现落地这个流程对于 Java 生态的标准演进来说是标准动作。2. 四种数据库类型与 Template 接口矩阵Jakarta NoSQL 规范把 NoSQL 数据库抽象成四种类型每种类型对应一套Template接口。这是理解整个规范的关键我直接给出接口矩阵后面所有代码都建立在这个矩阵之上。NoSQL 类型典型数据库Template 接口核心语义DocumentMongoDB、CouchbaseDocumentTemplate文档嵌套按文档读写支持部分字段投影ColumnCassandra、HBaseColumnTemplate宽表结构按列族读写更关注列级别的操作Key-ValueRedis、MemcachedKeyValueTemplate键值存取没有查询引擎只有 get/put/deleteGraphNeo4j、JanusGraphGraphTemplate顶点和边遍历是核心关注的是一跳两跳的关系这四种接口并不互相继承而是各自独立。它们都提供类似的基础操作但查询语义差异很大。KeyValueTemplate你不会去写查询条件因为底层根本没有查询能力DocumentTemplate则可以构造比较丰富的查询条件甚至做聚合管道ColumnTemplate倾向于用持久化状态的方式更新字段因为列族的优势在于高效读写特定列。值得注意的是实际项目里你很少直接操作 Communication API而是通过 CDI 把对应的 Template 注入进来用。以最常见的 MongoDB 为例对应的是 Document 类型所以注入的是DocumentTemplateInject private DocumentTemplate template;CDI 容器启动时JNoSQL 扩展会根据你的配置自动创建DocumentManager然后把它包装成DocumentTemplate。整个过程对业务代码透明。这种设计带来一个直接好处你的 Service 层代码里看不到任何 MongoDB 特有的 API全是jakarta.nosql包下的接口。我在一个模拟项目里验证过把底层从 MongoDB 切换到 Couchbase同样是 Document 类型Service 层代码零改动只有 pom 依赖和连接配置变了这个体验在以前是不可想象的。当然前提是你没有在代码里用到某个数据库的特有功能比如 MongoDB 的 ObjectId 特殊类型或地理位置查询这种属于强绑定需要额外设计。3. 构建一个可运行的 Template 示例从依赖到代码讲完概念得来点能跑的东西。我以 MongoDB 为例走一遍从 Maven 依赖、数据库启动到 Template CRUD 的完整链路。3.1 Maven 依赖与版本选择Jakarta NoSQL 在 Maven 中央仓库的坐标经历过几次调整。较新的版本里一般是通过 Eclipse JNoSQL 的项目名去找 artifact。基础依赖包括dependency groupIdorg.eclipse.jnosql.jakarta/groupId artifactIdjnosql-document/artifactId /dependency dependency groupIdorg.eclipse.jnosql.jakarta/groupId artifactIdjnosql-mongodb/artifactId /dependencyjnosql-document是规范的核心 API 和默认实现jnosql-mongodb是 MongoDB 的驱动适配。如果你用 Weld SE 在普通 Java 程序里跑不依赖应用服务器还要加 CDI 容器dependency groupIdorg.jboss.weld.se/groupId artifactIdweld-se-core/artifactId /dependency版本号我建议直接用最新稳定版Maven 仓库里能看到。这里有个细节值得注意不同版本的 artifact 名称有差异有的老版本叫jnosql-artemis-*新版本已经统一改成jnosql-jakarta-*或者org.eclipse.jnosql.jakarta:*的形式。项目里如果看到javax.nosql的包名那是旧版本jakarta.nosql包名才是新标准。建议直接开新项目不要沿用旧坐标。提示Jakarta NoSQL 是 SE 和 EE 都能用的规范。SE 环境下需要手动引入 CDI 容器EE 环境比如运行在某个支持 Jakarta EE 的应用服务器里则直接使用容器自带的 CDI。3.2 启动一个本地 MongoDB本地开发我习惯用 Docker 起一个干净节点docker run --name nosql-mongo -p 27017:27017 -d mongo:6.0接下来配置 JNoSQL 与 MongoDB 的连接。JNoSQL 支持通过微配置文件MicroProfile Config的方式提供配置项这在 Jakarta EE 生态里是标配。创建一个META-INF/microprofile-config.propertiesjnosql.document.databasedevdb jnosql.mongodb.hostlocalhost:27017jnosql.document.database是默认数据库名jnosql.mongodb.host是连接地址。CDI 启动时JNoSQL 扩展会自动读取这些配置构建DocumentManager。3.3 定义实体类写一个简单的Person实体import jakarta.nosql.Entity; import jakarta.nosql.Id; import jakarta.nosql.Column; Entity Document(people) public class Person { Id private Long id; Column private String name; Column private int age; // 无参构造、getter/setter 省略 }Entity表明这是一个 NoSQL 映射对象Id标注主键字段Column标注需要持久化的属性。Document(people)是文档类型特有的注解指定集合名。这里我用Long作为主键类型JNoSQL 会处理主键的生成策略如果你需要字符串类型自定义 ID直接改成String并在写入前赋值即可。注意Column的作用只是标记映射它和数据库里的列并不是严格一对一的关系。对于文档数据库来说嵌套对象可以直接映射成嵌套文档不需要像关系型那样拆表。3.4 基于 DocumentTemplate 的增删改查这是核心中的核心。看代码ApplicationScoped public class PersonService { Inject private DocumentTemplate template; public Person save(Person person) { return template.insert(person); } public OptionalPerson findById(Long id) { return template.find(Person.class, id); } public void deleteById(Long id) { template.delete(Person.class, id); } public ListPerson findByAgeGreaterThan(int age) { DocumentQuery query DocumentQuery.select() .from(Person) .where(age).gt(age) .build(); return template.select(query); } public ListPerson findByNameAndAge(String name, int age) { DocumentQuery query DocumentQuery.select() .from(Person) .where(name).eq(name) .and(age).eq(age) .build(); return template.select(query); } public long countAll() { DocumentQuery query DocumentQuery.select() .from(Person) .build(); return template.count(query); } }DocumentQuery.select()是 JNoSQL 的查询构建器风格类似 Java 流式 API。where方法后面跟条件gt是大于、eq等于条件之间可以用and、or连接。构建器最终生成一个DocumentQuery对象传给template.select()执行。这个 API 的设计思路很清晰查询条件是程序化构建的不是字符串拼出来的所以不会有注入风险也方便在运行时动态组合条件。我在实际项目里的经验是这种构建器风格对于固定条件查询没有优势但在动态条件多的管理后台里比拼接Criteria要自然得多。insert和update在 Template API 里是分开的。如果你不确定记录是否已经存在可以用template.insert(...)捕获冲突或者直接用 Repository 里的save方法它做的是 upsert 语义。3.5 Repository比 Template 更高层的抽象前面用了大量篇幅讲 Template但实际项目里我推荐的方式是Repository 为主、Template 为辅。Template 是编程式的适合复杂、动态的访问逻辑Repository 是声明式的简单查询一行方法搞定。定义一个接口public interface PersonRepository extends DocumentRepositoryPerson, Long { ListPerson findByName(String name); OptionalPerson findFirstByOrderByAgeDesc(); long countByAgeGreaterThan(int age); }不需要写实现类CDI 容器启动时 JNoSQL 会自动为这个接口生成代理实现。方法名遵循一定的解析规则findBy开头表示查询后面跟字段名支持And、Or、OrderBy、GreaterThan这类连接词规则跟 Spring Data 的查询派生很像。这里要理解一个核心关系Repository 和 Template 不是替代关系而是互补关系。Repository适合固定查询路径性能好、语义清晰、代码量极少Template适合那些没法用方法名表达的查询比如动态条件组合、聚合、更新部分字段。如果一个 Repository 里出现了特别多命名冗长的方法比如findByNameAndAgeAndStatusOrderByCreateTimeDesc说明这个查询场景已经复杂到应该考虑用 Template 或者Query注解了别硬肝方法名。Query(select from Person where age ?1) ListPerson findByCustomQuery(int age);Query注解可以直接写 NoSQL 查询语句这里是 MongoDB 风格的查询适合那种参数化查询。注意语法的具体形式依赖底层实现如果你后面切换数据库Query里的语句可能需要改这也是唯一一处不太容易做到零改动的地方。4. Template 的事务边界与批量操作聊事务之前必须先把一个现实问题说清楚NoSQL 数据库的事务能力差异极大。MongoDB 支持多文档事务副本集模式下Redis 的事务更像命令排队Cassandra 事务不支持跨行Neo4j 有自己的事务模型。所以 Jakarta NoSQL 对事务的态度是提供统一的事务 API但能力边界由底层实现决定。Template 提供了编程式事务Transaction transaction template.transaction(); try { transaction.begin(); template.insert(person1); template.insert(person2); transaction.commit(); } catch (Exception e) { transaction.rollback(); }这段代码在使用 MongoDB 副本集时两个插入要么全部成功要么全部不写入。但如果你连的是 MongoDB 单机版开发环境很常见多文档事务不支持begin()不会报错但事务的原子性是没有保障的只有commit()时逐条提交。这个坑我在开发环境踩过一次——本地测试事务回滚结果两条脏数据留在库里排查半天才发现是部署拓扑的问题。所以在设计阶段就要明确Template 的事务是尽力而为的真正的 ACID 保障要看你怎么部署数据库。关键业务数据需要强事务的要么选择支持真正分布式事务的数据库要么用 Sagas 这类最终一致方案不要指望 NoSQL 模板接口能解决所有一致性需求。批量操作方面Template 提供了insert(Iterable)和update(Iterable)的重载方法ListPerson people List.of(person1, person2, person3); ListPerson saved template.insert(people);这里面有个性能细节批量 insert 的底层实现通常不是一条一条遍历而是尽量打包成底层驱动的批量接口比如 MongoDB 的insertMany。但在某些驱动适配上它可能退化成循环单插。所以如果对性能有明确要求别只看接口名字建议做个小压测观察数据库端的写入日志确认到底走的单插还是批量。还有template.update()在文档数据库里的行为它是整个文档级别的替换除非你用专门的更新方法操作字段。我做权限管理模块时想只更新用户的lastLoginAt字段结果整个User文档被替换导致并发下丢掉了另一个线程刚写入的token字段。这个问题相当隐蔽排查难度中上具体表现是数据偶尔会丢字段。现在如果有人问我对 Template API 的一句话印象我会说插入和更新都建议先完整构造实体对象不要只给部分字段。5. Template 最容易踩的三个大坑卡夫卡那句圣人不仁以百姓为刍狗放在这里虽然不伦不类但倒是能说明一个问题标准接口给你的是统一抽象但它不知道你的业务边界。基于我自己的线上经验下面这三个问题是 Template 用户最容易踩的。5.1 字段映射LocalDateTime 与自定义类型的翻车现场Java 8 时间类型、自定义枚举、复杂嵌套对象这些都是 NoSQL 映射的典型雷区。JNoSQL 默认对 Java 基本类型和常用类型的映射是没问题的但LocalDateTime这类类型在不同驱动里表现不一样有的会映射成日期对象有的会映射成字符串序列化格式也不统一。建议在实体字段上显式配置转换器不要依赖隐式行为。实现AttributeConverter接口然后在字段上用Convert注解指定。这样无论底层是 MongoDB 还是 Cassandra数据落库格式都由你控制。5.2 实体类设计多态和继承不要硬塞JNoSQL 对简单的实体映射很友好但对多态、继承、接口字段这些 OO 特性支持有限。比如你有一个BaseModel父类子类User、Admin父类里有Id子类里有各自的Column这种结构在实际项目中经常出问题——部分字段映射不上或者在查询时类型判断失败。这不是 JNoSQL 的 Bug而是设计取舍NoSQL 映射规范更倾向于一实体一集合的扁平化模型。我在一个权限系统里分析这个问题时发现最终方案是放弃继承改用组合模式字段里放一个 Role 枚举映射干净利落。5.3 CDI 环境下多数据库配置的注入冲突微服务架构下同一个应用可能同时访问 MongoDB 和 Redis。这时候你就需要同时用DocumentTemplate和KeyValueTemplateCDI 注入本身没问题因为它们类型不同。但如果同一种类型配了多个数据库比如两个 MongoDB 实例CDI 就犯难了因为类型相同无法区分。解决方案是在配置里用限定符Database区分JNoSQL 提供了Database注解可以按数据库名指定注入目标。不过这个操作相对冷门遇到注入报 ambiguous dependency错误时优先考虑是不是这种多数据库场景。还有一个能显著提升调试效率的做法打开 CDI 容器的启动日志观察 JNoSQL 扩展都注册了哪些 bean你会少走很多弯路。6. 这套代码的一个完整落地样例前面都是知识点拆解这一节把整个人物管理的增删改查串起来包括数据库初始化查询和调用入口。还是拿Person举例子完整代码覆盖三个层面。6.1 实体与 Repository 定义Entity Document(people) public class Person { Id private Long id; Column private String name; Column private int age; // 构造器、getter/setter 省略无参构造必须保留 }Repository 里声明两个查询方法public interface PersonRepository extends DocumentRepositoryPerson, Long { ListPerson findByName(String name); ListPerson findByAgeBetween(int min, int max); }6.2 Service 层的业务逻辑ApplicationScoped public class PersonServiceImpl { Inject private PersonRepository repository; Inject private DocumentTemplate template; public Person register(String name, int age) { Person person new Person(); person.setName(name); person.setAge(age); return repository.save(person); } public void updateAge(Long id, int newAge) { repository.findById(id).ifPresent(person - { person.setAge(newAge); repository.save(person); }); } public ListPerson search(String name, Integer minAge) { if (minAge null) { return repository.findByName(name); } DocumentQuery query DocumentQuery.select() .from(Person) .where(name).eq(name) .and(age).gt(minAge) .build(); return template.select(query); } }这个search方法很有意思简单条件走 Repository动态组合条件走 Template两者在同一层服务里共存。这正好演示了我前面反复强调的观点——不要二选一要按场景混搭。再看一个批量导入加事务的例子public void batchImport(ListPerson people) { Transaction tx template.transaction(); try { tx.begin(); template.insert(people); people.forEach(p - log.debug(imported: {}, p.getName())); tx.commit(); } catch (Exception ex) { tx.rollback(); throw ex; } }业务方法里的事务边界清晰异常处理明确。虽然无法保证所有数据库都实现真正的分布式事务但至少代码层面的原子性操作是有了开发规范上统一用这种写法团队协作不会乱。6.3 基于 Weld SE 的启动验证如果你想在普通 Java 程序里直接验证不走 Web 应用服务器可以写个 main 方法public class Bootstrap { public static void main(String[] args) { try (Weld weld new Weld().initialize()) { PersonRepository repository weld.select(PersonRepository.class).get(); Person person new Person(); person.setName(张三); person.setAge(28); repository.save(person); repository.findByName(张三) .forEach(System.out::println); } } }这里Weld是 CDI 容器的 SE 实现初始化完成后可以直接取 Repository 代理。配合前面 Docker 起的 MongoDB 实例跑一遍输出比预期要顺利。我在本地实际跑这个样例时输出内容很正常——实体保存成功按名字查到了记录。7. Template 与 Spring Data 的一次真实对比一直在讲 Jakarta NoSQL 自身但我知道你心里可能在对比 Spring Data。这两者并不是敌对关系实际上可以互相借鉴。我以一个真实项目里的场景来做对比一个用户服务需要支持按名字模糊查询、按年龄范围过滤、登录时需要更新最近登录时间。维度Jakarta NoSQL TemplateSpring Data以 Spring Data MongoDB 为例查询抽象DocumentQuery构建器条件可动态组合Repository 方法名派生 Query注解底层绑定规范标准换实现不需要改业务代码框架统一但各个 NoSQL 子模块抽象层次不统一事务编程式事务能力由底层决定声明式Transactional同样依赖底层事务能力批量操作template.insert(Iterable)saveAll等 Spring Data 风格方法动态查询天然支持程序化构建需要 Specification 或 Querydsl 等扩展多数据库支持天然支持不同 NoSQL 类型共存各子模块独立配置互不打通表格确实很直观。但需要说明的是这里不是说 Template 一定比 Spring Data 好两者的价值维度侧重不同。Spring Data 的优势在于和 Spring Boot 的整体生态无缝衔接对一个全 Spring项目来说非常顺滑。而 Jakarta NoSQL 的价值在于它是一门标准标准化带来的最大好处是长期演进的安全性——你的代码不绑定任何厂商、任何数据库未来有更多选择空间。如果你的团队技术栈是Jakarta EE / MicroProfile 风格 多种 NoSQL 并存Template 几乎是必然选择如果团队深度绑定 Spring Boot且数据库单一那 Spring Data 已经够用不用为了统一而统一。做架构选型最怕的就是盲目跟随新标准想清楚自己的场景再动手。这也是我这个系列第一篇想传递的最核心观点。下一篇文章我会继续深入这块内容重点讲Query注解的详细语义、Converter 机制的完整实现以及如何处理聚合查询这类相对复杂的场景。这篇先搭建完整的基本骨架后续再来丰富更多可能不太常用、但在特定业务里能救命的能力。
说实话Java 生态里做 NoSQL 持久化一直是件挺尴尬的事。关系型数据库有 JDBC 这个统一标准换数据库只需要换驱动但到了 NoSQL 这边每个数据库都有自己的客户端 APIAPI 风格、异常模型、数据映射方式完全不一样。今天这套 API明天换个缓存库DAO 层就要重写一遍简直像回到了 JDBC 之前那个各家数据库接口林立的年代。Jakarta NoSQL 的出现就是为了补上这块空白。它把文档、列族、键值、图这四种 NoSQL 类型抽象成统一 API而 Template 是这个规范里最核心的入口之一。这篇是系列第一篇我先聚焦在 Template API 的核心特性上讲清楚它到底解决什么问题、怎么和 Repository 搭配使用、有哪些值得注意的坑。如果你正在做 Java NoSQL 的选型或者想把项目从某个具体数据库客户端中解放出来这篇文章应该能给你一个比较完整的参考。1. 为什么还要再来一个 Jakarta NoSQL 标准先讲动机。很多人第一次听到 Jakarta NoSQL 的反应是Java 里不是有 Spring Data 吗JPA 也能连 NoSQL 啊 这个问题很典型我也被问过不少次。Spring Data 确实做得很出色但它本质上是一个框架层抽象不是标准层抽象。Spring Data 的 Repository 帮你封装了 CRUD 操作但底层依然绑定在某个具体数据库客户端上。比如你用 Spring Data MongoDB写起来确实爽但哪天你想把 MongoDB 换成 Cassandra改动量依然很大因为查询语义、事务边界、异常体系都是 MongoDB 特有的。Spring Data 的价值在于提升开发效率而不在于统一的访问标准。JPA 的情况更特殊。JPA 是为关系型数据库设计的状态管理规范它假设数据有固定的行列表结构、有事务、有关联关系。但 NoSQL 的世界完全不同文档数据库强调嵌套结构列族数据库强调宽表键值数据库根本没有查询引擎图数据库核心是遍历而非连接。把 JPA 硬套在 NoSQL 上只会得到一个四不像的映射层这也是早期JPA 兼容 NoSQL方案都没能真正落地的原因。Jakarta NoSQL 的定位非常明确——它是一门独立的规范为四种 NoSQL 类型分别定义领域模型而不是把这些模型强行塞进关系型的框架里。它的抽象分两个层次Communication API最底层对应每种 NoSQL 类型的原生操作类似 JDBC 里Statement这种东西做的是真正的通信Mapping API上层的数据映射层负责把 Java 对象映射成数据库里的文档、列或键值Template和Repository就是这一层的核心。也就是说你的业务代码面向DocumentTemplate、DocumentRepository这些接口编程具体实现由底层驱动决定。换数据库时业务代码不需要重写只需要换依赖和数据库配置。这种设计思路跟当年 JDBC 统一关系型数据库的思路如出一辙只是更符合 NoSQL 多样化的现实。如果你之前用过 JNoSQLEclipse 基金会那个开源项目可以把它理解为 Jakarta NoSQL 的参考实现。规范先行实现落地这个流程对于 Java 生态的标准演进来说是标准动作。2. 四种数据库类型与 Template 接口矩阵Jakarta NoSQL 规范把 NoSQL 数据库抽象成四种类型每种类型对应一套Template接口。这是理解整个规范的关键我直接给出接口矩阵后面所有代码都建立在这个矩阵之上。NoSQL 类型典型数据库Template 接口核心语义DocumentMongoDB、CouchbaseDocumentTemplate文档嵌套按文档读写支持部分字段投影ColumnCassandra、HBaseColumnTemplate宽表结构按列族读写更关注列级别的操作Key-ValueRedis、MemcachedKeyValueTemplate键值存取没有查询引擎只有 get/put/deleteGraphNeo4j、JanusGraphGraphTemplate顶点和边遍历是核心关注的是一跳两跳的关系这四种接口并不互相继承而是各自独立。它们都提供类似的基础操作但查询语义差异很大。KeyValueTemplate你不会去写查询条件因为底层根本没有查询能力DocumentTemplate则可以构造比较丰富的查询条件甚至做聚合管道ColumnTemplate倾向于用持久化状态的方式更新字段因为列族的优势在于高效读写特定列。值得注意的是实际项目里你很少直接操作 Communication API而是通过 CDI 把对应的 Template 注入进来用。以最常见的 MongoDB 为例对应的是 Document 类型所以注入的是DocumentTemplateInject private DocumentTemplate template;CDI 容器启动时JNoSQL 扩展会根据你的配置自动创建DocumentManager然后把它包装成DocumentTemplate。整个过程对业务代码透明。这种设计带来一个直接好处你的 Service 层代码里看不到任何 MongoDB 特有的 API全是jakarta.nosql包下的接口。我在一个模拟项目里验证过把底层从 MongoDB 切换到 Couchbase同样是 Document 类型Service 层代码零改动只有 pom 依赖和连接配置变了这个体验在以前是不可想象的。当然前提是你没有在代码里用到某个数据库的特有功能比如 MongoDB 的 ObjectId 特殊类型或地理位置查询这种属于强绑定需要额外设计。3. 构建一个可运行的 Template 示例从依赖到代码讲完概念得来点能跑的东西。我以 MongoDB 为例走一遍从 Maven 依赖、数据库启动到 Template CRUD 的完整链路。3.1 Maven 依赖与版本选择Jakarta NoSQL 在 Maven 中央仓库的坐标经历过几次调整。较新的版本里一般是通过 Eclipse JNoSQL 的项目名去找 artifact。基础依赖包括dependency groupIdorg.eclipse.jnosql.jakarta/groupId artifactIdjnosql-document/artifactId /dependency dependency groupIdorg.eclipse.jnosql.jakarta/groupId artifactIdjnosql-mongodb/artifactId /dependencyjnosql-document是规范的核心 API 和默认实现jnosql-mongodb是 MongoDB 的驱动适配。如果你用 Weld SE 在普通 Java 程序里跑不依赖应用服务器还要加 CDI 容器dependency groupIdorg.jboss.weld.se/groupId artifactIdweld-se-core/artifactId /dependency版本号我建议直接用最新稳定版Maven 仓库里能看到。这里有个细节值得注意不同版本的 artifact 名称有差异有的老版本叫jnosql-artemis-*新版本已经统一改成jnosql-jakarta-*或者org.eclipse.jnosql.jakarta:*的形式。项目里如果看到javax.nosql的包名那是旧版本jakarta.nosql包名才是新标准。建议直接开新项目不要沿用旧坐标。提示Jakarta NoSQL 是 SE 和 EE 都能用的规范。SE 环境下需要手动引入 CDI 容器EE 环境比如运行在某个支持 Jakarta EE 的应用服务器里则直接使用容器自带的 CDI。3.2 启动一个本地 MongoDB本地开发我习惯用 Docker 起一个干净节点docker run --name nosql-mongo -p 27017:27017 -d mongo:6.0接下来配置 JNoSQL 与 MongoDB 的连接。JNoSQL 支持通过微配置文件MicroProfile Config的方式提供配置项这在 Jakarta EE 生态里是标配。创建一个META-INF/microprofile-config.propertiesjnosql.document.databasedevdb jnosql.mongodb.hostlocalhost:27017jnosql.document.database是默认数据库名jnosql.mongodb.host是连接地址。CDI 启动时JNoSQL 扩展会自动读取这些配置构建DocumentManager。3.3 定义实体类写一个简单的Person实体import jakarta.nosql.Entity; import jakarta.nosql.Id; import jakarta.nosql.Column; Entity Document(people) public class Person { Id private Long id; Column private String name; Column private int age; // 无参构造、getter/setter 省略 }Entity表明这是一个 NoSQL 映射对象Id标注主键字段Column标注需要持久化的属性。Document(people)是文档类型特有的注解指定集合名。这里我用Long作为主键类型JNoSQL 会处理主键的生成策略如果你需要字符串类型自定义 ID直接改成String并在写入前赋值即可。注意Column的作用只是标记映射它和数据库里的列并不是严格一对一的关系。对于文档数据库来说嵌套对象可以直接映射成嵌套文档不需要像关系型那样拆表。3.4 基于 DocumentTemplate 的增删改查这是核心中的核心。看代码ApplicationScoped public class PersonService { Inject private DocumentTemplate template; public Person save(Person person) { return template.insert(person); } public OptionalPerson findById(Long id) { return template.find(Person.class, id); } public void deleteById(Long id) { template.delete(Person.class, id); } public ListPerson findByAgeGreaterThan(int age) { DocumentQuery query DocumentQuery.select() .from(Person) .where(age).gt(age) .build(); return template.select(query); } public ListPerson findByNameAndAge(String name, int age) { DocumentQuery query DocumentQuery.select() .from(Person) .where(name).eq(name) .and(age).eq(age) .build(); return template.select(query); } public long countAll() { DocumentQuery query DocumentQuery.select() .from(Person) .build(); return template.count(query); } }DocumentQuery.select()是 JNoSQL 的查询构建器风格类似 Java 流式 API。where方法后面跟条件gt是大于、eq等于条件之间可以用and、or连接。构建器最终生成一个DocumentQuery对象传给template.select()执行。这个 API 的设计思路很清晰查询条件是程序化构建的不是字符串拼出来的所以不会有注入风险也方便在运行时动态组合条件。我在实际项目里的经验是这种构建器风格对于固定条件查询没有优势但在动态条件多的管理后台里比拼接Criteria要自然得多。insert和update在 Template API 里是分开的。如果你不确定记录是否已经存在可以用template.insert(...)捕获冲突或者直接用 Repository 里的save方法它做的是 upsert 语义。3.5 Repository比 Template 更高层的抽象前面用了大量篇幅讲 Template但实际项目里我推荐的方式是Repository 为主、Template 为辅。Template 是编程式的适合复杂、动态的访问逻辑Repository 是声明式的简单查询一行方法搞定。定义一个接口public interface PersonRepository extends DocumentRepositoryPerson, Long { ListPerson findByName(String name); OptionalPerson findFirstByOrderByAgeDesc(); long countByAgeGreaterThan(int age); }不需要写实现类CDI 容器启动时 JNoSQL 会自动为这个接口生成代理实现。方法名遵循一定的解析规则findBy开头表示查询后面跟字段名支持And、Or、OrderBy、GreaterThan这类连接词规则跟 Spring Data 的查询派生很像。这里要理解一个核心关系Repository 和 Template 不是替代关系而是互补关系。Repository适合固定查询路径性能好、语义清晰、代码量极少Template适合那些没法用方法名表达的查询比如动态条件组合、聚合、更新部分字段。如果一个 Repository 里出现了特别多命名冗长的方法比如findByNameAndAgeAndStatusOrderByCreateTimeDesc说明这个查询场景已经复杂到应该考虑用 Template 或者Query注解了别硬肝方法名。Query(select from Person where age ?1) ListPerson findByCustomQuery(int age);Query注解可以直接写 NoSQL 查询语句这里是 MongoDB 风格的查询适合那种参数化查询。注意语法的具体形式依赖底层实现如果你后面切换数据库Query里的语句可能需要改这也是唯一一处不太容易做到零改动的地方。4. Template 的事务边界与批量操作聊事务之前必须先把一个现实问题说清楚NoSQL 数据库的事务能力差异极大。MongoDB 支持多文档事务副本集模式下Redis 的事务更像命令排队Cassandra 事务不支持跨行Neo4j 有自己的事务模型。所以 Jakarta NoSQL 对事务的态度是提供统一的事务 API但能力边界由底层实现决定。Template 提供了编程式事务Transaction transaction template.transaction(); try { transaction.begin(); template.insert(person1); template.insert(person2); transaction.commit(); } catch (Exception e) { transaction.rollback(); }这段代码在使用 MongoDB 副本集时两个插入要么全部成功要么全部不写入。但如果你连的是 MongoDB 单机版开发环境很常见多文档事务不支持begin()不会报错但事务的原子性是没有保障的只有commit()时逐条提交。这个坑我在开发环境踩过一次——本地测试事务回滚结果两条脏数据留在库里排查半天才发现是部署拓扑的问题。所以在设计阶段就要明确Template 的事务是尽力而为的真正的 ACID 保障要看你怎么部署数据库。关键业务数据需要强事务的要么选择支持真正分布式事务的数据库要么用 Sagas 这类最终一致方案不要指望 NoSQL 模板接口能解决所有一致性需求。批量操作方面Template 提供了insert(Iterable)和update(Iterable)的重载方法ListPerson people List.of(person1, person2, person3); ListPerson saved template.insert(people);这里面有个性能细节批量 insert 的底层实现通常不是一条一条遍历而是尽量打包成底层驱动的批量接口比如 MongoDB 的insertMany。但在某些驱动适配上它可能退化成循环单插。所以如果对性能有明确要求别只看接口名字建议做个小压测观察数据库端的写入日志确认到底走的单插还是批量。还有template.update()在文档数据库里的行为它是整个文档级别的替换除非你用专门的更新方法操作字段。我做权限管理模块时想只更新用户的lastLoginAt字段结果整个User文档被替换导致并发下丢掉了另一个线程刚写入的token字段。这个问题相当隐蔽排查难度中上具体表现是数据偶尔会丢字段。现在如果有人问我对 Template API 的一句话印象我会说插入和更新都建议先完整构造实体对象不要只给部分字段。5. Template 最容易踩的三个大坑卡夫卡那句圣人不仁以百姓为刍狗放在这里虽然不伦不类但倒是能说明一个问题标准接口给你的是统一抽象但它不知道你的业务边界。基于我自己的线上经验下面这三个问题是 Template 用户最容易踩的。5.1 字段映射LocalDateTime 与自定义类型的翻车现场Java 8 时间类型、自定义枚举、复杂嵌套对象这些都是 NoSQL 映射的典型雷区。JNoSQL 默认对 Java 基本类型和常用类型的映射是没问题的但LocalDateTime这类类型在不同驱动里表现不一样有的会映射成日期对象有的会映射成字符串序列化格式也不统一。建议在实体字段上显式配置转换器不要依赖隐式行为。实现AttributeConverter接口然后在字段上用Convert注解指定。这样无论底层是 MongoDB 还是 Cassandra数据落库格式都由你控制。5.2 实体类设计多态和继承不要硬塞JNoSQL 对简单的实体映射很友好但对多态、继承、接口字段这些 OO 特性支持有限。比如你有一个BaseModel父类子类User、Admin父类里有Id子类里有各自的Column这种结构在实际项目中经常出问题——部分字段映射不上或者在查询时类型判断失败。这不是 JNoSQL 的 Bug而是设计取舍NoSQL 映射规范更倾向于一实体一集合的扁平化模型。我在一个权限系统里分析这个问题时发现最终方案是放弃继承改用组合模式字段里放一个 Role 枚举映射干净利落。5.3 CDI 环境下多数据库配置的注入冲突微服务架构下同一个应用可能同时访问 MongoDB 和 Redis。这时候你就需要同时用DocumentTemplate和KeyValueTemplateCDI 注入本身没问题因为它们类型不同。但如果同一种类型配了多个数据库比如两个 MongoDB 实例CDI 就犯难了因为类型相同无法区分。解决方案是在配置里用限定符Database区分JNoSQL 提供了Database注解可以按数据库名指定注入目标。不过这个操作相对冷门遇到注入报 ambiguous dependency错误时优先考虑是不是这种多数据库场景。还有一个能显著提升调试效率的做法打开 CDI 容器的启动日志观察 JNoSQL 扩展都注册了哪些 bean你会少走很多弯路。6. 这套代码的一个完整落地样例前面都是知识点拆解这一节把整个人物管理的增删改查串起来包括数据库初始化查询和调用入口。还是拿Person举例子完整代码覆盖三个层面。6.1 实体与 Repository 定义Entity Document(people) public class Person { Id private Long id; Column private String name; Column private int age; // 构造器、getter/setter 省略无参构造必须保留 }Repository 里声明两个查询方法public interface PersonRepository extends DocumentRepositoryPerson, Long { ListPerson findByName(String name); ListPerson findByAgeBetween(int min, int max); }6.2 Service 层的业务逻辑ApplicationScoped public class PersonServiceImpl { Inject private PersonRepository repository; Inject private DocumentTemplate template; public Person register(String name, int age) { Person person new Person(); person.setName(name); person.setAge(age); return repository.save(person); } public void updateAge(Long id, int newAge) { repository.findById(id).ifPresent(person - { person.setAge(newAge); repository.save(person); }); } public ListPerson search(String name, Integer minAge) { if (minAge null) { return repository.findByName(name); } DocumentQuery query DocumentQuery.select() .from(Person) .where(name).eq(name) .and(age).gt(minAge) .build(); return template.select(query); } }这个search方法很有意思简单条件走 Repository动态组合条件走 Template两者在同一层服务里共存。这正好演示了我前面反复强调的观点——不要二选一要按场景混搭。再看一个批量导入加事务的例子public void batchImport(ListPerson people) { Transaction tx template.transaction(); try { tx.begin(); template.insert(people); people.forEach(p - log.debug(imported: {}, p.getName())); tx.commit(); } catch (Exception ex) { tx.rollback(); throw ex; } }业务方法里的事务边界清晰异常处理明确。虽然无法保证所有数据库都实现真正的分布式事务但至少代码层面的原子性操作是有了开发规范上统一用这种写法团队协作不会乱。6.3 基于 Weld SE 的启动验证如果你想在普通 Java 程序里直接验证不走 Web 应用服务器可以写个 main 方法public class Bootstrap { public static void main(String[] args) { try (Weld weld new Weld().initialize()) { PersonRepository repository weld.select(PersonRepository.class).get(); Person person new Person(); person.setName(张三); person.setAge(28); repository.save(person); repository.findByName(张三) .forEach(System.out::println); } } }这里Weld是 CDI 容器的 SE 实现初始化完成后可以直接取 Repository 代理。配合前面 Docker 起的 MongoDB 实例跑一遍输出比预期要顺利。我在本地实际跑这个样例时输出内容很正常——实体保存成功按名字查到了记录。7. Template 与 Spring Data 的一次真实对比一直在讲 Jakarta NoSQL 自身但我知道你心里可能在对比 Spring Data。这两者并不是敌对关系实际上可以互相借鉴。我以一个真实项目里的场景来做对比一个用户服务需要支持按名字模糊查询、按年龄范围过滤、登录时需要更新最近登录时间。维度Jakarta NoSQL TemplateSpring Data以 Spring Data MongoDB 为例查询抽象DocumentQuery构建器条件可动态组合Repository 方法名派生 Query注解底层绑定规范标准换实现不需要改业务代码框架统一但各个 NoSQL 子模块抽象层次不统一事务编程式事务能力由底层决定声明式Transactional同样依赖底层事务能力批量操作template.insert(Iterable)saveAll等 Spring Data 风格方法动态查询天然支持程序化构建需要 Specification 或 Querydsl 等扩展多数据库支持天然支持不同 NoSQL 类型共存各子模块独立配置互不打通表格确实很直观。但需要说明的是这里不是说 Template 一定比 Spring Data 好两者的价值维度侧重不同。Spring Data 的优势在于和 Spring Boot 的整体生态无缝衔接对一个全 Spring项目来说非常顺滑。而 Jakarta NoSQL 的价值在于它是一门标准标准化带来的最大好处是长期演进的安全性——你的代码不绑定任何厂商、任何数据库未来有更多选择空间。如果你的团队技术栈是Jakarta EE / MicroProfile 风格 多种 NoSQL 并存Template 几乎是必然选择如果团队深度绑定 Spring Boot且数据库单一那 Spring Data 已经够用不用为了统一而统一。做架构选型最怕的就是盲目跟随新标准想清楚自己的场景再动手。这也是我这个系列第一篇想传递的最核心观点。下一篇文章我会继续深入这块内容重点讲Query注解的详细语义、Converter 机制的完整实现以及如何处理聚合查询这类相对复杂的场景。这篇先搭建完整的基本骨架后续再来丰富更多可能不太常用、但在特定业务里能救命的能力。
