投影

简介

Spring Data 查询方法通常返回由仓库管理的聚合根的一个或多个实例。然而，有时可能需要基于这些类型的某些属性创建投影。Spring Data 允许建模专用的返回类型，以更选择性地检索受管聚合的部分视图。

假设有一个仓库和聚合根类型，例如以下示例：

示例聚合和仓库
class Person {

  @Id UUID id;
  String firstname, lastname;
  Address address;

  static class Address {
    String zipCode, city, street;
  }
}

interface PersonRepository extends Repository<Person, UUID> {

  Collection<Person> findByLastname(String lastname);
}

现在假设我们只想检索人员的名称属性。Spring Data 提供了哪些方法来实现这一点？本章的其余部分将回答这个问题。

投影类型是位于实体类型层次结构之外的类型。实体实现的超类和接口位于类型层次结构之内，因此返回超类型（或实现的接口）将返回完全具体化实体的实例。

基于接口的投影

将查询结果限制为仅名称属性的最简单方法是声明一个接口，该接口公开要读取的属性的访问器方法，如以下示例所示：

用于检索属性子集的投影接口
interface NamesOnly {

  String getFirstname();
  String getLastname();
}

这里的关键在于，此处定义的属性与聚合根中的属性完全匹配。这样做允许添加一个查询方法，如下所示：

使用基于接口的投影和查询方法的仓库
interface PersonRepository extends Repository<Person, UUID> {

  Collection<NamesOnly> findByLastname(String lastname);
}

查询执行引擎在运行时为返回的每个元素创建该接口的代理实例，并将对公开方法的调用转发到目标对象。

在您的 Repository 中声明一个覆盖基本方法（例如在 CrudRepository、特定于存储的仓库接口或 Simple...Repository 中声明）的方法，无论声明的返回类型如何，都将导致对基本方法的调用。请确保使用兼容的返回类型，因为基本方法不能用于投影。某些存储模块支持 @Query 注解，将重写的基本方法转换为查询方法，然后可用于返回投影。

投影可以递归使用。如果您还想包含一些 Address 信息，请为其创建一个投影接口，并从 getAddress() 的声明中返回该接口，如以下示例所示：

用于检索属性子集的投影接口
interface PersonSummary {

  String getFirstname();
  String getLastname();
  AddressSummary getAddress();

  interface AddressSummary {
    String getCity();
  }
}

在方法调用时，将获取目标实例的 address 属性，并将其包装成一个投影代理。

封闭式投影

一个投影接口，其所有访问器方法都与目标聚合的属性匹配，被认为是封闭式投影。以下示例（我们之前在本章中也使用过）是封闭式投影：

封闭式投影
interface NamesOnly {

  String getFirstname();
  String getLastname();
}

如果您使用封闭式投影，Spring Data 可以优化查询执行，因为我们知道支持投影代理所需的所有属性。有关更多详细信息，请参阅参考文档中特定于模块的部分。

开放式投影

投影接口中的访问器方法也可以通过使用 @Value 注解来计算新值，如以下示例所示：

开放式投影
interface NamesOnly {

  @Value("#{target.firstname + ' ' + target.lastname}")
  String getFullName();
  …
}

支持投影的聚合根在 target 变量中可用。使用 @Value 的投影接口是一个开放式投影。在这种情况下，Spring Data 无法应用查询执行优化，因为 SpEL 表达式可以使用聚合根的任何属性。

@Value 中使用的表达式不应过于复杂——您应该避免在 String 变量中进行编程。对于非常简单的表达式，一种选择是使用默认方法（在 Java 8 中引入），如以下示例所示：

使用默认方法实现自定义逻辑的投影接口
interface NamesOnly {

  String getFirstname();
  String getLastname();

  default String getFullName() {
    return getFirstname().concat(" ").concat(getLastname());
  }
}

这种方法要求您能够纯粹基于投影接口上公开的其他访问器方法来实现逻辑。第二种更灵活的选择是在 Spring bean 中实现自定义逻辑，然后从 SpEL 表达式中调用它，如以下示例所示：

示例 Person 对象
@Component
class MyBean {

  String getFullName(Person person) {
    …
  }
}

interface NamesOnly {

  @Value("#{@myBean.getFullName(target)}")
  String getFullName();
  …
}

请注意，SpEL 表达式如何引用 myBean 并调用 getFullName(…) 方法，并将投影目标作为方法参数转发。由 SpEL 表达式评估支持的方法也可以使用方法参数，然后可以在表达式中引用这些参数。方法参数通过名为 args 的 Object 数组可用。以下示例显示了如何从 args 数组中获取方法参数：

示例 Person 对象
interface NamesOnly {

  @Value("#{args[0] + ' ' + target.firstname + '!'}")
  String getSalutation(String prefix);
}

同样，对于更复杂的表达式，您应该使用 Spring bean 并让表达式调用方法，如前面所述。

可空包装器

投影接口中的 getter 可以利用可空包装器来提高空安全性。目前支持的包装器类型有：

  • java.util.Optional

  • com.google.common.base.Optional

  • scala.Option

  • io.vavr.control.Option

使用可空包装器的投影接口
interface NamesOnly {

  Optional<String> getFirstname();
}

如果底层投影值不为 null，则使用包装器类型的存在表示返回这些值。如果支持值为 null，则 getter 方法返回所用包装器类型的空表示。

基于类的投影（DTO）

定义投影的另一种方法是使用值类型 DTO（数据传输对象），它们包含要检索的字段的属性。这些 DTO 类型可以像投影接口一样使用，只是不发生代理，也无法应用嵌套投影。

如果存储通过限制要加载的字段来优化查询执行，则要加载的字段将从公开的构造函数的参数名称中确定。

以下示例显示了一个投影 DTO：

