投影

Doubao 中英对照 Projections

介绍

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

现在设想我们只想检索 person 的姓名属性。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 表达式中调用它，如下例所示：

@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 可以利用可空包装类型来提升空安全。目前支持的包装类型有：

• 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：

record NamesOnly(String firstname, String lastname) {
}

Java Record 非常适合定义 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){}

• 选择顶层实体。该查询会被重写为 SELECT new UserDto(u.firstname, u.lastname) FROM User u WHERE u.lastname = :lastname。

• 多选 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 = "…") 提供结果映射名称。