定義查詢方法

Repository 代理有兩種方法可以從方法名稱派生出特定於儲存的查詢

  • 直接從方法名稱派生查詢。

  • 使用手動定義的查詢。

可用選項取決於實際的儲存。但是，必須有一個策略來決定實際建立的查詢。下一節描述了可用選項。

查詢查詢策略

Repository 基礎設施可以使用以下策略來解析查詢。透過 XML 配置，您可以使用 query-lookup-strategy 屬性在名稱空間中配置策略。對於 Java 配置，您可以使用 EnableJpaRepositories 註解的 queryLookupStrategy 屬性。某些策略可能不適用於特定的資料儲存。

  • CREATE 嘗試從查詢方法名稱構建特定於儲存的查詢。通用方法是移除方法名稱中一組眾所周知的（well known）字首，然後解析方法的其餘部分。您可以在“查詢建立”中閱讀更多關於查詢構建的資訊。

  • USE_DECLARED_QUERY 嘗試查詢已宣告的查詢，如果找不到則丟擲異常。查詢可以透過註解或其他方式定義。請參閱特定儲存的文件以查詢該儲存的可用選項。如果在引導時 Repository 基礎設施沒有找到該方法的已宣告查詢，則會失敗。

  • CREATE_IF_NOT_FOUND（預設）結合了 CREATE 和 USE_DECLARED_QUERY。它首先查詢已宣告的查詢，如果沒有找到已宣告的查詢，則建立一個自定義的基於方法名稱的查詢。這是預設的查詢策略，因此如果您未顯式配置任何內容，則會使用它。它允許透過方法名稱快速定義查詢，同時也可以透過根據需要引入已宣告的查詢來自定義調整這些查詢。

查詢建立

內置於 Spring Data Repository 基礎設施中的查詢構建器機制對於構建針對 Repository 實體的約束查詢很有用。

以下示例展示瞭如何建立多個查詢

從方法名稱建立查詢
interface PersonRepository extends Repository<Person, Long> {

  List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);

  // Enables the distinct flag for the query
  List<Person> findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
  List<Person> findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);

  // Enabling ignoring case for an individual property
  List<Person> findByLastnameIgnoreCase(String lastname);
  // Enabling ignoring case for all suitable properties
  List<Person> findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname);

  // Enabling static ORDER BY for a query
  List<Person> findByLastnameOrderByFirstnameAsc(String lastname);
  List<Person> findByLastnameOrderByFirstnameDesc(String lastname);
}

解析查詢方法名稱分為主題（subject）和謂詞（predicate）。第一部分（find…By, exists…By）定義了查詢的主題，第二部分構成謂詞。引入從句（主題）可以包含更多表達式。find（或其他引入關鍵詞）和 By 之間的任何文字都被視為描述性的，除非使用結果限制關鍵詞，例如 Distinct 來為要建立的查詢設定 distinct 標誌，或者使用 Top/First 來限制查詢結果。

附錄包含查詢方法主題關鍵詞的完整列表以及查詢方法謂詞關鍵詞，包括排序和字母大小寫修飾符。然而，第一個 By 作為分隔符，指示實際條件謂詞的開始。在非常基本的層面，您可以定義實體屬性上的條件，並使用 And 和 Or 將它們連線起來。

解析方法的實際結果取決於您建立查詢的持久化儲存。但是，有一些一般性的事項需要注意

  • 表示式通常是屬性遍歷與可以連線的運算子的組合。您可以使用 AND 和 OR 組合屬性表示式。對於屬性表示式，您還支援 Between, LessThan, GreaterThan 和 Like 等運算子。支援的運算子可能因資料儲存而異，因此請查閱您的參考文件的相應部分。

  • 方法解析器支援為單個屬性設定 IgnoreCase 標誌（例如 findByLastnameIgnoreCase(…)），或者為支援忽略大小寫的型別（通常是 String 例項）的所有屬性設定此標誌（例如 findByLastnameAndFirstnameAllIgnoreCase(…)）。是否支援忽略大小寫可能因儲存而異，因此請查閱參考文件中針對特定儲存的查詢方法的有關章節。

  • 您可以透過在查詢方法後附加引用屬性的 OrderBy 從句，並提供排序方向（Asc 或 Desc）來應用靜態排序。要建立支援動態排序的查詢方法，請參閱“分頁、處理大型結果、排序與限制”。

