示例查詢

引言

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

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

本章解釋了示例查詢的核心概念。這些資訊提取自 Spring Data Commons 模組。根據你的資料庫，字串匹配支援可能會受到限制。

用法

Query by Example API 包含四個部分

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

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

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

示例查詢也有一些限制

不支援巢狀或分組的屬性約束，例如 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 條件中是基於 nullability 的。原始型別的屬性（int, double 等）總是包含在內，除非 ExampleMatcher 忽略了該屬性路徑。

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 執行示例查詢。為此，讓你的 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 Matchers

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 期望探針上設定的所有值都匹配。如果你想獲取與隱式定義的任何謂詞匹配的結果，請使用 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 級別設定，而 individual settings 可以應用於特定的屬性路徑。在 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()
);