Spring Data 擴充套件

本節介紹了一組 Spring Data 擴充套件，這些擴充套件使 Spring Data 能夠在各種上下文中使用。目前，大多數整合都針對 Spring MVC。

Querydsl 擴充套件

Querydsl 是一個框架，可以透過其流暢的 API 構建靜態型別的類 SQL 查詢。

Querydsl 的維護速度已減慢到社群在 OpenFeign 下分叉該專案的地步，網址為 github.com/OpenFeign/querydsl（groupId io.github.openfeign.querydsl）。 Spring Data 會盡最大努力支援該分支。

一些 Spring Data 模組透過 QuerydslPredicateExecutor 提供與 Querydsl 的整合，如以下示例所示

QuerydslPredicateExecutor 介面

public interface QuerydslPredicateExecutor<T> {

  Optional<T> findById(Predicate predicate);  (1)

  Iterable<T> findAll(Predicate predicate);   (2)

  long count(Predicate predicate);            (3)

  boolean exists(Predicate predicate);        (4)

  // … more functionality omitted.
}

1	查詢並返回與 `Predicate` 匹配的單個實體。
2	查詢並返回與 `Predicate` 匹配的所有實體。
3	返回與 `Predicate` 匹配的實體的數量。
4	返回是否存在與 `Predicate` 匹配的實體。

要使用 Querydsl 支援，請在 Repository 介面上擴充套件 QuerydslPredicateExecutor，如以下示例所示

Repository 上的 Querydsl 整合

interface UserRepository extends CrudRepository<User, Long>, QuerydslPredicateExecutor<User> {
}

前面的示例允許您使用 Querydsl Predicate 例項編寫型別安全的查詢，如以下示例所示

Predicate predicate = user.firstname.equalsIgnoreCase("dave")
	.and(user.lastname.startsWithIgnoreCase("mathews"));

userRepository.findAll(predicate);

Web 支援

支援 Repository 程式設計模型的 Spring Data 模組附帶各種 Web 支援。 Web 相關元件需要 Spring MVC JAR 位於類路徑中。其中一些甚至提供與 Spring HATEOAS 的整合。通常，整合支援透過在 JavaConfig 配置類中使用 @EnableSpringDataWebSupport 註釋來啟用，如以下示例所示

啟用 Spring Data Web 支援

Java
XML

@Configuration
@EnableWebMvc
@EnableSpringDataWebSupport
class WebConfiguration {}

<bean class="org.springframework.data.web.config.SpringDataWebConfiguration" />

<!-- If you use Spring HATEOAS, register this one *instead* of the former -->
<bean class="org.springframework.data.web.config.HateoasAwareSpringDataWebConfiguration" />

@EnableSpringDataWebSupport 註釋註冊了一些元件。我們將在本節後面討論這些元件。它還會檢測類路徑上的 Spring HATEOAS，並註冊整合元件（如果存在）也適用於它。

基本 Web 支援

在 XML 中啟用 Spring Data Web 支援

上一節中顯示的配置註冊了一些基本元件

使用 DomainClassConverter 類，以便 Spring MVC 可以從請求引數或路徑變數解析 Repository 管理的域類的例項。
HandlerMethodArgumentResolver 實現，以便 Spring MVC 可以從請求引數解析 Pageable 和 Sort 例項。
Jackson Modules 用於序列化/反序列化諸如 Point 和 Distance 之類的型別，或儲存特定型別，具體取決於所使用的 Spring Data 模組。

使用 `DomainClassConverter` 類

DomainClassConverter 類允許您直接在 Spring MVC 控制器方法簽名中使用域型別，這樣您就不需要手動透過 Repository 查詢例項，如以下示例所示

在方法簽名中使用域型別的 Spring MVC 控制器

@Controller
@RequestMapping("/users")
class UserController {

  @RequestMapping("/{id}")
  String showUserForm(@PathVariable("id") User user, Model model) {

    model.addAttribute("user", user);
    return "userForm";
  }
}

該方法直接接收 User 例項，無需進一步查詢。可以透過讓 Spring MVC 首先將路徑變數轉換為域類的 id 型別，然後最終透過在為域型別註冊的 Repository 例項上呼叫 findById(…) 來訪問該例項，從而解析該例項。

目前，Repository 必須實現 CrudRepository 才能有資格被發現以進行轉換。

Pageable 和 Sort 的 HandlerMethodArgumentResolvers