保留方法名稱

雖然派生的 Repository 方法按名稱繫結到屬性，但對於從基礎 Repository 繼承的、針對識別符號屬性的某些方法名稱，此規則有一些例外。這些保留方法（reserved methods），例如 CrudRepository#findById（或僅 findById），無論在宣告的方法中使用的實際屬性名稱是什麼，它們都針對識別符號屬性。

考慮以下領域型別，它包含一個透過 @Id 標記為識別符號的 pk 屬性，以及一個名為 id 的屬性。在這種情況下，您需要密切注意查詢方法的命名，因為它們可能與預定義的簽名衝突

class User {
  @Id Long pk;                          (1)

  Long id;                              (2)

  // …
}

interface UserRepository extends Repository<User, Long> {

  Optional<User> findById(Long id);     (3)

  Optional<User> findByPk(Long pk);     (4)

  Optional<User> findUserById(Long id); (5)
}
1 識別符號屬性（主鍵）。
2 一個名為 id 的屬性，但不是識別符號。
3 由於它引用了 CrudRepository 基礎 Repository 方法，因此它針對 pk 屬性（即標記有 @Id 並被視為識別符號的屬性）。因此，它不是一個使用 id 作為屬性名稱的派生查詢，因為它屬於保留方法。
4 由於它是一個派生查詢，因此按名稱針對 pk 屬性。
5 透過使用 find 和 by 之間的描述性標記來針對 id 屬性，以避免與保留方法衝突。

這種特殊行為不僅針對查詢方法，也適用於 exits 和 delete 方法。請參閱“Repository 查詢關鍵詞”以獲取方法列表。

屬性表示式

屬性表示式只能引用受管實體的直接屬性，如前面的示例所示。在查詢建立時，您已經確保解析的屬性是受管領域類的屬性。但是，您也可以透過遍歷巢狀屬性來定義約束。考慮以下方法簽名

List<Person> findByAddressZipCode(ZipCode zipCode);

假設一個人（Person）有一個包含郵政編碼（ZipCode）的地址（Address）。在這種情況下，該方法會建立 x.address.zipCode 屬性遍歷。解析演算法首先將整個部分（AddressZipCode）解釋為屬性，並在領域類中檢查是否存在該名稱（首字母小寫）的屬性。如果演算法成功，則使用該屬性。如果失敗，演算法會從右側根據駝峰大小寫部分將源拆分為頭部和尾部，並嘗試找到相應的屬性——在我們的示例中是 AddressZip 和 Code。如果演算法找到具有該頭部的屬性，它會取尾部並從那裡繼續向下構建樹，以剛才描述的方式拆分尾部。如果第一次拆分不匹配，演算法會將拆分點向左移動（Address, ZipCode）並繼續。

雖然這在大多數情況下應該有效，但演算法有可能選擇錯誤的屬性。假設 Person 類也有一個 addressZip 屬性。演算法將在第一次拆分時就匹配到，選擇錯誤的屬性，然後失敗（因為 addressZip 的型別很可能沒有 code 屬性）。

為了解決這種歧義，您可以在方法名稱中使用 _ 來手動定義遍歷點。因此，我們的方法名稱將如下所示

List<Person> findByAddress_ZipCode(ZipCode zipCode);

由於我們將下劃線（_）視為保留字元，因此強烈建議遵循標準的 Java 命名約定（即，不在屬性名稱中使用下劃線，而是應用駝峰大小寫）。
以下劃線開頭的欄位名

欄位名可以以下劃線開頭，例如 String _name。請確保保留 _，如 _name 中所示，並使用雙下劃線 __ 來分隔巢狀路徑，例如 user__name。

全大寫欄位名

全部大寫的欄位名可以直接使用。如果適用，巢狀路徑需要透過 _ 進行分割，例如 USER_name。

第二個字母為大寫的欄位名

由一個起始小寫字母后跟一個大寫字母組成的欄位名，例如 String qCode，可以透過使用兩個大寫字母開頭來解析，例如 QCode。請注意潛在的路徑歧義。

路徑歧義

在以下示例中，屬性 qCode 和 q 的排列方式（q 包含一個名為 code 的屬性）為路徑 QCode 建立了歧義。

record Container(String qCode, Code q) {}
record Code(String code) {}

