範例查詢

簡介

本章介紹 Query by Example 並解釋如何使用它。

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

本章解釋了 Query by Example 的核心概念。這些資訊來自 Spring Data Commons 模組。根據您的資料庫，字串匹配支援可能有限。

用法

Query by Example API 由四部分組成

Probe: 填充了欄位的領域物件的實際示例。
ExampleMatcher: ExampleMatcher 帶有關於如何匹配特定欄位的詳細資訊。它可以在多個 Example 中重用。
Example: 一個 Example 由 probe 和 ExampleMatcher 組成。它用於建立查詢。
FetchableFluentQuery: FetchableFluentQuery 提供了一個流式 API，允許進一步自定義從 Example 派生的查詢。使用流式 API 可以指定查詢的排序、投影和結果處理。

Query by Example 非常適合以下幾個用例

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

Query by Example 也有一些限制

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

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

Person 物件示例

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 條件中取決於其可空性。除非 ExampleMatcher 忽略該屬性路徑，否則原始型別（int, double, …）的屬性總是被包含。

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

例 1. 簡單 Example

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

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

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

您可以使用 repositories 執行 example 查詢。為此，讓您的 repository 介面繼承 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.
}

Example Matcher

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

例 2. 使用自定義匹配的 Example matcher

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"）指定行為。您可以使用匹配選項和大小寫敏感性對其進行調整，如下例所示

配置 matcher 選項

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

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

使用 lambdas 配置 matcher 選項

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

這裡有一個示例

Employee employee = new Employee(); (1)
employee.name= "Frodo";

Example<Employee> example = Example.of(employee); (2)

repository.findAll(example); (3)

// do whatever with the result

1	建立帶有條件的領域物件（`null` 欄位將被忽略）。
2	使用領域物件建立 `Example`。
3	透過 repository 執行查詢（對於單個專案使用 `findOne`）。

這說明了如何使用領域物件構建一個簡單的 probe。在本例中，它將基於 Employee 物件的 name 欄位等於 Frodo 來查詢。null 欄位將被忽略。

Employee employee = new Employee();
employee.name = "Baggins";
employee.role = "ring bearer";

ExampleMatcher matcher = matching() (1)
		.withMatcher("name", endsWith()) (2)
		.withIncludeNullValues() (3)
		.withIgnorePaths("role"); (4)
Example<Employee> example = Example.of(employee, matcher); (5)

repository.findAll(example);

// do whatever with the result

1	建立一個自定義的 `ExampleMatcher`，它匹配所有欄位（使用 `matchingAny()` 匹配任意欄位）。
2	對於 `name` 欄位，使用一個萬用字元匹配欄位的末尾。
3	匹配列是否為 `null`（別忘了在關係型資料庫中 `NULL` 不等於 `NULL`）。
4	在形成查詢時忽略 `role` 欄位。
5	將自定義的 `ExampleMatcher` 插入到 probe 中。

還可以對任何屬性應用 withTransform()，允許您在形成查詢之前轉換屬性。例如，您可以在建立查詢之前對基於 String 的屬性應用 toUpperCase()。

當您不知道查詢中需要的所有欄位時，Query By Example 真正發揮作用。如果您正在構建一個網頁上的過濾器，使用者可以選擇欄位，那麼 Query By Example 是將這些靈活地捕獲到高效查詢中的絕佳方法。