投影

介绍

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

想象一下如下所示的 repository 和聚合根类型示例

聚合和 Repository 示例

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();
}

此处重要的是，此处定义的属性与聚合根中的属性完全匹配。这样做就可以添加查询方法，如下所示

使用基于接口投影和查询方法的 Repository

interface PersonRepository extends Repository<Person, UUID> {

  Collection<NamesOnly> findByLastname(String lastname);
}

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

在你的 Repository 中声明一个覆盖基础方法（例如，在 CrudRepository 中声明的、特定于存储的 repository 接口或 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 表达式中调用它，如下所示

人员对象示例

@Component
class MyBean {

  String getFullName(Person person) {
    …
  }
}

interface NamesOnly {

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

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

人员对象示例

interface NamesOnly {

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

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

可空包装器

投影接口中的 getter 方法可以使用可空包装器来提高 null 安全性。当前支持的包装器类型有

java.util.Optional
com.google.common.base.Optional
scala.Option
io.vavr.control.Option

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

interface NamesOnly {

  Optional<String> getFirstname();
}

如果底层投影值不是 null，则使用包装器类型的 present 表示返回值。如果 backing 值是 null，则 getter 方法返回所用包装器类型的 empty 表示。

基于类的投影 (DTO)

定义投影的另一种方法是使用值类型 DTO（数据传输对象），这些对象包含要检索的字段的属性。这些 DTO 类型的使用方式与投影接口完全相同，不同之处在于不会发生代理，并且不能应用嵌套投影。

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

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

投影 DTO 示例

record NamesOnly(String firstname, String lastname) {
}

Java Records 是定义 DTO 类型的理想选择，因为它们遵循值语义：所有字段都是 private final，并且会自动创建 equals(…)/hashCode()/toString() 方法。另外，你可以使用任何定义了要投影属性的类。

动态投影

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

使用动态投影参数的 Repository

interface PersonRepository extends Repository<Person, UUID> {

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

这样，该方法可以用于获取聚合本身，或者应用投影，如下所示

使用动态投影的 Repository

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 的实例化机制（构造函数表达式）来创建投影实例。

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

基于字符串的查询

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

JPQL 查询

当使用基于类的投影进行 JPQL 查询时，你必须在 JPQL 查询中使用构造函数表达式，例如 SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u。（注意 DTO 类型使用了 FQDN！）此 JPQL 表达式也可用于 @Query 注解来定义命名查询。作为一种变通方法，你可以使用带有 ResultSetMapping 的命名查询或 Hibernate 特定的 ResultListTransformer

原生查询

当使用基于类的投影时，其用法需要根据你的... 进行稍微更多的考虑。

如果结果类型的属性直接映射到结果（列的顺序及其类型与构造函数参数匹配），则无需额外提示即可将查询结果类型声明为 DTO 类型（或通过动态投影使用 DTO 类）。
如果属性不匹配或需要转换，请使用 @SqlResultSetMapping 通过 JPA 的注解将结果集映射到 DTO，并通过 @NativeQuery(resultSetMapping = "…") 提供结果映射名称。