由於首先考慮對屬性的直接匹配，任何潛在的巢狀路徑都不會被考慮，演算法會選擇 qCode 欄位。為了選擇 q 中的 code 欄位，需要使用下劃線表示法 Q_Code。

返回集合或可迭代物件的 Repository 方法

返回多個結果的查詢方法可以使用標準的 Java Iterable, List 和 Set。除此之外，我們還支援返回 Spring Data 的 Streamable（Iterable 的一個自定義擴充套件）以及 Vavr 提供的集合型別。請參閱附錄，其中解釋了所有可能的查詢方法返回型別。

使用 Streamable 作為查詢方法返回型別

您可以使用 Streamable 作為 Iterable 或任何集合型別的替代方案。它提供了訪問非並行 Stream（Iterable 中缺失）的便利方法，以及直接對元素進行 ….filter(…) 和 ….map(…) 操作以及將 Streamable 連線到其他 Streamable 的能力

使用 Streamable 組合查詢方法結果
interface PersonRepository extends Repository<Person, Long> {
  Streamable<Person> findByFirstnameContaining(String firstname);
  Streamable<Person> findByLastnameContaining(String lastname);
}

Streamable<Person> result = repository.findByFirstnameContaining("av")
  .and(repository.findByLastnameContaining("ea"));

返回自定義 Streamable 包裝型別

為集合提供專用的包裝型別是一種常用的模式，用於為返回多個元素的查詢結果提供 API。通常，這些型別透過呼叫返回集合型別（collection-like type）的 Repository 方法並手動建立包裝型別例項來使用。Spring Data 允許您將這些包裝型別用作查詢方法的返回型別，從而避免了額外的步驟，如果它們滿足以下條件

  1. 該型別實現了 Streamable。

  2. 該型別暴露一個建構函式或名為 of(…) 或 valueOf(…) 的靜態工廠方法，該方法接受 Streamable 作為引數。

以下列出了一個示例

class Product {                                         (1)
  MonetaryAmount getPrice() { … }
}

@RequiredArgsConstructor(staticName = "of")
class Products implements Streamable<Product> {         (2)

  private final Streamable<Product> streamable;

  public MonetaryAmount getTotal() {                    (3)
    return streamable.stream()
      .map(Product::getPrice)
      .reduce(Money.of(0), MonetaryAmount::add);
  }


  @Override
  public Iterator<Product> iterator() {                 (4)
    return streamable.iterator();
  }
}

interface ProductRepository implements Repository<Product, Long> {
  Products findAllByDescriptionContaining(String text); (5)
}
1 一個 Product 實體，暴露了訪問產品價格的 API。
2 Streamable<Product> 的包裝型別，可以透過使用 Products.of(…)（使用 Lombok 註解建立的工廠方法）構造。接受 Streamable<Product> 的標準建構函式也可以。
3 包裝型別暴露了額外的 API，用於計算 Streamable<Product> 上的新值。
4 實現 Streamable 介面並委託給實際結果。
5 該包裝型別 Products 可以直接用作查詢方法的返回型別。您不需要返回 Streamable<Product> 並在 Repository 客戶端查詢後手動進行包裝。

支援 Vavr 集合

Vavr 是一個擁抱 Java 函數語言程式設計概念的庫。它附帶了一組自定義的集合型別，您可以將其用作查詢方法的返回型別，如下表所示

Vavr 集合型別 使用的 Vavr 實現型別 有效的 Java 源型別

io.vavr.collection.Seq

io.vavr.collection.List

java.util.Iterable

io.vavr.collection.Set

io.vavr.collection.LinkedHashSet

java.util.Iterable

io.vavr.collection.Map

io.vavr.collection.LinkedHashMap

java.util.Map

您可以使用第一列中的型別（或其子型別）作為查詢方法的返回型別，並根據實際查詢結果的 Java 型別（第三列）獲得第二列中用作實現型別的型別。或者，您可以宣告 Traversable（相當於 Vavr 的 Iterable），然後我們根據實際返回值派生實現類。也就是說，一個 java.util.List 會轉換為 Vavr 的 List 或 Seq，一個 java.util.Set 會變成 Vavr 的 LinkedHashSet Set，依此類推。

流式處理查詢結果

