跳到主要内容

投影

DeepSeek V3 中英对照 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);
}
java

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

备注

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

基于接口的投影​

将查询结果限制为仅包含 name 属性的最简单方法是声明一个接口，该接口公开用于读取这些属性的访问器方法，如下例所示：

interface NamesOnly {

  String getFirstname();
  String getLastname();
}
java

这里的关键在于，此处定义的属性与聚合根中的属性完全匹配。这样做可以让查询方法按如下方式添加：

interface PersonRepository extends Repository<Person, UUID> {

  Collection<NamesOnly> findByLastname(String lastname);
}
java

查询执行引擎在运行时为该接口创建代理实例，并将暴露方法的调用转发给目标对象。

备注

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

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

interface PersonSummary {

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

  interface AddressSummary {
    String getCity();
  }
}
java

在方法调用时，目标实例的 address 属性会被获取并依次包装到一个投影代理中。

闭合投影​

一个投影接口，其访问器方法全部匹配目标聚合体的属性，被视为一个封闭投影。以下示例（我们在本章前面也使用过）便是一个封闭投影：

interface NamesOnly {

  String getFirstname();
  String getLastname();
}
java

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

开放投影​

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

interface NamesOnly {

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

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

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

interface NamesOnly {

  String getFirstname();
  String getLastname();

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

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

@Component
class MyBean {

  String getFullName(Person person) {
    …
  }
}

interface NamesOnly {

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

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

interface NamesOnly {

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

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

可空包装器​

在投影接口中的 getter 方法可以使用可为空的包装器来提高空安全性。目前支持的包装器类型包括：

  • java.util.Optional

  • com.google.common.base.Optional

  • scala.Option

  • io.vavr.control.Option

interface NamesOnly {

  Optional<String> getFirstname();
}
java

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

基于类的投影（DTOs）​

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

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

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

record NamesOnly(String firstname, String lastname) {
}
java

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

动态投影​

到目前为止，我们已经将投影类型用作集合的返回类型或元素类型。然而，您可能希望在选择类型时根据调用时的需求进行动态决定。为了实现动态投影，可以使用如下示例中的查询方法：

interface PersonRepository extends Repository<Person, UUID> {

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

这样，该方法既可以用于直接获取聚合结果，也可以在应用投影后获取聚合结果，如下例所示：

void someMethod(PersonRepository people) {

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

  Collection<NamesOnly> aggregates =
    people.findByLastname("Matthews", NamesOnly.class);
}
java
备注

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

  // ...
}
java

在 JPA 中使用投影​

你可以通过多种方式在 JPA 中使用投影（Projections）。根据技术和查询类型的不同，你需要应用特定的注意事项。

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

派生查询​

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

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

基于字符串的查询​

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

JPQL 查询​

在使用 JPQL 的基于类的投影时，你必须在 JPQL 查询中使用构造器表达式，例如 SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u。（注意 DTO 类型使用了完全限定域名！）这个 JPQL 表达式也可以用在 @Query 注解中，你可以在其中定义任何命名查询。作为一种替代方案，你可以使用带有 ResultSetMapping 的命名查询，或者使用 Hibernate 特有的 ResultListTransformer。

原生查询​

在使用基于类的投影时，根据你的具体情况，其使用方式需要稍加考虑。

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

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