投影

介紹

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 = "…") 提供結果對映名稱。