您可以使用 Java 8 Stream<T> 作為返回型別，透過增量方式處理查詢方法的結果。與將查詢結果包裝到 Stream 中不同，這裡使用特定於資料儲存的方法來執行流式處理，如下例所示

使用 Java 8 Stream<T> 流式處理查詢結果
@Query("select u from User u")
Stream<User> findAllByCustomQueryAndStream();

Stream<User> readAllByFirstnameNotNull();

@Query("select u from User u")
Stream<User> streamAllPaged(Pageable pageable);
Stream 可能會包裝底層特定於資料儲存的資源，因此在使用後必須關閉。您可以透過呼叫 close() 方法手動關閉 Stream，或者使用 Java 7 的 try-with-resources 塊來關閉，如下例所示
在 try-with-resources 塊中處理 Stream<T> 結果
try (Stream<User> stream = repository.findAllByCustomQueryAndStream()) {
  stream.forEach(…);
}
目前並非所有 Spring Data 模組都支援將 Stream<T> 作為返回型別。

非同步查詢結果

您可以使用Spring 的非同步方法執行能力來非同步執行 Repository 查詢。這意味著方法呼叫後會立即返回，而實際的查詢發生在提交給 Spring TaskExecutor 的任務中。非同步查詢不同於響應式查詢，不應混用。有關響應式支援的更多詳細資訊，請參閱特定儲存的文件。以下示例顯示了多個非同步查詢

@Async
Future<User> findByFirstname(String firstname);               (1)

@Async
CompletableFuture<User> findOneByFirstname(String firstname); (2)
1 使用 java.util.concurrent.Future 作為返回型別。
2 使用 Java 8 的 java.util.concurrent.CompletableFuture 作為返回型別。

分頁、處理大型結果、排序與限制

為了處理查詢中的引數，請定義方法引數，如前面的示例所示。除此之外，基礎設施還能識別一些特定型別，如 Pageable、Sort 和 Limit，以便動態地對查詢應用分頁、排序和限制。以下示例演示了這些功能

在查詢方法中使用 Pageable, Slice, Sort 和 Limit
Page<User> findByLastname(String lastname, Pageable pageable);

Slice<User> findByLastname(String lastname, Pageable pageable);

List<User> findByLastname(String lastname, Sort sort);

List<User> findByLastname(String lastname, Sort sort, Limit limit);

List<User> findByLastname(String lastname, Pageable pageable);
接受 Sort, Pageable 和 Limit 的 API 期望將非 null 值傳入方法。如果您不想應用任何排序或分頁，請使用 Sort.unsorted(), Pageable.unpaged() 和 Limit.unlimited()。

第一個方法允許您將 org.springframework.data.domain.Pageable 例項傳遞給查詢方法，以便動態地為您的靜態定義查詢新增分頁。Page 知道元素的總數和可用的總頁數。這是透過基礎設施觸發一個計數查詢來計算總數實現的。由於這可能代價高昂（取決於使用的儲存），您可以轉而返回 Slice。Slice 只知道是否有下一個 Slice 可用，這在遍歷大型結果集時可能就足夠了。

排序選項也透過 Pageable 例項處理。如果您只需要排序，請向方法中新增 org.springframework.data.domain.Sort 引數。如您所見，返回 List 也是可能的。在這種情況下，構建實際 Page 例項所需的額外元資料不會被建立（這意味著本來需要的額外計數查詢也不會發出）。而是將查詢限制為僅查詢給定範圍的實體。

要了解整個查詢能獲得多少頁，您必須觸發一個額外的計數查詢。預設情況下，此查詢是從您實際觸發的查詢派生出來的。

特殊引數在查詢方法中只能使用一次。
上面描述的一些特殊引數是互斥的。請考慮以下無效引數組合列表。

引數 示例 原因

Pageable 和 Sort

findBy…​(Pageable page, Sort sort)

Pageable 已經定義了 Sort

Pageable 和 Limit

findBy…​(Pageable page, Limit limit)

Pageable 已經定義了一個限制。

用於限制結果的 Top 關鍵詞可以與 Pageable 一起使用，其中 Top 定義了結果的總最大值，而 Pageable 引數可能會減少此數值。

哪種方法合適？

Spring Data 抽象提供的價值或許最能體現在下表中列出的可能的查詢方法返回型別。下表顯示了您可以從查詢方法返回哪些型別

