Jakarta NoSQL实战：构建统一Java数据访问层

最近在整理手里的一个 Java 后端项目时，我重新设计了一遍数据访问层。项目本身不算复杂，但存储端混着 MongoDB、Redis 和一个关系型数据库，之前访问层的代码几乎被各种 SDK 占满了。让我最终下决心去尝试 Jakarta NoSQL 的，是另一个更现实的场景：换掉其中一个存储中间件时，光迁移数据访问代码就足以拖垮一个迭代周期。这篇文章就以“基于 Jakarta NoSQL 的 Java 数据访问层设计”为主线，把这段时间踩过的坑、验证过的方案写清楚。它能解决什么问题？简单说，就是把不同 NoSQL 的访问方式收敛到一套统一规范之下。适合谁看？正在做多存储项目、打算给系统引入 NoSQL，或者面试前想补一补这块 Java 生态知识的朋友，都会用得上。

1. 为什么我用它来设计数据访问层

1.1 传统 JDBC/JPA 在“多存储”面前的尴尬

先聊基础。Java 生态里，JDBC 是最经典的数据库访问接口，但它面向的是关系型数据库，核心模型是表、行、列、外键和 SQL。后来 JPA/Hibernate 在这之上做了 ORM，开发体验好了很多，但 JPA 能“屏蔽”的范围依然被限制在关系模型内。只要底层还是 MySQL、PostgreSQL 这类关系型数据库，Hibernate 都能帮你处理大部分方言差异。

问题在于，NoSQL 不是关系模型。MongoDB 的 Document 可以嵌套、字段不固定；Cassandra 的查询能力被分区键、聚簇列限制得死死的；Redis 本质上是键值操作，还要面对过期时间；Neo4j 则完全是图思维，节点和关系才是核心。这些存储模型和 SQL 表格差得太远，JPA 的 @OneToMany、@JoinColumn 到文档型数据库里根本无从映射。

实际项目里，大家通常会引入 Spring Data 生态的子模块，比如 Spring Data MongoDB、Spring Data Redis 等。写起来确实方便，但它们底层暴露的数据类型并不一致，Mongo 的 Document、Redis 的 ValueOperations、Cassandra 的 ResultSet 各有各的 API。一个服务既要读写 MongoDB，又要维护 Redis 缓存的时候，业务代码里就会出现两三种数据访问风格。表面上看没什么，真正换存储时，这些代码几乎要推倒重来。

我见过很多 Java 面试题里问“JDBC 为什么还在用”“JPA 和 MyBatis 怎么选”，其实背后同一个理：我们需要一个稳定的底层访问抽象。JDBC 就是关系型数据库的公共接口，框架在此基础上做增强。到了 NoSQL 时代，也需要一个类似的“公共接入模型”。Jakarta NoSQL 想做的，就是这件事。

1.2 Jakarta NoSQL 的定位：NoSQL 世界的 JPA

Jakarta NoSQL 是 Jakarta EE 官方规范，参考实现由 Eclipse JNoSQL 项目推进。它把 NoSQL 数据库按数据模型分成四类：Document、Column、Key-Value、Graph，并针对每一类提供对应的 Template 接口。这里的关键是，虽然底层存储差异很大，但它在上层用一套统一的 Entity 映射和 Repository 抽象把所有类型串起来。

你可以定义实体时只管 @Entity、@Id、@Column，仓库接口只管写 Optional<Person> findByName(String name)，至于这个实体最终落在 MongoDB 还是 Cassandra，对业务代码来说并不重要。做数据访问层设计时，团队可以先把领域实体定义出来，再把具体存储的选择往后放。需要切换存储时，理论上改的是依赖和少量配置，而不是把所有 DAO 代码重写一遍。

我最初接触时有一些怀疑：NoSQL 之间的差异那么大，一个规范真能统一？后来仔细看它的设计才理解，它并不是要把所有数据库变成同一个东西，而是在实体映射、仓库方法、查询关键词、事务边界这些“应用侧”抽象上拉齐。就好比 JPA 并没有让 Oracle 和 MySQL 完全一样，但让应用开发人员不用关心一个分页 SQL 到底怎么写。这个思路对多存储项目非常实用。

