定義查詢方法

倉庫代理有兩種方法從方法名稱中派生出特定於儲存的查詢

直接從方法名稱派生查詢。
使用手動定義的查詢。

可用的選項取決於實際的儲存。但是，必須有一個策略來決定建立什麼樣的實際查詢。下一節將介紹可用的選項。

查詢查詢策略

倉庫基礎架構可以使用以下策略來解析查詢。對於 XML 配置，您可以透過名稱空間中的 query-lookup-strategy 屬性配置策略。對於 Java 配置，您可以使用 EnableRedisRepositories 註解的 queryLookupStrategy 屬性。某些策略可能不支援特定的資料儲存。

CREATE 嘗試從查詢方法名稱構造特定於儲存的查詢。一般方法是從方法名稱中移除一組已知的特定字首，然後解析方法的其餘部分。您可以在“查詢建立”中閱讀更多關於查詢構造的資訊。
USE_DECLARED_QUERY 嘗試查詢一個已宣告的查詢，如果找不到則丟擲異常。查詢可以透過註解或其他方式在某處定義或宣告。請查閱特定儲存的文件以瞭解該儲存可用的選項。如果在引導時倉庫基礎架構找不到該方法的已宣告查詢，則會失敗。
CREATE_IF_NOT_FOUND (預設) 結合了 CREATE 和 USE_DECLARED_QUERY。它首先查詢一個已宣告的查詢，如果找不到已宣告的查詢，則建立一個基於方法名稱的自定義查詢。這是預設的查詢策略，因此，如果您未顯式配置任何內容，將使用此策略。它允許透過方法名稱快速定義查詢，但也允許透過根據需要引入已宣告的查詢來自定義調整這些查詢。

查詢建立

Spring Data 倉庫基礎架構內建的查詢構建機制對於構建針對倉庫實體進行約束的查詢非常有用。

下面的例子展示瞭如何建立一些查詢

從方法名稱建立查詢

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) 來應用靜態排序。要建立支援動態排序的查詢方法，請參見“分頁、迭代大型結果、排序和限制”。

保留方法名稱

雖然派生的倉庫方法按名稱繫結到屬性，但在涉及到從基礎倉庫繼承的某些方法名稱時，這些方法名稱以識別符號屬性為目標，而有一些例外。這些保留方法，如 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	以 `pk` 屬性 (標記有 `@Id` 並被視為識別符號的屬性) 為目標，因為它引用了一個 `CrudRepository` 基礎倉庫方法。因此，它不是一個使用 `id` 作為屬性名稱所暗示的派生查詢，因為它是保留方法之一。
4	透過名稱以 `pk` 屬性為目標，因為它是一個派生查詢。
5	透過使用 `find` 和 `by` 之間的描述性標記來避免與保留方法衝突，從而以 `id` 屬性為目標。

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

屬性表示式

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

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。

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

返回多個結果的查詢方法可以使用標準的 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 的常用模式。通常，這些型別是透過呼叫返回集合型別資料的倉庫方法，然後手動建立包裝器型別的例項來使用的。您可以避免額外的步驟，因為 Spring Data 允許您將這些包裝器型別用作查詢方法的返回型別，只要它們滿足以下條件

該型別實現了 Streamable 介面。
該型別暴露了一個建構函式或一個名為 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>` 並在倉庫客戶端中查詢後手動包裝它。

支援 Vavr 集合

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

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`

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 的非同步方法執行能力來非同步執行倉庫查詢。這意味著方法在呼叫後立即返回，而實際查詢則在提交給 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` 提供了是否有更多資料可獲取的詳細資訊。基於偏移量的查詢在偏移量太大時會變得低效，因為資料庫仍然必須物化完整的結果。 `Window` 提供了是否有更多資料可獲取的詳細資訊。基於偏移量的查詢在偏移量太大時會變得低效，因為資料庫仍然必須物化完整的結果。
`Page<T>`	在 `Pageable.getOffset()` 處獲取 `Pageable.getPageSize()` 條資料	一個或多個查詢，從 `Pageable.getOffset()` 開始應用限制。此外，可能需要 `COUNT(…)` 查詢來確定元素總數。	通常需要執行昂貴的 `COUNT(…)` 查詢。基於偏移量的查詢在偏移量太大時會變得低效，因為資料庫仍然必須物化完整的結果。

分頁和排序

您可以使用屬性名稱定義簡單的排序表示式。您可以連線表示式將多個條件收集到一個表示式中。

定義排序表示式

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 關鍵字包裝結果。

如果將分頁或分片應用於限制查詢的分頁 (以及可用頁數的計算)，則會在限制結果範圍內應用。

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