示例查詢

引言

本章介紹了示例查詢（Query by Example）並解釋瞭如何使用它。

示例查詢（Query by Example，QBE）是一種使用者友好的查詢技術，具有簡單的介面。它允許動態建立查詢，並且不需要您編寫包含欄位名稱的查詢。實際上，示例查詢根本不需要您使用特定於儲存的查詢語言來編寫查詢。

本章解釋了示例查詢（Query by Example）的核心概念。這些資訊來源於 Spring Data Commons 模組。取決於您的資料庫，字串匹配的支援可能會受到限制。

用法

示例查詢 API 由四部分組成

Probe（探測物件）：一個填充了欄位值的實際領域物件示例。
ExampleMatcher（示例匹配器）：ExampleMatcher 包含如何匹配特定欄位的詳細資訊。它可以在多個 Example 中重用。
Example（示例）：一個 Example 由 probe 和 ExampleMatcher 組成。它用於建立查詢。
FetchableFluentQuery（可獲取的流式查詢）：FetchableFluentQuery 提供了一個流式 API，允許進一步定製從 Example 派生的查詢。使用流式 API，您可以為查詢指定排序、投影和結果處理。

示例查詢非常適合以下幾種用例

使用一組靜態或動態約束查詢您的資料儲存。
頻繁重構領域物件，而無需擔心破壞現有查詢。
獨立於底層資料儲存 API 工作。

示例查詢也有一些限制

不支援巢狀或分組的屬性約束，例如 firstname = ?0 or (firstname = ?1 and lastname = ?2)。
特定於儲存的字串匹配支援。取決於您的資料庫，字串匹配可以支援字串的 starts/contains/ends/regex。
對其他屬性型別進行精確匹配。

在開始使用示例查詢（Query by Example）之前，您需要有一個領域物件。要開始，請為您的倉庫（repository）建立一個介面，如下面的示例所示

人員物件示例

public class Person {

  @Id
  private String id;
  private String firstname;
  private String lastname;
  private Address address;

  // … getters and setters omitted
}

前面的示例展示了一個簡單的領域物件。您可以使用它建立一個 Example。預設情況下，null 值的欄位會被忽略，字串使用特定於儲存的預設設定進行匹配。

屬性是否包含到示例查詢（Query by Example）條件中取決於其是否為 null。使用原始型別（int、double 等）的屬性總是被包含，除非 ExampleMatcher 忽略了該屬性路徑。

Examples 可以透過 of 工廠方法或使用 ExampleMatcher 來構建。Example 是不可變的。以下清單展示了一個簡單的 Example

示例 1. 簡單示例

Person person = new Person();                         (1)
person.setFirstname("Dave");                          (2)

Example<Person> example = Example.of(person);         (3)

1	建立一個新的領域物件例項。
2	設定要查詢的屬性。
3	建立 Example。

您可以使用倉庫來執行示例查詢。為此，讓您的倉庫介面繼承 QueryByExampleExecutor<T>。以下清單展示了 QueryByExampleExecutor 介面的摘錄

QueryByExampleExecutor

public interface QueryByExampleExecutor<T> {

  <S extends T> S findOne(Example<S> example);

  <S extends T> Iterable<S> findAll(Example<S> example);

  // … more functionality omitted.
}

示例匹配器

Examples 不限於預設設定。您可以使用 ExampleMatcher 指定自己的字串匹配、null 處理和屬性特定設定的預設值，如下面的示例所示

示例 2. 自定義匹配的示例匹配器

Person person = new Person();                          (1)
person.setFirstname("Dave");                           (2)

ExampleMatcher matcher = ExampleMatcher.matching()     (3)
  .withIgnorePaths("lastname")                         (4)
  .withIncludeNullValues()                             (5)
  .withStringMatcher(StringMatcher.ENDING);            (6)

Example<Person> example = Example.of(person, matcher); (7)

1	建立一個新的領域物件例項。
2	設定屬性。
3	建立一個 ExampleMatcher，期望所有值都匹配。即使沒有進一步配置，它在此階段也是可用的。
4	構造一個新的 ExampleMatcher 以忽略 `lastname` 屬性路徑。
5	構造一個新的 ExampleMatcher 以忽略 `lastname` 屬性路徑幷包含 `null` 值。
6	構造一個新的 ExampleMatcher 以忽略 `lastname` 屬性路徑，包含 `null` 值，並執行字尾字串匹配。
7	基於領域物件和配置的 ExampleMatcher 建立一個新的 Example。

預設情況下，ExampleMatcher 期望 probe 上設定的所有值都匹配。如果您希望獲取與隱式定義的任何謂詞匹配的結果，請使用 ExampleMatcher.matchingAny()。

您可以為單個屬性指定行為（例如 `"firstname"` 和 `"lastname"`，或巢狀屬性如 `"address.city"`）。您可以使用匹配選項和大小寫敏感性來調整它，如下面的示例所示

配置匹配器選項

ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", endsWith())
  .withMatcher("lastname", startsWith().ignoreCase());
}

配置匹配器選項的另一種方法是使用 lambdas（在 Java 8 中引入）。這種方法建立了一個回撥，要求實現者修改匹配器。您不需要返回匹配器，因為配置選項儲存在匹配器例項中。以下示例展示了一個使用 lambdas 的匹配器

使用 lambdas 配置匹配器選項

ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", match -> match.endsWith())
  .withMatcher("firstname", match -> match.startsWith());
}

由 Example 建立的查詢使用配置的合併檢視。預設匹配設定可以在 ExampleMatcher 級別設定，而單個設定可以應用於特定的屬性路徑。在 ExampleMatcher 上設定的設定會被屬性路徑設定繼承，除非屬性路徑明確定義了設定。屬性路徑上的設定優先順序高於預設設定。下表描述了各種 ExampleMatcher 設定的作用範圍

表 1. ExampleMatcher 設定的作用範圍
設定	作用範圍
Null 處理	`ExampleMatcher`
字串匹配	ExampleMatcher 和屬性路徑
忽略屬性	屬性路徑
大小寫敏感性	ExampleMatcher 和屬性路徑
值轉換	屬性路徑

流式 API

QueryByExampleExecutor 還提供了一個我們尚未提及的方法：<S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction)。與其他方法一樣，它執行從 Example 派生的查詢。但是，透過第二個引數，您可以控制該執行中無法以其他方式動態控制的方面。您可以透過呼叫第二個引數中的 FetchableFluentQuery 的各種方法來實現。sortBy 允許您為結果指定排序。as 允許您指定結果要轉換的型別。project 限制查詢的屬性。first、firstValue、one、oneValue、all、page、stream、count 和 exists 定義了您獲得的結果型別以及當結果數量超出預期時查詢的行為方式。

使用流式 API 獲取潛在的多個結果中的最後一個，按 lastname 排序。

Optional<Person> match = repository.findBy(example,
    q -> q
        .sortBy(Sort.by("lastname").descending())
        .first()
);