另外，理解 Jakarta NoSQL 之后，再回头看那些 Java 基础概念，感觉完全不一样。它的 Repository 自动实现依赖动态代理，方法名解析依赖反射，内部处理集合时大量使用 Lambda 和 Stream。其实很多“Java 八股文”里背过的接口、泛型、反射、动态代理，都是这类框架能够成立的底层支撑。我以前理解不深，觉得背这些只是为了应付面试；真正看懂框架源码之后才发现，很多东西是串起来的。

2. 核心概念：Entity、Template、Repository 是怎么形成的

2.1 实体映射：从 JavaBean 到 NoSQL Document

Jakarta NoSQL 的实体映射代码，和 JPA 看起来很像，但底层语义完全不同。先看一个实际例子：

java复制@Entity
public class Person {

    @Id
    private String id;

    @Column("name")
    private String name;

    @Column
    private Address address;

    @Column
    private List<String> tags;

    // getter / setter 省略
}

@Entity 标注这是一个实体，@Id 标记主键，@Column 指定字段映射。如果没有显式指定名称，默认使用 Java 属性名。address 是一个内嵌对象，在 MongoDB 里会被直接序列化成嵌套 JSON 文档，不需要单独建表。List<String> 这类集合也能直接映射成文档里的数组。

这就是和 JPA 最大的差异：JPA 面对的是扁平的行，嵌套关系往往要拆表或者用 @Embedded 模拟；而 Document 型 NoSQL 天然支持嵌套，实体设计更贴近聚合根的想法。如果你之前习惯用 JPA，写 Jakarta NoSQL 实体时反而要“松开一点”，不需要刻意把对象拆成多个实体，内嵌值和子文档直接摆在聚合里通常更合理。

这里有个容易踩的坑：ID 类型的选择。MongoDB 里原生主键是 ObjectId，但实践中我更倾向于用 String 类型的业务主键；Redis 的键本身就是字符串；Cassandra 的主键可能由多个列组合而成。如果你在实体里把 ID 死死写成 Long，后续接入 KV 存储时大概率要返工。我一般会在实体设计中保留 @Id 的语义，但类型尽量选 String 或自定义的标识符对象。

2.2 Template 和 Repository：两种操作姿势

Jakarta NoSQL 给开发者的操作入口主要有两个：Template 和 Repository。两者不是替代关系，而是粒度不同。

Template 更偏底层，类似 Spring 里的 JdbcTemplate。它负责直接连接数据库，提供 insert、update、delete、select 等基础操作。DocumentTemplate 负责文档型数据库，ColumnTemplate 负责列族存储，KeyValueTemplate 负责键值存储，GraphTemplate 负责图数据库。使用方式大致像这样：

java复制template.insert(person);
template.update(person);
template.delete(Person.class, id);
Optional<Person> person = template.find(Person.class, id);

Repository 则是更上层的抽象。开发者只需要写一个接口，声明方法签名，框架会根据方法名自动生成实现。例如：

java复制@Repository
public interface PersonRepository extends Repository<Person, String> {

    Optional<Person> findByName(String name);

    List<Person> findByAgeGreaterThan(int age);

    long countByCity(String city);
}

“为什么方法名能生成查询？”这是我面试别人时很喜欢问的问题，也是很多 Java 面试题里往深里考的方向。框架拿到接口定义后，在运行时通过动态代理拦截接口调用，解析方法名。findByName 会被拆成“字段 name 等于入参”的条件，findByAgeGreaterThan 会被拆成“字段 age 大于入参”的条件，然后再翻译成对应数据库的查询语句。整个过程依赖反射、泛型擦除和 Lambda 表达式，全是 Java 基础内容。

实际开发中，我建议把简单查询、单实体操作丢给 Repository，把复杂的条件查询、聚合操作下放到 Template。好比入参是一个对象、出参也是对象，中间不暴露底层存储类型。Service 层永远不直接拿到 Document、Row 这类数据库类型，这样才能把存储差异隔离在数据访问层内部。

2.3 四种存储类型背后的设计差异

Jakarta NoSQL 把数据库分成四类，不同类的性能和查询能力差异很大。用表格列一下：

设计数据访问层时，不要指望一个接口打天下。正确的做法是：把业务实体层固定下来，把存储差异隔离在 Template 实现后面。比如项目里可以用 DocumentTemplate 保存订单主数据，用 KeyValueTemplate 做订单缓存，用 DocumentTemplate 查历史记录。业务服务只面对订单实体和订单仓库接口，不会感知到底层实际有几种存储。

