Spring Data JPA 投影：从关联实体中高效获取特定字段列表

本文深入探讨了在 spring data jpa 中如何从关联实体中高效地查询并返回特定字段列表。通过分析直接返回原始类型和不当使用接口投影时遇到的常见错误，文章提供了两种正确的解决方案：利用 spring data jpa 的方法命名查询以及通过 jpql 显式选择实体进行投影。此外，还分享了使用 jpa 和 spring data rest 时的多项最佳实践和注意事项。

Spring Data JPA 投影：从关联实体中高效获取特定字段列表

在现代企业级应用开发中，数据访问层（DAO）是不可或缺的一部分。Spring Data JPA 极大地简化了数据库操作，但当需要从关联实体中选择特定字段并将其投影到自定义结构时，开发者可能会遇到一些挑战。本教程将通过一个具体的示例，详细介绍如何使用 Spring Data JPA 的接口投影功能，从关联实体中获取所需数据，并探讨常见的错误及其解决方案。

实体模型概览

假设我们有两个实体：Subject（科目）和 Category（类别），它们之间存在多对一（ManyToOne）关系，即一个 Category 可以包含多个 Subject。

// Category 实体
@Entity
@Table(name="Category")
public class Category {
    @Id
    @Column(name="id")
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    private Integer id; // 建议使用包装类型
    // ... 其他字段和方法

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

// Subject 实体
@Entity
@Table(name="Subject")
public class Subject {
    // ... 其他字段和方法

    @Column(name = "date") // 建议避免使用 "date" 作为列名，因为它可能是数据库保留字
    public Date date; // 建议使用 java.util.Date 或 java.time.LocalDate/LocalDateTime

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

我们的目标是根据 Category 的 ID，查询所有关联 Subject 的 date 字段，并将其作为列表返回。

常见问题与错误分析

开发者在尝试实现上述目标时，通常会遇到以下两种错误场景：

尝试一：直接查询原始类型并分页

最初，开发者可能尝试使用 JPQL 直接查询 Subject 的 date 字段，并期望将其封装到 Page 中：

public interface SubjectDao extends JpaRepository{
    @Query("Select s.date from Subject s Where s.category.id=:id")
    Page findDates(@RequestParam("id") int id, Pageable pegeable); // @RequestParam 在这里无效
}

执行此查询时，可能会收到类似以下错误：

Couldn't find persistentEntity for type class java.sql.Timestamp...

错误原因分析： Spring Data JPA 的 Page 返回类型通常期望返回的是 JPA 实体、DTO 或通过构造函数表达式明确映射的对象。当您直接选择一个原始类型（如 java.util.Date，它在数据库中可能映射为 java.sql.Timestamp）时，Spring Data JPA 无法为其找到一个 PersistentEntity 来进行管理和分页。它不知道如何将一个简单的 Date 对象视为一个可以分页的“实体”。

尝试二：使用接口投影但 JPQL 选择不当

为了解决上述问题，开发者可能会转向 Spring Data JPA 的接口投影（Interface-based Projection）技术。首先定义一个只包含 date 字段的接口：

public interface DatesOnly {
    Date getDate();
}

然后修改 SubjectDao 接口，尝试将 s.date 投影到 DatesOnly 列表：

public interface SubjectDao extends JpaRepository{
    @Query("Select s.date from Subject s where s.category.id =:id")
    List findDates(@RequestParam("id")int id); // @RequestParam 在这里仍然无效
}

此时，运行代码可能会遇到以下错误：

org.springframework.data.mapping.MappingException: Couldn't find PersistentEntity for type class jdk.proxy4.$Proxy133
    at org.springframework.data.mapping.context.MappingContext.getRequiredPersistentEntity(MappingContext.java:80)
    ...

错误原因分析： Spring Data JPA 的接口投影工作原理是创建一个代理对象，该代理对象实现了投影接口，并将其方法调用（如 getDate()）委托给底层的数据源。当您在 JPQL 中 Select s.date 时，查询结果实际上是一个 List。Spring Data JPA 尝试将每个 Date 对象映射到 DatesOnly 接口的代理实例。然而，一个 Date 对象本身并没有 getDate() 方法（或者说，它就是日期本身，而不是一个包含日期的对象）。Spring Data JPA 无法将一个原始 Date 类型直接代理成 DatesOnly 接口，因为它需要一个“拥有” date 属性的实体（例如 Subject 实体）来创建代理。

正确的解决方案

理解了上述错误原因后，我们可以采用两种正确的方式来实现目标。

黑点工具

在线工具导航网站，免费使用无需注册，快速使用无门槛。

下载

方案一：使用 Spring Data JPA 的方法命名查询 (推荐)

Spring Data JPA 允许通过方法名称自动生成查询。对于接口投影，这是最简洁和推荐的方式。

1. 定义投影接口： 保持 DatesOnly 接口不变。

   public interface DatesOnly {
       Date getDate();
   }

2. 修改 Repository 接口： 使用 Spring Data JPA 的方法命名约定来定义查询。findAllByCategoryId 会根据 Category 的 id 字段查找所有 Subject，并自动将结果投影到 DatesOnly。

   import org.springframework.data.jpa.repository.JpaRepository;
   import java.util.List;
   import java.util.Date; // 确保导入正确的 Date 类型
   
