範例查詢

簡介

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

範例查詢 (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。

  • 其他屬性類型的精確比對。

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

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。

您可以使用 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.
}

範例比對器

範例不限於預設設定。您可以使用 ExampleMatcher 指定您自己的字串比對、Null 處理和屬性特定設定的預設值，如下列範例所示

範例 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 屬性路徑並包含 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 取得可能多個結果中的最後一個，並依 lastname 排序。
Optional<Person> match = repository.findBy(example,
    q -> q
        .sortBy(Sort.by("lastname").descending())
        .first()
);

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

範例 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 不支援 Regex 比對。