投影 DTO
record NamesOnly(String firstname, String lastname) {
}

Java 记录非常适合定义 DTO 类型，因为它们遵循值语义：所有字段都是 private final，并且自动创建 equals(…)/hashCode()/toString() 方法。或者，您可以使用任何定义要投影的属性的类。

动态投影

到目前为止，我们已经将投影类型用作返回类型或集合的元素类型。但是，您可能希望在调用时选择要使用的类型（这使其具有动态性）。要应用动态投影，请使用如下所示的查询方法：

使用动态投影参数的仓库
interface PersonRepository extends Repository<Person, UUID> {

  <T> Collection<T> findByLastname(String lastname, Class<T> type);
}

这样，该方法可以用于按原样获取聚合或应用投影后获取聚合，如以下示例所示：

使用带有动态投影的仓库
void someMethod(PersonRepository people) {

  Collection<Person> aggregates =
    people.findByLastname("Matthews", Person.class);

  Collection<NamesOnly> aggregates =
    people.findByLastname("Matthews", NamesOnly.class);
}
类型为 Class 的查询参数将检查它们是否符合动态投影参数的条件。如果查询的实际返回类型等于 Class 参数的泛型参数类型，则匹配的 Class 参数不可用于查询或 SpEL 表达式中使用。如果您希望将 Class 参数用作查询参数，请确保使用不同的泛型参数，例如 Class<?>。

当使用基于类的投影时，类型必须声明单个构造函数，以便 Spring Data 可以确定它们的输入属性。如果您的类定义了多个构造函数，则不能在没有进一步提示的情况下将该类型用于 DTO 投影。在这种情况下，请用 @PersistenceCreator 注解所需的构造函数，如下所示，以便 Spring Data 可以确定要选择哪些属性：

public class NamesOnly {

  private final String firstname;
  private final String lastname;

  protected NamesOnly() { }

  @PersistenceCreator
  public NamesOnly(String firstname, String lastname) {
      this.firstname = firstname;
      this.lastname = lastname;
  }

  // ...
}

使用 JPA 投影

您可以通过多种方式使用 JPA 投影。根据技术和查询类型，您需要应用特定的注意事项。

Spring Data JPA 通常使用 Tuple 查询来为基于接口的投影构建接口代理。

派生查询

查询派生通过内省返回类型来支持基于类和基于接口的投影。基于类的投影使用 JPA 的实例化机制（构造函数表达式）来创建投影实例。

投影将选择限制在目标实体的顶级属性。任何解析为连接的嵌套属性都会选择整个嵌套属性，导致完全连接具象化。

基于字符串的查询

对基于字符串的查询的支持涵盖了 JPQL 查询 (@Query) 和原生查询 (@NativeQuery)。

JPQL 查询

JPA 使用 JPQL 返回基于类的投影的机制是构造函数表达式。因此，您的查询必须定义一个构造函数表达式，例如 SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u。（请注意 DTO 类型使用了 FQDN！）此 JPQL 表达式也可以在 @Query 注解中使用，您可以在其中定义任何命名查询。作为一种变通方法，您可以使用带有 ResultSetMapping 的命名查询或 Hibernate 特定的 ResultListTransformer。

如果您的查询选择主实体或选择项列表，Spring Data JPA 可以帮助您将查询重写为构造函数表达式。

DTO 投影 JPQL 查询重写

JPQL 查询允许通过构造函数表达式选择根对象、单个属性和 DTO 对象。使用构造函数表达式可以快速为查询添加大量文本，并使其难以阅读实际查询。Spring Data JPA 可以通过引入构造函数表达式来方便您处理 JPQL 查询。

考虑以下查询

示例 1. 投影查询
interface UserRepository extends Repository<User, Long> {

  @Query("SELECT u FROM USER u WHERE u.lastname = :lastname")                       (1)
  List<UserDto> findByLastname(String lastname);

  @Query("SELECT u.firstname, u.lastname FROM USER u WHERE u.lastname = :lastname") (2)
  List<UserDto> findMultipleColumnsByLastname(String lastname);
}

record UserDto(String firstname, String lastname){}
1 选择顶级实体。此查询将被重写为 SELECT new UserDto(u.firstname, u.lastname) FROM USER u WHERE u.lastname = :lastname。
2 多选 firstname 和 lastname 属性。此查询将被重写为 SELECT new UserDto(u.firstname, u.lastname) FROM USER u WHERE u.lastname = :lastname。

JPQL 构造函数表达式不能包含所选列的别名，查询重写不会为您删除它们。虽然 SELECT u as user, count(u.roles) as roleCount FROM USER u … 是基于接口的投影（依赖于返回的 Tuple 中的列名）的有效查询，但当请求 DTO 时，相同的构造是无效的，此时它需要是 SELECT u, count(u.roles) FROM USER u …。
一些持久化提供程序可能对此宽容，而另一些则不然。

返回 DTO 投影类型（域类型层次结构之外的 Java 类型）的仓库查询方法需要进行查询重写。如果 @Query 注解的查询已使用构造函数表达式，则 Spring Data 会回退并且不应用 DTO 构造函数表达式重写。

确保您的 DTO 类型为投影提供一个全参构造函数，否则查询将失败。

原生查询

使用基于类的投影时，根据您的具体情况，其使用需要更多考虑。

  • 如果结果类型的属性直接映射到结果（列的顺序及其类型与构造函数参数匹配），那么您可以将查询结果类型声明为 DTO 类型，而无需进一步提示（或通过动态投影使用 DTO 类）。

  • 如果属性不匹配或需要转换，请通过 JPA 的注解使用 @SqlResultSetMapping 将结果集映射到 DTO，并通过 @NativeQuery(resultSetMapping = "…") 提供结果映射名称。

© . This site is unofficial and not affiliated with VMware.