这个设计约束非常重要。我见过一些团队把 Mongo 的 Document 直接爬到 Service 层，然后写一大堆 document.getString("customerId") 之类的代码。短时间很爽，但每次换库、升级驱动，业务层就要跟着大改。好的数据访问层设计，应该让业务代码几乎感觉不到底层是哪种 NoSQL，这就是隔离的价值。

3. 实操：基于 Jakarta NoSQL 实现仓库层

3.1 环境准备与依赖引入

我这次用的是 Maven 项目，JDK 17。先引入 Jakarta NoSQL 的核心依赖和 MongoDB 的适配包。以 Eclipse JNoSQL 为参考实现，pom.xml 核心部分大致如下：

xml复制<dependency>
    <groupId>org.eclipse.jnosql.mapping</groupId>
    <artifactId>jnosql-mapping-document</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>org.eclipse.jnosql.databases</groupId>
    <artifactId>mongodb</artifactId>
    <version>1.0.0</version>
    <type>pom</type>
</dependency>

注意，不同版本的 groupId 和 artifactId 调整过，最好以官方示例为准。这里要特别提醒一个典型的 Java 环境配置问题：如果你的本地 JDK 是 17，但 Maven 的 compiler 插件没有显式配置 source 和 target，很容易出现“源发行版 17 需要目标发行版 17”这类编译错误。这不是 Jakarta NoSQL 本身的问题，但只要涉及新项目初始化，几乎每个人都会撞上一次。解决办法是在 pom.xml 中显式设置：

xml复制<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

连接信息通常放在 setting.properties 或 microprofile-config.properties 中。MongoDB 的默认配置类似：

properties复制jnosql.document.database=mydb
jnosql.mongodb.host=localhost:27017

如果你是本地测试，记得先确认 MongoDB 服务启动，端口默认 27017。如果不想本地装数据库，也可以用 Docker 跑一个临时实例，后面测试部分我会展开。

3.2 实体定义与注解

我以一个订单实体为例，展示实际使用的实体结构：

java复制@Entity
public class Order {

    @Id
    private String orderId;

    @Column
    private String customerId;

    @Column
    private LocalDateTime createdAt;

    @Column("items")
    private List<OrderItem> items;

    @Column
    private BigDecimal totalAmount;

    // 构造方法、getter/setter 省略
}

OrderItem 用 @Embeddable 标注，表示它是可嵌入对象，不需要单独作为实体来查询。在 MongoDB 中，它会被序列化成订单文档里的一个子文档数组。这种设计非常适合订单这类聚合根场景：一个订单就是一个文档，嵌套商品条目，读和写都非常快。

关于 @Column，记得使用显式名称。Java 代码里用驼峰命名很常见，但存储层字段往往希望用下划线命名，例如 order_id。在 @Column("order_id") 里指定之后，代码和存储层各用各的命名习惯，互不干扰。如果不写，框架会按 Java 字段名直接存，后面做数据迁移或跨团队协作时很容易对不上。

JPA 开发经验在这里大部分可以迁移。需要额外关注的是：NoSQL 数据库一般没有 DDL 自动建表的概念，实体类设计更像“约定优先于配置”。字段类型、嵌套深度、是否用集合，都要先在建模阶段想清楚，而不是依赖数据库去强约束。

3.3 自定义 Repository 方法

实体定义好之后，就可以建 Repository 了。这是整个数据访问层里可读性最强的一部分：

java复制@Repository
public interface OrderRepository extends Repository<Order, String> {

    Optional<Order> findByOrderId(String orderId);

    List<Order> findByCustomerId(String customerId);

    List<Order> findByCustomerIdAndCreatedAtAfter(String customerId, LocalDateTime time);

    List<Order> findByTotalAmountGreaterThanEqual(BigDecimal amount);

    long countByCustomerId(String customerId);

    boolean existsByOrderId(String orderId);
}

方法名解析支持的关键词和 Spring Data 基本一致，比如 And、Or、Between、LessThan、GreaterThan、OrderBy、CountBy、ExistsBy 等。组合条件越多，方法名越长，生成的查询语义也越直白。

但这里我要泼一盆冷水：派生查询真的不是万能的。一个方法名如果有四五个条件，读起来已经很难受，维护起来更痛苦。比如：

java复制List<Order> findByCustomerIdAndStatusAndCreatedAtGreaterThanAndDeletedAtIsNull(...);

