Projections

Projections

Spring 数据查询方法通常返回存储库管理的聚合根的一个或多个实例。然而，有时可能需要基于这些类型的特定属性创建投影。Spring 数据允许建模专用返回类型，以更选择性地检索管理聚合的局部视图。 设想一个存储库和一个聚合根类型，如下例所示：

A sample aggregate and 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 数据提供哪些方法来实现此目的？本章的其余部分将回答这个问题。

Interface-based Projections

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

A projection interface to retrieve a subset of attributes
interface NamesOnly {

  String getFirstname();
  String getLastname();
}

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

A repository using an interface based projection with a query method
interface PersonRepository extends Repository<Person, UUID> {

  Collection<NamesOnly> findByLastname(String lastname);
}

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

在 Repository 中声明一个覆盖基本方法（例如，在 CrudRepository 中声明，存储特定存储库接口或 Simple…Repository 中声明）的方法，将导致调用基本方法，而不管声明的返回类型如何。请务必使用兼容的返回类型，因为基本方法不能用于投影。一些存储模块支持 @Query 注释，可将覆盖的基本方法转换成查询方法，然后可用于返回投影。

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

A projection interface to retrieve a subset of attributes
interface PersonSummary {

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

  interface AddressSummary {
    String getCity();
  }
}

在调用方法时，将获取目标实例的 address 属性，并将其依次封装到投影代理中。

Closed Projections

如果一个投影接口的访问器方法都匹配目标聚合的属性，那么该接口被认为是闭合投影。以下示例（我们也在本章中使用过）是一个闭合投影：

A closed projection
interface NamesOnly {

  String getFirstname();
  String getLastname();
}

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

Open Projections

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

An Open Projection
interface NamesOnly {

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

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

在 @Value 中使用的表达式并不应该过于复杂，你应该避免在 String 变量中进行编程。对于非常简单的表达式，可以使用默认方法（在 Java 8 中引入）来解决，如下例所示：

A projection interface using a default method for custom logic
interface NamesOnly {

  String getFirstname();
  String getLastname();

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

该方法需要你可以基于投影接口上公开的其他访问器方法来实现逻辑。第二种更灵活的方法是在 Spring bean 中实现自定义逻辑，然后从 SpEL 表达式中对其进行调用，如下例所示：

Sample Person object
@Component
class MyBean {

  String getFullName(Person person) {
    …
  }
}

interface NamesOnly {

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

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

Sample Person object
interface NamesOnly {

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

对于更复杂的表达式，你应该使用 Spring bean，并让表达式调用一个方法，如 projections.interfaces.open.bean-reference 所述。

Nullable Wrappers

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

  • java.util.Optional

  • com.google.common.base.Optional

  • scala.Option

  • io.vavr.control.Option

A projection interface using nullable wrappers
interface NamesOnly {

  Optional<String> getFirstname();
}

如果底层投影值不是 null，则使用包装器类型的当前表示形式返回值。如果支持值是 null，则 getter 方法将返回所用包装器的空表示形式。

Class-based Projections (DTOs)

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

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

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

A projecting DTO
record NamesOnly(String firstname, String lastname) {
}

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

Dynamic Projections

到目前为止，我们已经使用投影类型作为集合的返回类型或元素类型。然而，你可能需要在调用时选择要使用的类型（这会使其变成动态类型）。要应用动态投影，请使用查询方法，如以下示例所示：

A repository using a dynamic projection parameter
interface PersonRepository extends Repository<Person, UUID> {

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

通过这种方式，该方法可用于按照原样获取聚合或应用投影，如下例所示：

Using a repository with dynamic projections
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<?>。

需要注意的是，具有 JPQL 的Class-based projections 在 JPQL 表达式中仅限于*constructor expressions*，例如`SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u`。（请注意为 DTO 类型使用 FQDN！）此 JPQL 表达式也可以在定义任何命名查询的`@Query` 注释中使用。重要的是要指出，基于类的映射根本不适用于原生查询。作为一种解决办法，您可以使用带有`ResultSetMapping` 或 Hibernate 特定的 ResultTransformer 的命名查询