範例查詢

簡介

本章節介紹範例查詢，並說明如何使用它。

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

本章節說明範例查詢的核心概念。這些資訊來自 Spring Data Commons 模組。根據您的資料庫，字串比對支援可能會受到限制。

用法

範例查詢 API 包含四個部分

探針 (Probe)：具有已填入欄位的網域物件的實際範例。
ExampleMatcher: ExampleMatcher 攜帶有關如何比對特定欄位的詳細資訊。它可以跨多個範例重複使用。
Example: Example 包含探針和 ExampleMatcher。它用於建立查詢。
FetchableFluentQuery: FetchableFluentQuery 提供流暢的 API，允許進一步自訂從 Example 衍生的查詢。使用流暢的 API 可讓您為查詢指定排序投影和結果處理。

範例查詢非常適合以下幾種使用案例

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

範例查詢也有一些限制

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

在開始使用範例查詢之前，您需要有一個網域物件。若要開始使用，請為您的儲存庫建立介面，如下列範例所示

範例 Person 物件

public class Person {

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

  // … getters and setters omitted
}

前面的範例顯示一個簡單的網域物件。您可以使用它來建立 Example。預設情況下，具有 null 值的欄位會被忽略，並且字串會使用儲存庫特定的預設值進行比對。

將屬性包含到範例查詢條件中是基於可空性。除非 ExampleMatcher 忽略屬性路徑，否則使用原始型別（int、double、…）的屬性始終包含在內。

範例可以使用 of 工廠方法或使用 ExampleMatcher 來建構。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.
}

Example Matchers

範例不限於預設設定。您可以使用 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 預期探針上設定的所有值都符合。如果您想要取得符合隱式定義的任何述詞的結果，請使用 ExampleMatcher.matchingAny()。

您可以指定個別屬性（例如 "firstname" 和 "lastname"，或針對巢狀屬性 "address.city"）的行為。您可以使用比對選項和區分大小寫來調整它，如下列範例所示

配置 matcher 選項

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

配置 matcher 選項的另一種方法是使用 lambda（在 Java 8 中引入）。此方法建立一個回呼，要求實作人員修改 matcher。您不需要傳回 matcher，因為組態選項保留在 matcher 實例中。以下範例顯示使用 lambda 的 matcher

使用 lambda 配置 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` 和屬性路徑
值轉換	屬性路徑

Fluent 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 定義了您獲得的結果類型，以及當可用結果數量超出預期時查詢的行為方式。

使用 Fluent API 取得最後一個可能有很多結果的結果，並依姓氏排序。

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	透過儲存庫，執行查詢（針對單個項目使用 `findOne`）。

這說明了如何使用網域物件製作簡單的探針。在此範例中，它將根據 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` 插入探針。

也可以對任何屬性套用 withTransform()，讓您在形成查詢之前轉換屬性。例如，您可以在建立查詢之前將 toUpperCase() 套用至基於 String 的屬性。

當您事先不知道查詢中需要的所有欄位時，範例查詢確實會發光發熱。如果您正在網頁上建置篩選器，使用者可以在其中選擇欄位，則範例查詢是一種將其靈活地擷取到有效查詢中的絕佳方法。