投影

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

現在想像一下，我們只想檢索人員的姓名屬性。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，則使用包裝器類型的 present-representation 返回值。如果後端值為 null，則 getter 方法返回所用包裝器類型的空表示形式。



基於類別的投影 (DTO)


定義投影的另一種方法是使用值類型 DTO（資料傳輸物件），它們保存要檢索的欄位的屬性。這些 DTO 類型可以與投影介面以完全相同的方式使用，但不會發生代理，也無法應用巢狀投影。


如果儲存庫通過限制要載入的欄位來最佳化查詢執行，則要載入的欄位是從公開的建構子的參數名稱確定的。


以下範例顯示了一個投影 DTO


投影 DTO

record NamesOnly(String firstname, String lastname) {
}



Java Records 是定義 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<?>。