Spring Data JPA原生查询报DTO类型转换异常排查

抛出该异常的核心原因是Spring Data JPA无法将原生查询返回的结果自动转换为你定义的PaymentFormulaDto，具体触发点有三个：

• Repository方法的返回值使用了没有指定泛型的原始类型List，执行原生查询时框架默认会将结果封装为TupleBackedMap结构（也就是异常信息中提到的源类型），由于没有明确声明目标转换类型，框架不会自动执行DTO映射。
• 你编写的原生SQL仅查询了a.external_id as externalId_单个字段，不仅和PaymentFormulaDto定义的7个属性数量不匹配，字段别名externalId_也和DTO内的属性名externalId不一致，没有映射匹配的基础。
• PaymentFormulaDto没有配置对应的结果映射规则，也没有提供符合框架实例化要求的构造方法、getter/setter，框架无法完成属性填充。

优先推荐使用JPQL构造投影的方式实现，代码侵入性最低，不需要额外配置映射规则：

方案一：JPQL构造投影（推荐） #

1. 为PaymentFormulaDto补充无参构造、和查询字段顺序一致的全参构造，以及所有属性的getter/setter方法：

public class PaymentFormulaDto {

    private String externalId;
    private String employeeName;
    private String employeeLastName;
    private String pasword;
    private String employeeEmail;
    private String employeeExternalId;
    private String employeeId;

    // 无参构造，兼容序列化、框架反射实例化场景
    public PaymentFormulaDto() {}

    // 全参构造，参数顺序必须和后续查询语句的字段顺序完全一致
    public PaymentFormulaDto(String externalId, String employeeName, String employeeLastName, String pasword, String employeeEmail, String employeeExternalId, String employeeId) {
        this.externalId = externalId;
        this.employeeName = employeeName;
        this.employeeLastName = employeeLastName;
        this.pasword = pasword;
        this.employeeEmail = employeeEmail;
        this.employeeExternalId = employeeExternalId;
        this.employeeId = employeeId;
    }

    // 省略所有属性的getter、setter方法，实际代码需要补全
}

2. 修改Repository层查询方法，移除nativeQuery = true改用JPQL语法，通过new关键字指定返回的DTO类型，注意JPQL中使用实体类属性名而非数据库字段名：

// 注意替换类的全路径为你项目中的实际路径
@Query(value = "select new com.example.entities.dtos.PaymentFormulaDto(a.externalId, a.employeeName, a.employeeLastName, a.pasword, a.employeeEmail, a.externalId, cast(a.employeeId as string)) " +
        "from Employee a left join PaymentFormula b on a.externalId = b.userId")
List<PaymentFormulaDto> getEmployeeAndPayment();

方案二：原生SQL+结果集映射（必须使用原生SQL时选择） #

如果因为SQL语法特殊无法改用JPQL，可以通过@SqlResultSetMapping显式定义映射规则：

1. 在任意实体类（一般放在关联的主查询实体上，比如Employee类）上添加结果映射配置：

@SqlResultSetMapping(
        name = "PaymentFormulaDtoMapping",
        classes = @ConstructorResult(
                targetClass = PaymentFormulaDto.class,
                columns = {
                        @ColumnResult(name = "externalId", type = String.class),
                        @ColumnResult(name = "employeeName", type = String.class),
                        @ColumnResult(name = "employeeLastName", type = String.class),
                        @ColumnResult(name = "pasword", type = String.class),
                        @ColumnResult(name = "employeeEmail", type = String.class),
                        @ColumnResult(name = "employeeExternalId", type = String.class),
                        @ColumnResult(name = "employeeId", type = String.class)
                }
        )
)
@Entity
public class Employee {
    // 实体原有代码保持不变
}

2. 修改Repository方法，补全SQL查询字段、修正别名，指定使用定义好的映射规则，同时给返回值加上正确的泛型：

@Query(value = "select a.external_id as externalId, " +
        "a.name as employeeName, " +
        "a.last_name as employeeLastName, " +
        "a.password as pasword, " +
        "a.email as employeeEmail, " +
        "a.external_id as employeeExternalId, " +
        "cast(a.id as char) as employeeId " +
        "from employee a left join paymentformula b on a.external_id = b.user_id",
        nativeQuery = true)
@ResultSetMapping(name = "PaymentFormulaDtoMapping")
List<PaymentFormulaDto> getEmployeeAndPayment();

• 禁止使用无泛型的原始List作为查询返回值，必须明确指定泛型类型，否则框架无法推断转换目标。
• 查询字段的别名必须和DTO属性名、映射配置中定义的字段名完全一致，JPA映射默认大小写敏感。
• 如果使用构造函数投影，查询字段的顺序、类型必须和DTO全参构造的参数顺序、类型一一对应，否则会抛出构造方法找不到的异常。
• 原SQL仅查询单个字段，即使映射配置正确，也会因为参数数量不匹配报错，必须把DTO需要的所有字段都加入查询语句。

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