Spring Data JPA投影遇TupleConverterNotFoundException，如何编写注册转换器？

首先明确回答：当然可以编写并注册自定义的TupleConverter，不过在动手实现自定义转换器之前，我们先看看有没有更省心的方式解决你当前的问题，再深入自定义方案。

快速解决当前的ConverterNotFoundException #

你的场景是用@Query返回自定义DTO（ProjectItem），Spring Data JPA其实默认支持通过构造方法直接映射查询结果到DTO，大概率是你的ProjectItem构造方法不符合要求：

• 确保ProjectItem有public的全参构造方法，并且参数顺序和@Query中查询的字段顺序完全一致（projectId → projectName → techstack）。比如：

public class ProjectItem { 
    private final Integer projectId; 
    private final String projectName; 
    private final String techstack; 

    // 必须是public，参数顺序和查询字段严格对应
    public ProjectItem(Integer projectId, String projectName, String techstack) {
        this.projectId = projectId;
        this.projectName = projectName;
        this.techstack = techstack;
    }

    // getter方法按需添加
}

• 另一种更简便的方式是使用接口式Projection，不需要写构造方法，只需要定义对应字段的getter：

public interface ProjectItem {
    Integer getProjectId();
    String getProjectName();
    String getTechstack();
}

Spring Data会自动生成代理类来映射查询结果，完全不需要手动处理转换器。

自定义并注册TupleConverter（针对复杂转换场景） #

如果上面的方法满足不了你的需求（比如需要对字段做复杂处理、格式转换等），可以自定义TupleConverter并整合到Spring Data JPA的转换流程中。

1. 实现TupleConverter接口 #

TupleConverter是Spring Data Commons提供的接口，我们需要实现它的convert方法，把JPA查询返回的Tuple（结果集行）转换成目标DTO：

import org.springframework.data.convert.TupleConverter;
import org.springframework.data.convert.TupleConverter.Tuple;

public class CustomProjectItemConverter implements TupleConverter<ProjectItem> {

    @Override
    public ProjectItem convert(Tuple tuple) {
        // 从Tuple中按索引获取字段（索引从0开始，和查询字段顺序对应）
        Integer projectId = tuple.get(0, Integer.class);
        String projectName = tuple.get(1, String.class);
        String techstack = tuple.get(2, String.class);

        // 这里可以添加自定义转换逻辑，比如把技术栈转成大写
        String processedTechstack = techstack != null ? techstack.toUpperCase() : null;

        return new ProjectItem(projectId, projectName, processedTechstack);
    }
}

2. 注册自定义转换器到Spring容器 #

需要创建一个Spring配置类，将自定义转换器整合到JPA的查询执行转换器中：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.data.jpa.repository.query.JpaQueryFactory;
import org.springframework.data.jpa.repository.query.QueryEnhancer;
import org.springframework.data.jpa.repository.query.QueryExecutionConverter;
import javax.persistence.EntityManager;
import java.util.Collections;

@Configuration
@EnableJpaRepositories(basePackages = "com.yourpackage.repository") // 替换成你的Repository包路径
public class JpaCustomConfig {

    @Bean
    public JpaQueryFactory jpaQueryFactory(EntityManager entityManager) {
        // 创建包含自定义转换器的QueryExecutionConverter
        QueryExecutionConverter customConverter = QueryExecutionConverter.of(
                Collections.singletonList(new CustomProjectItemConverter())
        );

        // 注入自定义转换器到JpaQueryFactory
        return new JpaQueryFactory(entityManager, QueryEnhancer::forJpqlQuery, customConverter);
    }
}

3. （可选）为特定查询指定转换器 #

如果你的转换器只需要作用于某一个查询，可以直接在@Query注解中指定：

public interface ProjectRepository extends JpaRepository<Project, Integer> { 
    @Query(
        value = "select p.projectId, p.projectName, p.techstack from Project p",
        converter = CustomProjectItemConverter.class
    )
    List<ProjectItem> findAllForTest(); 
}

这样就能让Spring Data JPA使用你自定义的转换器来处理查询结果了。

内容的提问来源于stack exchange，提问作者K.Nicholas