定義查詢方法

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

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

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

查詢查詢策略

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

CREATE 嘗試從查詢方法名構造特定於儲存的查詢。通常的方法是從方法名中移除一組已知的特定字首，然後解析方法的其餘部分。您可以在“查詢建立”中瞭解更多關於查詢構造的資訊。
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 等運算子。支援的運算子因資料儲存而異，請查閱您的參考文件的相應部分。
方法解析器支援為單個屬性（例如，findByLastnameIgnoreCase(…)）或支援忽略大小寫的所有屬性型別（通常是 String 例項——例如，findByLastnameAndFirstnameAllIgnoreCase(…)）設定 IgnoreCase 標誌。是否支援忽略大小寫可能因儲存而異，請查閱特定儲存的參考文件中的相關部分。
您可以透過向引用屬性的查詢方法附加 OrderBy 子句並提供排序方向（Asc 或 Desc）來應用靜態排序。要建立支援動態排序的查詢方法，請參閱“分頁、迭代大型結果集、排序與限制”。

保留方法名

雖然派生的 repository 方法透過名稱繫結到屬性，但在涉及繼承自目標為識別符號屬性的基礎 repository 的某些方法名時，此規則有一些例外。那些保留方法，如 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` 的基礎 repository 方法。因此，它不是一個派生查詢，不像屬性名 `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。通常，這些型別透過呼叫返回類似集合型別的 repository 方法並手動建立包裝型別的例項來使用。您可以避免這個額外的步驟，因為如果這些包裝型別滿足以下條件，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>` 並在 repository 客戶端中查詢後手動包裝它。

支援 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 的非同步方法執行能力來非同步執行 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 and Sort

findBy…(Pageable page, Sort sort)

Pageable 已定義 Sort

Pageable and Limit

findBy…(Pageable page, Limit limit)

Pageable 已定義限制。

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

哪種方法適合？

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

表 1. 處理大型查詢結果
方法	獲取的資料量	查詢結構	限制
`List<T>`	所有結果。	單次查詢。	查詢結果可能會耗盡所有記憶體。獲取所有資料可能非常耗時。
`Streamable<T>`	所有結果。	單次查詢。	查詢結果可能會耗盡所有記憶體。獲取所有資料可能非常耗時。
`Stream<T>`	分塊（按需一次一個或分批），取決於 `Stream` 的消費方式。	通常使用遊標的單次查詢。	使用後必須關閉 Streams 以避免資源洩漏。
`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”個最大元素的查詢方法。