Spring Data JPA中利用JPQL或接口投影查询关联实体特定字段

本文深入探讨了在spring data jpa中，如何高效且正确地使用jpql或接口投影（interface-based projections）来查询关联实体（如`subject`和`category`）的特定字段。文章通过分析常见的错误，提供了两种主要解决方案：声明式repository方法和自定义jpql查询，并强调了在使用投影时需注意的数据类型、查询语法以及与spring data rest集成时的序列化问题，旨在帮助开发者避免常见陷阱，优化数据查询性能。

实体模型概述

在深入探讨查询方法之前，我们首先定义两个关联的实体：Subject（科目）和Category（类别）。Subject实体包含一个date字段，并与Category实体存在多对一（ManyToOne）关联关系。

import javax.persistence.*;
import java.util.Date;
import java.util.HashSet;
import java.util.Set;

// Subject实体
@Entity
@Table(name="Subject")
public class Subject {

    @Id
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    private Integer id; // 使用包装类型Integer

    @Column(name = "lesson_date") // 避免使用数据库保留字'date'
    public Date date;

    @ManyToOne
    @JoinColumn(name="course_category", nullable=false)
    private Category category;

    // Getters and Setters
    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }
    public Date getDate() { return date; }
    public void setDate(Date date) { this.date = date; }
    public Category getCategory() { return category; }
    public void setCategory(Category category) { this.category = category; }
}

// Category实体
@Entity
@Table(name="Category")
public class Category {
    @Id
    @Column(name="id")
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    private Integer id; // 使用包装类型Integer

    @Column(name="name") // 添加name字段便于示例
    private String name;

    @OneToMany(cascade=CascadeType.ALL, mappedBy="category")
    private Set subject=new HashSet<>();

    // Getters and Setters
    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public Set getSubject() { return subject; }
    public void setSubject(Set subject) { this.subject = subject; }
}

注意：为了避免潜在问题，我们将原始类型int改为包装类型Integer，并将Subject实体中的date字段名更改为lesson_date，以避免与数据库保留字冲突。

接口投影（Interface-based Projections）

当我们需要从实体中只检索部分字段，而不是整个实体对象时，接口投影是一种非常有效且推荐的方法。它允许我们定义一个接口，其中包含我们希望获取的字段的Getter方法。

import java.util.Date;

public interface DatesOnly {
    Date getDate();
}

这个DatesOnly接口定义了一个getDate()方法，表明我们只对Subject实体的date字段感兴趣。

常见问题与错误分析

最初尝试直接在@Query中使用Select s.date并返回Page或List可能会遇到以下错误：

1. Couldn't find persistentEntity for type class java.sql.Timestamp...: 当JPQL查询直接返回一个基本类型（如Date或Timestamp）时，Spring Data JPA在某些上下文（特别是与Spring Data REST结合时）可能期望返回一个可以映射到持久化实体的类型。直接返回Date对象，它不是一个实体，也不是一个Spring Data JPA能够直接处理的投影接口的代理对象，因此导致无法找到对应的PersistentEntity。

2. MappingException: Couldn't find PersistentEntity for type class jdk.proxy4.$Proxy133: 当尝试将Select s.date的结果映射到List时，如果Spring Data JPA无法正确地为DatesOnly接口生成代理实例（因为查询结果是裸露的Date，而不是一个包含getDate()方法的对象），就会抛出此错误。Spring Data JPA需要能够代理DatesOnly接口，并调用其getDate()方法来填充数据。如果查询只返回Date本身，代理对象将无法找到getDate()方法的实现。

解决方案一：声明式Repository方法（推荐）

Spring Data JPA的强大之处在于其能够根据方法名自动生成查询。对于简单的投影查询，这是最简洁和推荐的方式。

import org.springframework.data.jpa.repository.JpaRepository;
import java.util.List;

public interface SubjectRepository extends JpaRepository {
    /**
     * 根据Category ID查询所有Subject的日期，并以DatesOnly接口投影。
     * Spring Data JPA会自动解析方法名：findAllByCategoryId
     * - findAll: 查询所有
     * - ByCategory: 根据Category实体
     * - Id: Category实体的id字段
     *
     * @param categoryId Category的ID
     * @return 包含DatesOnly投影的日期列表
     */
    List findAllByCategoryId(Integer categoryId);
}

这种方法利用了Spring Data JPA的命名查询约定。findAllByCategoryId(Integer categoryId)会被自动翻译成类似SELECT s FROM Subject s WHERE s.category.id = :categoryId的查询，然后Spring Data JPA会为每个Subject实体创建一个DatesOnly接口的代理实例，并填充date字段。

有道智云AI开放平台

有道智云AI开放平台

下载

解决方案二：使用JPQL进行投影

如果查询逻辑较为复杂，无法通过方法名表达，或者需要进行聚合操作，可以继续使用@Query注解编写JPQL。然而，为了使接口投影正常工作，JPQL查询需要返回整个实体对象，或者使用构造器表达式来明确创建投影接口的实例。

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import java.util.List;

public interface SubjectRepository extends JpaRepository {

