从Hibernate迁移到EclipseLink时遇Tuple缺失描述符错误求助

问题场景 #

将代码从Hibernate迁移到EclipseLink后，运行测试时遇到原生查询报错，涉及的查询代码如下：

@Query(value = "SELECT distinct on (s.id) s.id as pId, CAST(s.data as TEXT), " +
        "s.created_at as createdAt, s.closed as closedAt, s.type as Type" +
        " FROM Stable s where s.status = 'CLOSED' order by s.id, s.created_at desc", nativeQuery = true)
List<Project> getAll();

抛出的异常信息：

Exception Description: Missing descriptor for [interface jakarta.persistence.Tuple].
Query: ReadAllQuery(referenceClass=Tuple sql="******************")
    at org.eclipse.persistence.exceptions.QueryException.descriptorIsMissing(QueryException.java:480)
    ...（省略部分栈跟踪）

该查询在Hibernate中可正常运行，但Stack Overflow相关方案尝试后无效。

问题原因 #

• Hibernate处理原生查询返回实体时，对字段别名与实体属性的匹配规则较为宽松，即使别名和属性名不完全一致（如pId对应实体的id），也能自动完成映射，最终返回指定的实体对象。
• EclipseLink的逻辑更严格：当查询的字段别名与目标实体（Project）的属性名不匹配时，它不会自动尝试映射，而是默认将结果以Tuple类型返回。但方法声明返回List<Project>，而Tuple并非实体类，没有对应的映射描述符（Descriptor），因此抛出该异常。

查询中存在多处别名与实体属性不匹配的情况，比如s.id as pId（实体属性应为id）、s.type as Type（实体属性应为type），这是触发问题的核心原因。

解决思路 #

1. 修正查询字段别名，与实体属性完全匹配 #

直接修改查询中的别名，使其与Project实体的属性名（包括大小写）完全一致，让EclipseLink能自动完成结果映射：

@Query(value = "SELECT distinct on (s.id) s.id as id, CAST(s.data as TEXT), " +
        "s.created_at as createdAt, s.closed as closedAt, s.type as type" +
        " FROM Stable s where s.status = 'CLOSED' order by s.id, s.created_at desc", nativeQuery = true)
List<Project> getAll();

2. 使用@SqlResultSetMapping显式定义映射关系 #

如果无法修改查询语句的别名，可通过@SqlResultSetMapping显式指定查询字段别名到实体属性的映射规则：

• 在Project实体类上添加映射配置：

  @Entity
  @SqlResultSetMapping(
      name = "ProjectMapping",
      entities = @EntityResult(
          entityClass = Project.class,
          fields = {
              @FieldResult(name = "id", column = "pId"),
              @FieldResult(name = "type", column = "Type"),
              @FieldResult(name = "createdAt", column = "createdAt"),
              @FieldResult(name = "closedAt", column = "closedAt"),
              @FieldResult(name = "data", column = "data")
          }
      )
  )
  public class Project {
      // 实体属性定义
  }
  

• 在查询注解中指定该映射：

  @Query(value = "SELECT distinct on (s.id) s.id as pId, CAST(s.data as TEXT), " +
          "s.created_at as createdAt, s.closed as closedAt, s.type as Type" +
          " FROM Stable s where s.status = 'CLOSED' order by s.id, s.created_at desc", 
          nativeQuery = true,
          resultSetMapping = "ProjectMapping")
  List<Project> getAll();
  

3. 检查实体类的字段映射配置 #

确认Project实体类的每个属性都通过@Column等注解正确配置了与数据库字段的映射关系，避免因配置遗漏或名称不匹配导致的映射失败。

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