Spring Data JPA Repository自定义原生查询返回类型不符及最佳返回类型选择

最合适的返回类型选择 #

你当前的SQL是无分组的全表聚合，单次执行只会返回单行、两列的结果（分别是field1符合条件的行数、field2符合条件的行数），结合开发场景有三个可选的合理方案：

• 自定义DTO投影类（最推荐）：针对两个有明确业务含义的统计值，专门写一个带对应构造器的普通类，让Spring Data直接把查询列的值映射到对象字段上。
  *注意：count()函数的返回值是大整数范围，字段类型要用Long而非Integer，避免数据量超过Integer上限时溢出。
  示例代码：

  // 静态内部类或单独定义在domain层均可
  public class FieldCountStats {
      private final Long field1Count;
      private final Long field2Count;
  
      // 构造器参数名必须和SQL的列别名完全匹配
      public FieldCountStats(Long field1Count, Long field2Count) {
          this.field1Count = field1Count;
          this.field2Count = field2Count;
      }
      // 仅需要字段对应的getter方法即可，无需setter
      public Long getField1Count() { return field1Count; }
      public Long getField2Count() { return field2Count; }
  }
  

  Repository方法可以直接返回这个类，不需要用List包装，因为查询本身只会返回单行：

  @Query(
          value = "select count(case when field1 = true then 1 end) as field1Count, count(case when field2 = true then 1 end) as field2Count from test_table",
          nativeQuery = true
  )
  FieldCountStats selectRowCount();
  

• 临时场景用Map<String, Object>返回：如果不想专门写DTO类，可以直接声明返回值为Map，Spring会把列别名作为Map的key，列值作为对应的value，适合快速验证、临时统计的场景。
• 仅当SQL有分组逻辑、会返回多行统计结果时，才需要把上述DTO或Map用List包装，匹配多行的结果结构。

为什么声明了List<Integer>, 实际返回的是List<Object[]> #

这个现象完全是Spring Data JPA的运行时代理机制+Java泛型擦除共同导致的，和你推测的方向一致：

• 首先，Spring Data对原生查询的结果映射逻辑，完全以SQL实际返回的列结构为基准，不会强匹配Java方法上声明的泛型类型。你写的SQL查询行包含两个独立的列，Hibernate拿到JDBC结果集后，会把每一行的所有列值打包成一个Object数组——只要单行列数大于1，就无法直接映射成单个Java基础值。
• Java泛型的运行时擦除效应：你在方法上写的List<Integer>只是编译期的类型提示，在运行时代码里这个类型会被擦除，Spring在生成Repository的动态代理实现时，根本识别不到你原本指定的泛型元素是Integer。它只会按照返回值的原始类型List来理解：这是一个装多行结果的容器。
• 映射规则的本质：Spring Data的结果映射中，List是「行容器」，List里的每一个元素对应查询返回的一行数据。如果某一行只有1列，那List的元素就是这一列对应类型的值；如果某一行有多列，List的元素就是装着这一行所有列值的Object数组。你当前的SQL每行有2列，自然就形成了List<Object[]>的实际结构。
• 整个过程不会触发编译错误，因为Spring Data在原生查询映射阶段，不会校验你声明的泛型类型和实际SQL结构是否匹配，只有你实际取出元素做类型转换的时候，才会发现和预期的Integer类型不一致。

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