上一節中顯示的配置程式碼段還註冊了 PageableHandlerMethodArgumentResolver 以及 SortHandlerMethodArgumentResolver 的例項。該註冊使 Pageable 和 Sort 成為有效的控制器方法引數，如以下示例所示

將 Pageable 用作控制器方法引數

@Controller
@RequestMapping("/users")
class UserController {

  private final UserRepository repository;

  UserController(UserRepository repository) {
    this.repository = repository;
  }

  @RequestMapping
  String showUsers(Model model, Pageable pageable) {

    model.addAttribute("users", repository.findAll(pageable));
    return "users";
  }
}

前面的方法簽名導致 Spring MVC 嘗試使用以下預設配置從請求引數派生 Pageable 例項

表 1. 針對 `Pageable` 例項評估的請求引數
`page`	您要檢索的頁碼。從 0 開始，預設為 0。
`size`	您要檢索的頁面大小。預設為 20。
`sort`	應按 `property,property(,ASC\|DESC)(,IgnoreCase)` 格式排序的屬性。預設排序方向區分大小寫升序。如果要切換方向或大小寫敏感度，請使用多個 `sort` 引數，例如 `?sort=firstname&sort=lastname,asc&sort=city,ignorecase`。

要自定義此行為，請註冊一個實現 PageableHandlerMethodArgumentResolverCustomizer 介面或 SortHandlerMethodArgumentResolverCustomizer 介面的 bean。將呼叫其 customize() 方法，讓您更改設定，如以下示例所示

@Bean SortHandlerMethodArgumentResolverCustomizer sortCustomizer() {
    return s -> s.setPropertyDelimiter("<-->");
}

如果設定現有 MethodArgumentResolver 的屬性不足以滿足您的目的，請擴充套件 SpringDataWebConfiguration 或支援 HATEOAS 的等效配置，覆蓋 pageableResolver() 或 sortResolver() 方法，然後匯入您自定義的配置檔案，而不是使用 @Enable 註釋。

如果您需要從請求中解析多個 Pageable 或 Sort 例項（例如，用於多個表），您可以使用 Spring 的 @Qualifier 註解來區分它們。然後，請求引數必須以 ${qualifier}_ 為字首。以下示例顯示了生成的方法簽名：

String showUsers(Model model,
      @Qualifier("thing1") Pageable first,
      @Qualifier("thing2") Pageable second) { … }

您需要填充 thing1_page、thing2_page，等等。

傳遞到方法中的預設 Pageable 等效於 PageRequest.of(0, 20)，但您可以使用 Pageable 引數上的 @PageableDefault 註解對其進行自定義。

為 `Page` 建立 JSON 表示形式

Spring MVC 控制器通常會嘗試最終將 Spring Data 頁面的表示形式呈現給客戶端。雖然可以直接從處理程式方法返回 Page 例項，讓 Jackson 按原樣呈現它們，但我們強烈建議不要這樣做，因為底層實現類 PageImpl 是一個域型別。這意味著我們可能想要或必須出於不相關的原因更改其 API，並且此類更改可能會以破壞性的方式更改生成的 JSON 表示形式。

從 Spring Data 3.1 開始，我們透過發出描述問題的警告日誌來提示該問題。我們仍然最終建議利用與 Spring HATEOAS 的整合，以獲得完全穩定且啟用超媒體的方式來呈現頁面，從而方便客戶端瀏覽它們。但從 3.3 版開始，Spring Data 提供了一種方便使用的頁面呈現機制，但不需要包含 Spring HATEOAS。

使用 Spring Data 的 `PagedModel`

其核心在於，該支援包含 Spring HATEOAS 的 PagedModel 的簡化版本（Spring Data 的位於 org.springframework.data.web 包中）。它可用於包裝 Page 例項，並生成反映 Spring HATEOAS 建立的結構的簡化表示形式，但省略了導航連結。

import org.springframework.data.web.PagedModel;

@Controller
class MyController {

  private final MyRepository repository;

  // Constructor ommitted

  @GetMapping("/page")
  PagedModel<?> page(Pageable pageable) {
    return new PagedModel<>(repository.findAll(pageable)); (1)
  }
}

1	將 `Page` 例項包裝到 `PagedModel` 中。

這將生成如下所示的 JSON 結構：