    /**
     * 使用JPQL查询，返回Subject实体，然后通过DatesOnly接口进行投影。
     * 注意：JPQL查询必须返回一个实体或一个能被投影接口处理的对象。
     *
     * @param id Category的ID
     * @return 包含DatesOnly投影的日期列表
     */
    @Query("Select s from Subject s Where s.category.id = :id")
    List findDatesProjectedBySomeId(Integer id);

    // 另一种更明确的JPQL投影方式：构造器表达式
    // @Query("SELECT new com.edugreat.akademiksresource.DatesOnlyImpl(s.date) FROM Subject s WHERE s.category.id = :id")
    // List findDatesWithConstructorProjection(Integer id);
    // 此时需要一个实现DatesOnly接口的类，并提供对应的构造函数。
}

关键点：JPQL查询从Select s.date改为Select s。这意味着查询返回的是Subject实体对象，而不是单个Date字段。Spring Data JPA接收到Subject实体后，能够为DatesOnly接口生成代理，并从Subject实体中提取getDate()方法所需的数据。

示例控制器与测试

为了验证上述解决方案，我们可以创建一个简单的REST控制器来暴露这些查询方法。

import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/subjects")
public class SubjectController {
    private final SubjectRepository subjectRepository;

    public SubjectController(SubjectRepository subjectRepository) {
        this.subjectRepository = subjectRepository;
    }

    @PostMapping
    public Subject createSubject(@RequestBody Subject subject) {
        return subjectRepository.save(subject);
    }

    @GetMapping("/byCategory/{id}")
    public List getDatesByCategoryId(@PathVariable Integer id) {
        // 使用声明式Repository方法
        return subjectRepository.findAllByCategoryId(id);
    }

    @GetMapping("/byCategoryJPQL/{id}")
    public List getDatesByCategoryIdJPQL(@PathVariable Integer id) {
        // 使用JPQL查询方法
        return subjectRepository.findDatesProjectedBySomeId(id);
    }
}

测试步骤：

1. 初始化Category数据：

   insert into category(name) values ('test_category');

2. 创建Subject数据： 向/subjects端点发送POST请求（例如，多次发送以创建多个科目）：

   {
       "category": {
           "id": 1
       },
       "date": "2023-10-26T10:00:00.000Z"
   }

3. 查询日期列表： 访问GET /subjects/byCategory/1 或 GET /subjects/byCategoryJPQL/1，将返回类似以下结构的JSON响应：

   [
     {
       "date": "2023-10-26T10:00:00.000+00:00"
     },
     {
       "date": "2023-10-26T10:00:00.000+00:00"
     }
   ]

   这表明接口投影已成功工作，只返回了我们期望的date字段。

注意事项与最佳实践

1. 移除Repository方法中的@RequestParam： 在Spring Data JPA的Repository接口方法参数上使用@RequestParam是无效的。该注解通常用于Spring MVC控制器方法，用于从HTTP请求参数中绑定值。在Repository中，参数名（或@Param注解指定的名字）直接与JPQL中的命名参数匹配。

2. 统一使用包装类型而非基本类型： 在JPA实体中，推荐使用包装类型（如Integer, Long, Boolean, Date）而不是基本类型（int, long, boolean）。包装类型是可空的，这与数据库中可能存在的NULL值相对应。使用基本类型可能会导致在数据库值为NULL时出现NullPointerException或默认值问题。

3. 避免使用数据库保留字作为字段名： 如本例中的date，在许多数据库中是保留字。虽然某些ORM或数据库可能允许，但通常会导致潜在的兼容性问题或需要额外的引用（如"date"）。建议使用更具描述性且非保留字的名称，例如lessonDate或creationDate。

4. 处理双向关联的序列化问题： 如果Subject和Category之间存在双向关联（@OneToMany和@ManyToOne），并且你通过REST API返回这些实体，可能会遇到StackOverflowError。这是因为Jackson（Spring Boot默认的JSON序列化库）在序列化时会陷入无限循环：Subject包含Category，Category又包含Subject的集合，如此往复。 为解决此问题，可以使用@JsonManagedReference和@JsonBackReference注解：

   • 在关系的主导方（通常是“一”的一方，如Category的subject集合）上使用@JsonManagedReference。
   • 在关系的被引用方（通常是“多”的一方，如Subject的category字段）上使用@JsonBackReference。 例如：

     // Category实体
     public class Category {
     // ...
     @OneToMany(cascade=CascadeType.ALL, mappedBy="category")
     @JsonManagedReference // 标记为管理方
     private Set subject=new HashSet<>();
     // ...
     }

   // Subject实体 public class Subject { // ... @ManyToOne @JoinColumn(name="course_category", nullable=false) @JsonBackReference // 标记为被引用方 private Category category; // ... }

   这样，在序列化`Category`时会包含`Subject`列表，但在序列化`Subject`时会忽略其`Category`字段，从而避免循环引用。

总结

Spring Data JPA提供了灵活多样的查询机制，尤其在处理部分字段查询时，接口投影是一个极其有用的特性。通过声明式Repository方法，我们可以实现简洁高效的查询；而对于更复杂的场景，JPQL结合实体返回的方式也能很好地支持接口投影。同时，遵循良好的编程实践，如使用包装类型、避免保留字以及正确处理双向关联的序列化，将有助于构建健壮且可维护的应用程序。理解这些核心概念和最佳实践，将使你在Spring Data JPA的数据访问层开发中游刃有余。