查詢示例

簡介

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

查詢示例（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。

  • 其他屬性型別的精確匹配。

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

示例 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

示例 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.
}

示例匹配器

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

示例 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 屬性路徑幷包含空值。
6 構造一個新的 ExampleMatcher 以忽略 lastname 屬性路徑、包含空值並執行字尾字串匹配。
7 基於領域物件和配置的 ExampleMatcher 建立一個新的 Example。

預設情況下，ExampleMatcher 期望 probe 上設定的所有值都匹配。如果您希望獲得匹配隱式定義的任何謂詞的結果，請使用 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 設定的範圍
設定 作用域

空值處理

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、slice、stream、count 和 exists 定義了您獲得的結果型別以及當結果數量超出預期時查詢的行為。

使用流式 API 獲取可能存在多個結果中的最後一個，按姓氏排序。
Optional<Person> match = repository.findBy(example,
    q -> q
        .sortBy(Sort.by("lastname").descending())
        .first()
);

在 Spring Data JPA 中，您可以將查詢示例與 Repositories 一起使用，如下例所示

示例 3. 使用 Repository 的查詢示例
public interface PersonRepository extends JpaRepository<Person, String> { … }

public class PersonService {

  @Autowired PersonRepository personRepository;

  public List<Person> findPeople(Person probe) {
    return personRepository.findAll(Example.of(probe));
  }
}
目前，只有 SingularAttribute 屬性可用於屬性匹配。

屬性說明符接受屬性名稱（如 firstname 和 lastname）。您可以透過用點連線屬性來導航（address.city）。您還可以透過匹配選項和大小寫敏感性來調整它。

下表顯示了您可以使用的各種 StringMatcher 選項以及將它們用於名為 firstname 的欄位的結果

表 2. StringMatcher 選項
匹配 邏輯結果

DEFAULT (區分大小寫)

firstname = ?0

DEFAULT (不區分大小寫)

LOWER(firstname) = LOWER(?0)

EXACT (區分大小寫)

firstname = ?0

EXACT (不區分大小寫)

LOWER(firstname) = LOWER(?0)

STARTING (區分大小寫)

firstname like ?0 + '%'

STARTING (不區分大小寫)

LOWER(firstname) like LOWER(?0) + '%'

ENDING (區分大小寫)

firstname like '%' + ?0

ENDING (不區分大小寫)

LOWER(firstname) like '%' + LOWER(?0)

CONTAINING (區分大小寫)

firstname like '%' + ?0 + '%'

CONTAINING (不區分大小寫)

LOWER(firstname) like '%' + LOWER(?0) + '%'
JPA 不支援正則表示式匹配。
© . This site is unofficial and not affiliated with VMware.