投影

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 表达式中调用该逻辑，如下例所示

示例 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 方法返回所用包装器类型的空表示形式。

基于类的投影 (DTOs)

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

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

以下示例展示了一个投影 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;
  }

  // ...
}