这种代码放到团队里，不出一个月，就没人敢动。我的实际建议是：条件数量超过两三个的查询，直接改用 Template 写条件查询，或者用领域语义的 @Query 命名，把复杂逻辑收编到具有业务含义的方法后面。

3.4 模板操作与原生查询

需要复杂查询、聚合、或者数据库专属能力时，我会使用 DocumentTemplate。先通过依赖注入拿到实例：

java复制@Inject
private DocumentTemplate template;

然后使用流式查询 API：

java复制public List<Order> findOrdersAfter(LocalDateTime time) {
    return template.select(Order.class)
        .where("createdAt")
        .gt(time)
        .orderBy("createdAt")
        .desc()
        .result();
}

当条件很多时，这种链式 API 比派生方法名清晰得多。它返回的是 List<Order>，上层拿到的是领域对象，不会暴露 MongoDB 的底层类型。

需要更复杂的原生语句时，Template 也提供了入口。比如文档型数据库特有的数组操作、地理位置查询，可以把它包装在仓储实现里，只对服务层暴露一个按业务语义命名的接口，这样既不失去底层能力，也不污染上层设计。我自己的经验比例大概是：80% 的简单查询走 Repository，20% 的复杂查询走 Template。如果反过来，说明需求本身越来越复杂，应该考虑重构实体边界，而不是把所有 SQL 都堆在仓库层。

4. 与 Spring Boot 整合的完整示例

4.1 依赖与 Bean 注册

Jakarta NoSQL 规范本身基于 CDI（Contexts and Dependency Injection），所以它的原生环境是 Jakarta EE，而不是 Spring Boot。要在 Spring Boot 项目里使用，需要做一层简单的桥接。最直接的方式是启动一个 CDI 容器，再从 CDI 容器里取出 DocumentTemplate 或 Repository 实例，注册为 Spring Bean。

我的项目里是这样处理的：

java复制@Configuration
public class JNoSqlConfig {

    @Bean
    public DocumentTemplate documentTemplate() {
        return CDI.current()
            .select(DocumentTemplate.class)
            .get();
    }

    @Bean
    public OrderRepository orderRepository() {
        return CDI.current()
            .select(OrderRepository.class)
            .get();
    }
}

这里依赖 org.jboss.weld.se:weld-se-shaded。不同版本的 CDI 初始化方式略有差异，如果启动时找不到 DocumentTemplate，要先把 Weld 容器 initialize() 起来，再通过 CDI.current() 获取 Bean。这不是 Spring Boot 自动配置能覆盖的，属于 Jakarta NoSQL 和 Spring 生态之间的正常摩擦。

如果你不想引入 CDI 容器，也可以使用底层 API 手动构造。例如：

java复制DocumentConfiguration configuration = new DocumentConfiguration();
DocumentConfiguration.DocumentSupplier supplier = configuration.read("mongodb");
DocumentManager manager = supplier.get();
DocumentTemplate template = DocumentTemplate.of(manager);

这两种方式都能跑通。第一种更贴近 Jakarta NoSQL 的设计意图，第二种更显式、更好控制。我在项目里选的是第二种，因为团队对 CDI 不熟悉，显式构造能减少排查成本。

4.2 服务层实现：把 NoSQL 藏在门面后面

数据访问层设计里最容易被忽略的一环，是 Service 层的边界。如果 Service 直接操作 Template 或者暴露底层类型，仓库层设计得再干净也白搭。

我先把服务接口定义出来：

java复制public interface OrderService {

    Order create(Order order);

    Optional<Order> findById(String id);

    List<Order> recentOrders(int limit);
}

实现类不关心底层是 MongoDB 还是 Redis，只依赖 OrderRepository：

java复制@Service
public class OrderServiceImpl implements OrderService {

    private final OrderRepository orderRepository;

