按示例查詢

簡介

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

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

本章解釋了按示例查詢的核心概念。資訊來自 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。
其他屬性型別的精確匹配。

在開始使用按示例查詢之前，您需要有一個域物件。首先，為您的 Repository 建立一個介面，如以下示例所示

示例 Person 物件

public class Person {

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

  // … getters and setters omitted
}

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

將屬性包含到按示例查詢條件中是基於是否為空的。使用原始型別（int、double 等）的屬性總是包含在內，除非 ExampleMatcher 忽略了屬性路徑。

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

示例 1. 簡單示例

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

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

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

您可以使用 Repository 來執行示例查詢。為此，讓您的 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 不僅限於預設設定。您可以使用 ExampleMatcher 指定您自己的字串匹配、空值處理和特定屬性設定的預設值，如以下示例所示

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

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

配置匹配器選項

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

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

使用 Lambda 表示式配置匹配器選項

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 獲取可能存在多個結果中的最後一個結果，並按姓氏排序。

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