{
  "content" : [
     … // Page content rendered here
  ],
  "page" : {
    "size" : 20,
    "totalElements" : 30,
    "totalPages" : 2,
    "number" : 0
  }
}

請注意，文件如何包含一個 page 欄位，該欄位公開了基本的頁面元資料。

全域性啟用簡化的 `Page` 呈現

如果您不想更改所有現有控制器來新增對映步驟以返回 PagedModel 而不是 Page，則可以透過調整 @EnableSpringDataWebSupport 如下來啟用將 PageImpl 例項自動轉換為 PagedModel：

@EnableSpringDataWebSupport(pageSerializationMode = VIA_DTO)
class MyConfiguration { }

這將允許您的控制器仍然返回 Page 例項，並且它們將自動呈現為簡化的表示形式

@Controller
class MyController {

  private final MyRepository repository;

  // Constructor ommitted

  @GetMapping("/page")
  Page<?> page(Pageable pageable) {
    return repository.findAll(pageable);
  }
}

對 `Page` 和 `Slice` 的超媒體支援

Spring HATEOAS 提供了一個表示模型類（PagedModel/SlicedModel），允許使用必要的 Page/Slice 元資料以及允許客戶端輕鬆導航頁面的連結來豐富 Page 或 Slice 例項的內容。將 Page 轉換為 PagedModel 由 Spring HATEOAS RepresentationModelAssembler 介面的一個實現來完成，該實現稱為 PagedResourcesAssembler。類似地，可以使用 SlicedResourcesAssembler 將 Slice 例項轉換為 SlicedModel。以下示例顯示瞭如何將 PagedResourcesAssembler 用作控制器方法引數，因為 SlicedResourcesAssembler 的工作方式完全相同：

將 PagedResourcesAssembler 用作控制器方法引數

@Controller
class PersonController {

  private final PersonRepository repository;

  // Constructor omitted

  @GetMapping("/people")
  HttpEntity<PagedModel<Person>> people(Pageable pageable,
    PagedResourcesAssembler assembler) {

    Page<Person> people = repository.findAll(pageable);
    return ResponseEntity.ok(assembler.toModel(people));
  }
}

如前面的示例所示，啟用配置允許將 PagedResourcesAssembler 用作控制器方法引數。在其上呼叫 toModel(…) 具有以下效果：

Page 的內容成為 PagedModel 例項的內容。
PagedModel 物件附加了一個 PageMetadata 例項，並使用來自 Page 和底層 Pageable 的資訊填充它。
PagedModel 可能會附加 prev 和 next 連結，具體取決於頁面的狀態。這些連結指向方法對映到的 URI。新增到該方法的頁面引數與 PageableHandlerMethodArgumentResolver 的設定相匹配，以確保以後可以解析這些連結。

假設我們在資料庫中有 30 個 Person 例項。您現在可以觸發一個請求 (GET localhost:8080/people) 並檢視類似於以下內容的輸出：

{ "links" : [
    { "rel" : "next", "href" : "https://:8080/persons?page=1&size=20" }
  ],
  "content" : [
     … // 20 Person instances rendered here
  ],
  "page" : {
    "size" : 20,
    "totalElements" : 30,
    "totalPages" : 2,
    "number" : 0
  }
}

此處顯示的 JSON 封包格式不遵循任何正式指定的結構，並且不能保證穩定，我們可能會隨時更改它。強烈建議啟用呈現為由 Spring HATEOAS 支援的啟用超媒體的官方媒體型別，例如 HAL。可以透過使用其 @EnableHypermediaSupport 註解來啟用它們。有關更多資訊，請參見 Spring HATEOAS 參考文件。

彙編器生成了正確的 URI，並且還選擇了預設配置以將引數解析為即將到來的請求的 Pageable。這意味著，如果您更改該配置，則連結會自動遵守該更改。預設情況下，彙編器指向呼叫它的控制器方法，但是您可以透過傳遞一個自定義 Link 作為構建頁面連結的基礎來自定義它，這會過載 PagedResourcesAssembler.toModel(…) 方法。

Spring Data Jackson 模組

核心模組以及某些特定於儲存的模組附帶了一組 Jackson 模組，用於 Spring Data 域使用的型別，例如 org.springframework.data.geo.Distance 和 org.springframework.data.geo.Point。
一旦啟用 Web 支援並且 com.fasterxml.jackson.databind.ObjectMapper 可用，這些模組就會被匯入。