    public OrderServiceImpl(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    @Override
    public Order create(Order order) {
        return orderRepository.save(order);
    }

    @Override
    public Optional<Order> findById(String id) {
        return orderRepository.findById(id);
    }

    @Override
    public List<Order> recentOrders(int limit) {
        return orderRepository.findTopByOrderByCreatedAtDesc(limit);
    }
}

这里有几个细节值得注意。第一，OrderServiceImpl 只依赖 OrderRepository，不直接持有 DocumentTemplate。这样单元测试时只需要 Mock 掉 OrderRepository 一个接口，非常干净。第二，返回类型尽量使用领域对象和 Optional，不要把存储层特有的空值语义带到 Service 层。第三，findTopByOrderByCreatedAtDesc 这类方法名虽然方便，但底层如果换到 Cassandra，这种“取最近 N 条”的语义不一定等同，要提前确认。

我把这种设计叫“门面模式在持久化层的一次落地”。外部调用方拿到的是一个定义明确的订单服务，而不是一堆模板方法。换存储的时候，业务代码几乎没有感觉，真正的改动集中在 Repository 实现和底层依赖上。

4.3 事务与一致性处理

NoSQL 世界的事务能力差异非常大。MongoDB 4.0 之后支持多文档事务，Redis 只有分钟级的简单事务，Cassandra 的跨分区事务基本不存在。所以设计数据访问层时，不要天真地认为给方法加上 @Transactional 就万事大吉。

我负责的项目里有一个典型场景：创建订单时，既要写 MongoDB 的订单主表，又要删除 Redis 里的订单缓存。这是两个数据源之间的写操作，任何单库事务都管不住。最开始我尝试用 @Transactional 包住整个方法，结果发现 Redis 的写入失败时，MongoDB 的事务已经提交，数据一致性出现裂缝。

后来我调整方案：订单主表写入放在 MongoDB 的事务里，保证订单本身状态一致；缓存删除放到事务提交后的异步事件中，通过重试和最终一致来兜底。这个方案用了 Java 定时任务框架做补偿扫描，每五分钟检查一次有过期缓存标记的订单，重新刷新缓存。虽然实时性不是最强，但在业务可接受范围内，远比盲目追求强事务更现实。

这里的核心体会是：事务设计要跟着存储能力走，而不是跟着注解走。在设计初期就要明确每个操作的写路径、一致级别、补偿机制。如果项目里同时有 Document 和 Key-Value 两种存储，一定要把“跨存储一致性”当做一个独立设计问题来对待，不能指望一个框架帮你解决。

5. 常见问题与排查实录

5.1 我实际踩过的那些坑

先说一个最基础的。很多同学刚接触时会遇到“源发行版 17 需要目标发行版 17”的编译错误，这是 Maven compiler 插件配置和 JDK 版本不匹配导致的。花十分钟把 pom.xml 里的 maven.compiler.source 和 maven.compiler.target 都显式设为当前 JDK 版本，问题就解决了。这个坑看起来很小，但不动 Java 环境配置的人真的会卡很久。

第二个坑是 ID 类型不匹配。实体类里定义的 @Id 是 Long，但 MongoDB 存储的真实主键是 ObjectId，反序列化时直接报类型转换异常。后来我统一把业务实体的主键设计成 String，只有纯关系型、数据库自增主键的场景才保留 Long。这个教训让我养成了一个习惯：开始设计实体前，先翻一遍底层存储的主键策略。

第三个坑是方法名太长。findByCustomerIdAndStatusAndCreatedAtGreaterThanAndDeletedAtIsNull 这种方法写出来很容易，但维护它的人会崩溃。当方法名超过屏幕宽度时，不是代码风格问题，而是设计边界出现了问题。我会把这类查询重构到 Template 的链式查询中，或者定义一个语义更明确的新实体/视图。

第四个坑和 Spring Boot 整合有关。由于 Jakarta NoSQL 依赖 CDI，在 Spring Boot 中做类路径扫描时要格外小心包范围。如果扫描范围太大，服务启动会明显变慢，甚至因为 CDI 容器和 Spring 容器对同一接口的重复管理而出现“已有 instance 存在”的异常。解决方法很直接：把 @Repository 接口放在一个独立子包中，只对该包做扫描。

5.2 问题速查表

为了方便排查，我把最常见的几个问题整理成表格：

这张表不是官方文档，而是我在实际测试中反复遇到的问题。排查顺序一般是：先看依赖有没有，再看 Bean 有没有被扫描到，最后看字段映射和类型匹配。只要思路清晰，这类问题基本都能在半小时内定位。

5.3 测试与接口自动化实践

数据访问层虽然不对外暴露 HTTP 接口，但同样需要测试。我通常使用 Testcontainers 启动一个真实的 MongoDB 容器，在 JUnit 5 里直接跑 Repository 层的集成测试。这样做的好处是测试环境接近生产，能真实暴露方法名派生、字段映射、序列化等问题。

一个最简单的测试片段：

java复制@Testcontainers
public class OrderRepositoryTest {