   public interface SubjectRepository extends JpaRepository {
       // 根据 Category ID 查找所有 Subject 并投影其日期
       List findAllByCategoryId(Integer categoryId);
   }

   说明：

   • findAllByCategoryId 是一个典型的 Spring Data JPA 方法命名查询。它会解析为 SELECT s FROM Subject s WHERE s.category.id = ?。
   • 当返回类型是 DatesOnly 接口的 List 时，Spring Data JPA 会自动创建 DatesOnly 的代理实例，并将每个 Subject 实体中的 date 字段映射到代理实例的 getDate() 方法。

3. 示例 Controller (用于测试)： 为了演示如何使用，我们可以创建一个简单的 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("/dates-by-category/{categoryId}")
       public List getDatesByCategoryId(@PathVariable Integer categoryId) {
           return subjectRepository.findAllByCategoryId(categoryId);
       }
   }

   测试数据示例：

   • 首先向 Category 表插入一条记录：insert into category(id, name) values (1, 'Test Category')。
   • 然后通过 POST /subjects 接口创建多个 Subject 实例，例如：

     {
         "category": {
             "id": 1
         },
         "date": "2022-11-24T19:07:19.097303"
     }

   • 最后访问 GET /subjects/dates-by-category/1，您将获得类似以下输出：

     [
       {
         "date": "2022-11-24T19:07:19.097+00:00"
       },
       {
         "date": "2022-11-24T19:07:19.097+00:00"
       }
       // ... 更多日期
     ]

方案二：使用 JPQL 显式选择实体进行投影

如果您确实需要使用 JPQL 进行更复杂的查询，同时又想利用接口投影，那么关键在于在 JPQL 中选择整个实体，而不是单个字段。

1. 定义投影接口： 同样，DatesOnly 接口保持不变。

   public interface DatesOnly {
       Date getDate();
   }

2. 修改 Repository 接口： 在 @Query 注解中，选择 Subject 实体 (Select s)，而不是 s.date。

   import org.springframework.data.jpa.repository.JpaRepository;
   import org.springframework.data.jpa.repository.Query;
   import java.util.List;
   import java.util.Date;
   
   public interface SubjectRepository extends JpaRepository {
       @Query("Select s from Subject s Where s.category.id=:id")
       List findDatesProjectedBySomeId(Integer id); // 注意参数不再需要 @RequestParam
   }

   说明：

   • 通过 Select s，JPQL 返回的是 Subject 实体列表。
   • Spring Data JPA 接收到 Subject 实体后，会根据 DatesOnly 接口的方法名 (getDate())，查找 Subject 实体中对应的 date 字段，并创建 DatesOnly 的代理实例。

注意事项与最佳实践

在 Spring Data JPA 和实体设计中，还有一些重要的最佳实践值得遵循：

1. Repository 方法中的 @RequestParam： 在 Spring Data JPA 的 Repository 接口方法中，@RequestParam 注解是无效的。它通常用于 Spring MVC/Webflux 控制器方法中，用于从 HTTP 请求参数中绑定值。Repository 方法的参数会直接映射到 JPQL 或方法命名查询中的占位符。

2. 原始类型与包装类型： 在 JPA 实体中使用包装类型（如 Integer 而非 int）是更好的实践。包装类型可以为 null，这在数据库字段可为空时非常有用，并且可以避免不必要的自动装箱/拆箱操作。

3. 避免使用数据库保留字作为列名： 例如，date 是许多数据库系统的保留字。虽然某些 ORM 可能会处理这种情况，但为了避免潜在的冲突和混淆，建议使用更具体的名称，如 eventDate 或 subjectDate。

4. 处理双向关联的序列化问题： 在 OneToMany 和 ManyToOne 等双向关联中，如果直接进行 JSON 序列化（例如，通过 Spring Data REST 或 @RestController 返回实体），可能会导致 StackOverflowError，因为它们会尝试无限循环地序列化彼此。 为了解决这个问题，可以使用 Jackson 提供的注解，如 @JsonManagedReference 和 @JsonBackReference：

   // Category 实体
   @Entity
   @Table(name="Category")
   public class Category {
       // ...
       @OneToMany(cascade=CascadeType.ALL, mappedBy="category")
       @JsonManagedReference // 这是“拥有”引用的一方
       private Set subject = new HashSet<>();
   }
   
   // Subject 实体
   @Entity
   @Table(name="Subject")
   public class Subject {
       // ...
       @ManyToOne
       @JoinColumn(name="course_category", nullable=false)
       @JsonBackReference // 这是“被引用”的一方
       private Category category;
   }

   @JsonManagedReference 标注的字段会被正常序列化，而 @JsonBackReference 标注的字段在序列化时会被忽略，从而打破循环。

总结

通过本教程，我们学习了在 Spring Data JPA 中使用接口投影从关联实体中获取特定字段列表的正确方法。关键在于理解 Spring Data JPA 投影的工作机制：无论是通过方法命名查询还是 JPQL，当返回接口投影时，查询结果需要包含能够提供接口方法所需数据（通常是整个实体或包含这些数据的 DTO）的对象。同时，遵循良好的 JPA 和实体设计实践，可以帮助我们构建更健壮、更易于维护的应用程序。