在初始化期間，SpringDataJacksonModules（如 SpringDataJacksonConfiguration）會被基礎設施拾取，以便宣告的 com.fasterxml.jackson.databind.Module 可用於 Jackson ObjectMapper。

通用基礎設施註冊了以下域型別的資料繫結混合：

org.springframework.data.geo.Distance
org.springframework.data.geo.Point
org.springframework.data.geo.Box
org.springframework.data.geo.Circle
org.springframework.data.geo.Polygon

各個模組可以提供其他 SpringDataJacksonModules。
請參閱特定於儲存的部分以獲取更多詳細資訊。

Web 資料繫結支援

您可以使用 Spring Data 投影（在投影中描述）透過使用 JSONPath 表示式（需要 Jayway JsonPath）或 XPath 表示式（需要 XmlBeam）繫結傳入的請求有效負載，如下面的示例所示：

使用 JSONPath 或 XPath 表示式的 HTTP 有效負載繫結

@ProjectedPayload
public interface UserPayload {

  @XBRead("//firstname")
  @JsonPath("$..firstname")
  String getFirstname();

  @XBRead("/lastname")
  @JsonPath({ "$.lastname", "$.user.lastname" })
  String getLastname();
}

您可以將前面的示例中顯示的型別用作 Spring MVC 處理程式方法引數，或者透過在 RestTemplate 的方法之一上使用 ParameterizedTypeReference。前面的方法宣告將嘗試在給定文件中的任何位置查詢 firstname。XML 查詢 lastname 是在傳入文件的頂層執行的。該 JSON 變體首先嚐試一個頂級的 lastname，但如果前者沒有返回值，則也會嘗試巢狀在 user 子文件中的 lastname。這樣，可以輕鬆緩解源文件結構中的更改，而無需客戶端呼叫公開的方法（通常是基於類的有效負載繫結的缺點）。

支援巢狀投影，如投影中所述。如果該方法返回一個複雜的非介面型別，則使用 Jackson ObjectMapper 來對映最終值。

對於 Spring MVC，只要 @EnableSpringDataWebSupport 處於活動狀態並且所需的依賴項在類路徑上可用，必要的轉換器就會自動註冊。對於與 RestTemplate 的使用，請手動註冊 ProjectingJackson2HttpMessageConverter（JSON）或 XmlBeamHttpMessageConverter。

有關更多資訊，請參見規範 Spring Data 示例儲存庫中的 Web 投影示例。

Querydsl Web 支援

對於那些具有 Querydsl 整合的儲存，您可以從 Request 查詢字串中包含的屬性派生查詢。

考慮以下查詢字串：

?firstname=Dave&lastname=Matthews

給定先前示例中的 User 物件，您可以使用 QuerydslPredicateArgumentResolver 將查詢字串解析為以下值，如下所示：

QUser.user.firstname.eq("Dave").and(QUser.user.lastname.eq("Matthews"))

當在類路徑上找到 Querydsl 時，該功能會自動啟用，以及 @EnableSpringDataWebSupport。

將 @QuerydslPredicate 新增到方法簽名提供了一個隨時可用的 Predicate，您可以使用 QuerydslPredicateExecutor 執行它。

型別資訊通常從方法的返回型別解析。由於該資訊不一定與域型別匹配，因此最好使用 QuerydslPredicate 的 root 屬性。

以下示例顯示瞭如何在方法簽名中使用 @QuerydslPredicate：

@Controller
class UserController {

  @Autowired UserRepository repository;

  @RequestMapping(value = "/", method = RequestMethod.GET)
  String index(Model model, @QuerydslPredicate(root = User.class) Predicate predicate,    (1)
          Pageable pageable, @RequestParam MultiValueMap<String, String> parameters) {

    model.addAttribute("users", repository.findAll(predicate, pageable));

    return "index";
  }
}

1	將查詢字串引數解析為與 `User` 匹配的 `Predicate`。

預設繫結如下：

簡單屬性上的 Object 作為 eq。
集合（如屬性）上的 Object 作為 contains。
簡單屬性上的 Collection 作為 in。

您可以透過 @QuerydslPredicate 的 bindings 屬性自定義這些繫結，或者透過利用 Java 8 default methods 並將 QuerydslBinderCustomizer 方法新增到儲存庫介面，如下所示：