    @Container
    static MongoDBContainer mongo = new MongoDBContainer("mongo:6.0");

    @Test
    void shouldSaveAndFindOrder() {
        OrderRepository repository = buildRepository(mongo.getReplicaSetUrl());

        Order order = new Order();
        order.setOrderId("O001");
        order.setCustomerId("C001");
        order.setCreatedAt(LocalDateTime.now());

        Order saved = repository.save(order);
        Optional<Order> loaded = repository.findById("O001");

        assertThat(loaded).isPresent();
        assertThat(loaded.get().getCustomerId()).isEqualTo("C001");
    }
}

注意，Testcontainers 在本地运行时会自动下载 MongoDB 镜像，如果网络慢，第一次会等很久。需要在 CI 上跑的话，尽量提前预热镜像。我一般会在本地开发环境先把镜像拉好，再让 CI 直接复用，避免每次构建都卡在拉镜像上。

很多人理解的“接口自动化测试框架”只针对 HTTP API，但我觉得数据访问层同样需要自动化回归。尤其像 Jakarta NoSQL 这种基于动态代理的实现，方法名解析一旦出错，编译期是发现不了的，必须靠运行时测试兜住。最好在 CI 里面把 Repository 集成测试纳入流水线，保证实体字段改了、方法名变了，能第一时间被测试打回。这一步骤看起来琐碎，实际价值非常高。

6. 个人体会，以及还能怎么扩展

6.1 学习曲线和 Java 基础的关系

很多人一看到新的规范就头大，觉得又要背一堆新 API。我自己实际用下来的感受是：只要 Java 基础扎实，接受 Jakarta NoSQL 成本非常低。它的实体映射基于反射，Repository 自动实现基于动态代理，查询结果处理大量依赖 Stream 和 Lambda。你会这些基础能力，理解框架就快；反过来，理解了一个框架，也能把抽象的知识变得具体。

举个例子，Java 面试题里常考“接口和抽象类的区别”“lambda 函数 java 怎么用”这种基础题，但很多背得很熟的人，并没有真正见过它们在生产框架里怎么发力。Jakarta NoSQL 的 Repository 接口就是典型的接口加动态代理组合，where("age").gt(20) 这种链式 API 也是把函数式思维揉进了查询描述里。如果你只是背概念，面试过了也就忘了；但你在框架里见过它，以后再遇到新框架，一眼就能看出它底层玩的是什么。

我甚至觉得，所谓“Java 八股文”，如果用来反推框架原理，反而是一种高效学习方式。Repository 为什么不写实现类就能用？因为动态代理。Template 为什么能返回 Stream<Order>？因为泛型和 Lambda。@Entity 为什么能把字段映射到文档？因为反射。这些问题的答案，其实就是 Java 基础在数据访问层设计中的真实应用。

6.2 还能在哪继续深入

这次项目做完之后，我考虑继续扩展两个方向。

第一个是缓存层和数据主库的统一管理。现在我主库用 DocumentTemplate，缓存用 Redis 的 KeyValueTemplate，两者在服务层各自存在。下一步想把缓存访问也纳入统一规范，让 KeyValueTemplate 的读写方法和 DocumentTemplate 的实体操作并行放在同一个门面下。这样以后如果缓存中间件要换，比如从 Redis 换成其他 KV，影响范围依然能控制在数据访问层内部。再配合 Java 定时任务框架做缓存刷新和数据同步，整体架构会干净很多。

第二个方向是 AI 应用里的向量检索。现在很多项目会把文本向量化之后写入向量数据库，我在搜索“qwen embedding、并存储milvus 调用示例 java langchain4j”时，发现 Java 侧已经出现了不少可用的客户端。虽然向量库不完全等同于传统 NoSQL，但它同样可以被纳入数据访问层的统一设计思路中，用实体映射加 Repository 的方式来组织，而不是让业务代码直接拼向量 API。

踩过几次坑之后，我的核心建议只有一条：不要为了用规范而用规范，要看你的存储是不是真的足够多样。如果项目只有一种 NoSQL，直接用一个成熟客户端反而更省事；当第二、第三种存储出现，并且你们已经感受到切换成本时，Jakarta NoSQL 这种统一抽象才真正开始体现价值。这也是我这篇文章最想传达的一点。