表 1. 消費大型查詢結果
方法 獲取的資料量 查詢結構 限制

List<T>

所有結果。

單個查詢。

查詢結果可能會耗盡所有記憶體。獲取所有資料可能非常耗時。

Streamable<T>

所有結果。

單個查詢。

查詢結果可能會耗盡所有記憶體。獲取所有資料可能非常耗時。

Stream<T>

分塊（逐個或按批次），取決於 Stream 的消費方式。

通常使用遊標的單個查詢。

使用後必須關閉 Stream 以避免資源洩漏。

Flux<T>

分塊（逐個或按批次），取決於 Flux 的消費方式。

通常使用遊標的單個查詢。

儲存模組必須提供響應式基礎設施。

Slice<T>

在 Pageable.getOffset() 位置獲取 Pageable.getPageSize() + 1 個元素

一個或多個查詢，從 Pageable.getOffset() 位置開始獲取資料並應用限制。

Slice 只能導航到下一個 Slice。

  • Slice 提供是否有更多資料可供獲取的詳細資訊。

  • 當 offset 過大時，基於 offset 的查詢效率會降低，因為資料庫仍然必須具體化（materialize）完整的結果。

  • Window 提供是否有更多資料可供獲取的詳細資訊。

  • 當 offset 過大時，基於 offset 的查詢效率會降低，因為資料庫仍然必須具體化（materialize）完整的結果。

Page<T>

在 Pageable.getOffset() 位置獲取 Pageable.getPageSize() 個元素

一個或多個查詢，從 Pageable.getOffset() 位置開始並應用限制。此外，可能需要 COUNT(…) 查詢來確定元素的總數。

通常需要 COUNT(…) 查詢，而這些查詢代價高昂。

  • 當 offset 過大時，基於 offset 的查詢效率會降低，因為資料庫仍然必須具體化（materialize）完整的結果。

分頁與排序

您可以使用屬性名定義簡單的排序表示式。您可以連線表示式，將多個條件組合成一個表示式。

定義排序表示式
Sort sort = Sort.by("firstname").ascending()
  .and(Sort.by("lastname").descending());

為了以更型別安全的方式定義排序表示式，請從要定義排序表示式的型別開始，並使用方法引用來定義要排序的屬性。

使用型別安全 API 定義排序表示式
TypedSort<Person> person = Sort.sort(Person.class);

Sort sort = person.by(Person::getFirstname).ascending()
  .and(person.by(Person::getLastname).descending());
TypedSort.by(…) 透過（通常）使用 CGlib 利用執行時代理，這在使用 Graal VM Native 等工具進行原生映象編譯時可能會產生干擾。

如果您的儲存實現支援 Querydsl，您也可以使用生成的元模型型別來定義排序表示式

使用 Querydsl API 定義排序表示式
QSort sort = QSort.by(QPerson.firstname.asc())
  .and(QSort.by(QPerson.lastname.desc()));

限制查詢結果

除了分頁之外，還可以使用專用的 Limit 引數來限制結果大小。您還可以使用 First 或 Top 關鍵詞來限制查詢方法的結果，這兩個關鍵詞可以互換使用，但不能與 Limit 引數混用。您可以在 Top 或 First 後附加一個可選的數值，以指定要返回的最大結果大小。如果省略該數值，則假定結果大小為 1。以下示例展示瞭如何限制查詢大小

使用 Top 和 First 限制查詢結果大小
List<User> findByLastname(String lastname, Limit limit);

User findFirstByOrderByLastnameAsc();

User findTopByLastnameOrderByAgeDesc(String lastname);

Page<User> queryFirst10ByLastname(String lastname, Pageable pageable);

Slice<User> findTop3By(Pageable pageable);

List<User> findFirst10ByLastname(String lastname, Sort sort);

List<User> findTop10ByLastname(String lastname, Pageable pageable);

限制表示式還支援 Distinct 關鍵詞，適用於支援 Distinct 查詢的資料儲存。此外，對於將結果集限制為一個例項的查詢，支援使用 Optional 關鍵詞將結果包裝起來。

如果分頁或分塊（slicing）應用於限制性查詢的分頁（以及可用頁數的計算），則該分頁會應用在限制的結果範圍內。

將結果限制與使用 Sort 引數進行動態排序結合，可以表達用於查詢“K”個最小元素和“K”個最大元素的查詢方法。