interface UserRepository extends CrudRepository<User, String>,
                                 QuerydslPredicateExecutor<User>,                (1)
                                 QuerydslBinderCustomizer<QUser> {               (2)

  @Override
  default void customize(QuerydslBindings bindings, QUser user) {

    bindings.bind(user.username).first((path, value) -> path.contains(value))    (3)
    bindings.bind(String.class)
      .first((StringPath path, String value) -> path.containsIgnoreCase(value)); (4)
    bindings.excluding(user.password);                                           (5)
  }
}

1	`QuerydslPredicateExecutor` 提供了對 `Predicate` 的特定查詢器方法的訪問。
2	在儲存庫介面上定義的 `QuerydslBinderCustomizer` 會自動被拾取並繞過 `@QuerydslPredicate(bindings=…)`。
3	將 `username` 屬性的繫結定義為簡單的 `contains` 繫結。
4	將 `String` 屬性的預設繫結定義為不區分大小寫的 `contains` 匹配。
5	從 `Predicate` 解析中排除 `password` 屬性。

您可以在應用來自儲存庫或 @QuerydslPredicate 的特定繫結之前，註冊一個持有預設 Querydsl 繫結的 QuerydslBinderCustomizerDefaults bean。

儲存庫填充器

如果您使用 Spring JDBC 模組，您可能熟悉使用 SQL 指令碼填充 DataSource 的支援。儲存庫級別也提供類似的抽象，儘管它不使用 SQL 作為資料定義語言，因為它必須是與儲存無關的。因此，填充器支援 XML（透過 Spring 的 OXM 抽象）和 JSON（透過 Jackson）來定義用於填充儲存庫的資料。

假設您有一個名為 data.json 的檔案，其內容如下：

在 JSON 中定義的資料

[ { "_class" : "com.acme.Person",
 "firstname" : "Dave",
  "lastname" : "Matthews" },
  { "_class" : "com.acme.Person",
 "firstname" : "Carter",
  "lastname" : "Beauford" } ]

您可以使用 Spring Data Commons 中提供的儲存庫名稱空間的填充器元素來填充您的儲存庫。要將前面的資料填充到您的 PersonRepository，請宣告一個類似於以下的填充器：

宣告一個 Jackson 儲存庫填充器

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:repository="http://www.springframework.org/schema/data/repository"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
    https://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/data/repository
    https://www.springframework.org/schema/data/repository/spring-repository.xsd">

  <repository:jackson2-populator locations="classpath:data.json" />

</beans>

前面的宣告導致讀取 data.json 檔案並由 Jackson ObjectMapper 反序列化。

JSON 物件被解組到的型別是透過檢查 JSON 文件的 _class 屬性來確定的。基礎設施最終選擇適當的儲存庫來處理反序列化的物件。

要改為使用 XML 來定義應該使用哪些資料來填充儲存庫，您可以使用 unmarshaller-populator 元素。您可以將其配置為使用 Spring OXM 中可用的 XML 編組器選項之一。有關詳細資訊，請參見 Spring 參考文件。以下示例顯示瞭如何使用 JAXB 來解組儲存庫填充器：

宣告一個解組儲存庫填充器（使用 JAXB）

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:repository="http://www.springframework.org/schema/data/repository"
  xmlns:oxm="http://www.springframework.org/schema/oxm"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
    https://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/data/repository
    https://www.springframework.org/schema/data/repository/spring-repository.xsd
    http://www.springframework.org/schema/oxm
    https://www.springframework.org/schema/oxm/spring-oxm.xsd">

  <repository:unmarshaller-populator locations="classpath:data.json"
    unmarshaller-ref="unmarshaller" />

  <oxm:jaxb2-marshaller contextPath="com.acme" />

</beans>

Spring Data 擴充套件

Querydsl 擴充套件

Web 支援

基本 Web 支援

使用 DomainClassConverter 類

Pageable 和 Sort 的 HandlerMethodArgumentResolvers

為 Page 建立 JSON 表示形式

使用 Spring Data 的 PagedModel

全域性啟用簡化的 Page 呈現

對 Page 和 Slice 的超媒體支援

Spring Data Jackson 模組

Web 資料繫結支援

Querydsl Web 支援

儲存庫填充器

使用 `DomainClassConverter` 類

為 `Page` 建立 JSON 表示形式

使用 Spring Data 的 `PagedModel`

全域性啟用簡化的 `Page` 呈現

對 `Page` 和 `Slice` 的超媒體支援