如何让SpringData/Hibernate将非唯一查询结果映射为Java集合类型

报错根本原因 #

1. 集合关联的笛卡尔积展开：你对@ElementCollection类型的topics执行join操作时，JPQL会将每个tutorial记录与其topics集合中的每个元素做笛卡尔积展开。例如单条教程包含3个主题，查询就会返回3行结果，每行仅主题字段不同，其余字段完全一致。
2. 构造函数投影的机制限制：select new调用构造函数的投影逻辑是每行结果对应一个投影类实例，JPA本身没有自动聚合多行同主键记录、将分散的集合元素合并为Set的能力。你调用获取单条结果的方法时，框架检测到返回了3行数据，直接抛出NonUniqueResultException，不会执行合并逻辑。
3. 构造函数参数类型不匹配：你当前的投影类构造函数最后一个入参是String类型的topics，但你要赋值的字段是Set<String>，就算没有非唯一结果的报错，也只能拿到单个主题值，丢失其余数据。

为什么默认findById没有问题 #

默认findById是实体查询逻辑，JPA的实体加载流程原生支持集合属性的组装，会自动将关联表的多条记录合并为实体的Set字段，和自定义构造函数投影是完全不同的处理链路，因此可以正常拿到集合数据。

解决方案 #

方案1：手动聚合结果（最通用）

先调整查询返回Tuple类型，不直接构造投影类，自己遍历结果按主键聚合：

@Query("select t.id, t.created, t.createdBy, t.lastModified, t.lastModifiedBy, t.version, t.exclusive, (VALUE(l)).name, (VALUE(l)).description, tp " +
       "from tutorial t join t.localizations l join t.topics tp " +
       "where (VALUE(l)).name like %:name% and (KEY(l)) = :lang")
List<Tuple> queryLocalizedTutorials(@Param("name") String name, @Param("lang") String lang);

再写聚合逻辑：

// 按教程ID分组聚合
Map<UUID, LocalizedTutorialDAO> daoMap = new LinkedHashMap<>();
for (Tuple tuple : tupleList) {
    UUID id = tuple.get(0, UUID.class);
    LocalizedTutorialDAO dao = daoMap.get(id);
    if (dao == null) {
        dao = new LocalizedTutorialDAO(
            id,
            tuple.get(1, LocalDateTime.class),
            tuple.get(2, String.class),
            tuple.get(3, LocalDateTime.class),
            tuple.get(4, String.class),
            tuple.get(5, Integer.class),
            tuple.get(6, Boolean.class),
            tuple.get(7, String.class),
            tuple.get(8, String.class),
            new HashSet<>()
        );
        daoMap.put(id, dao);
    }
    // 把当前行的主题加入集合
    dao.getTopics().add(tuple.get(9, String.class));
}
List<LocalizedTutorialDAO> result = new ArrayList<>(daoMap.values());

记得调整投影类的构造函数，新增支持传入空Set的构造方法即可。

方案2：先查实体再映射（最简单）

用fetch join查询完整的Tutorial实体，JPA会自动组装topics集合，再手动映射到投影类：

@Query("select distinct t from tutorial t join fetch t.localizations l join fetch t.topics " +
       "where (VALUE(l)).name like %:name% and (KEY(l)) = :lang")
List<Tutorial> findLocalizedTutorials(@Param("name") String name, @Param("lang") String lang);

拿到实体列表后，直接遍历拷贝字段到LocalizedTutorialDAO即可，适合数据量不大的场景。

内容的提问来源于stack exchange，提问作者Goncalo Condeco