Spring Data 擴充套件

本節文件介紹了 Spring Data 的一組擴充套件，這些擴充套件支援在各種上下文中使用 Spring Data。目前，大部分整合都針對 Spring MVC。

Querydsl 擴充套件

Querydsl 是一個框架，透過其流式 API 支援構建靜態型別的類似 SQL 的查詢。

Querydsl 的維護速度已放緩，社群已在 OpenFeign 下 fork 了該專案，地址為 github.com/OpenFeign/querydsl (groupId io.github.openfeign.querydsl)。Spring Data 盡力支援此 fork。

幾個 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 位於 classpath 中。其中一些甚至提供與 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 註解會註冊一些元件。我們將在本節後面討論這些元件。它還會檢測 classpath 中的 Spring HATEOAS 並註冊相應的整合元件（如果存在）。

基本 Web 支援

在 XML 中啟用 Spring Data Web 支援

上一節中所示的配置會註冊一些基本元件

使用 DomainClassConverter 類，讓 Spring MVC 從請求引數或路徑變數解析 Repository 管理的域類例項。
HandlerMethodArgumentResolver 實現，讓 Spring MVC 從請求引數解析 Pageable 和 Sort 例項。
Jackson 模組，用於反/序列化 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 由一個名為 PagedResourcesAssembler 的 Spring HATEOAS RepresentationModelAssembler 介面實現完成。類似地，Slice 例項可以使用 SlicedResourcesAssembler 轉換為 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 的資訊。
根據 Page 的狀態，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 參考文件。

assembler 生成了正確的 URI，並且也使用了預設配置來解析引數到 Pageable 以供後續請求使用。這意味著，如果你更改了該配置，連結會自動遵循更改。預設情況下，assembler 指向呼叫它的控制器方法，但你可以透過傳遞自定義的 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。

常見基礎設施會為以下域型別註冊資料繫結 mixins。

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。lastname 的 XML 查詢在傳入文件的頂級執行。JSON 變體首先嚐試頂級的 lastname，如果前者未返回值，則還會嘗試巢狀在 user 子文件中的 lastname。透過這種方式，可以輕鬆緩解源文件結構的變化，而無需客戶端呼叫暴露的方法（這通常是基於類負載繫結的缺點）。

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

對於 Spring MVC，一旦 @EnableSpringDataWebSupport 處於活動狀態且所需的依賴項位於 classpath 中，就會自動註冊必要的轉換器。對於與 RestTemplate 一起使用，請手動註冊 ProjectingJackson2HttpMessageConverter (JSON) 或 XmlBeamHttpMessageConverter。

有關更多資訊，請參見規範 Spring Data Examples repository 中的web 投影示例。

Querydsl Web 支援

對於那些集成了 Querydsl 的儲存，你可以從 Request 查詢字串中包含的屬性派生查詢。

考慮以下查詢字串

?firstname=Dave&lastname=Matthews

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

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

當 classpath 中找到 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 方法新增到 repository 介面來自定義這些繫結，如下所示

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	在 repository 介面上定義的 `QuerydslBinderCustomizer` 會自動獲取，並快捷方式 `@QuerydslPredicate(bindings=…)`。
3	為 `username` 屬性定義繫結為簡單的 `contains` 繫結。
4	為 `String` 屬性定義預設繫結為不區分大小寫的 `contains` 匹配。
5	從 `Predicate` 解析中排除 `password` 屬性。

你可以註冊一個 QuerydslBinderCustomizerDefaults bean，該 bean 包含預設的 Querydsl 繫結，然後在應用來自 repository 或 @QuerydslPredicate 的特定繫結之前使用這些預設繫結。

Repository Populator

如果你使用 Spring JDBC 模組，你可能熟悉用 SQL 指令碼填充 DataSource 的支援。在 repository 級別也有類似的抽象，儘管它不使用 SQL 作為資料定義語言，因為它必須獨立於儲存。因此，populator 支援 XML（透過 Spring 的 OXM 抽象）和 JSON（透過 Jackson）來定義用於填充 repository 的資料。

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

JSON 中定義的資料

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

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

宣告 Jackson Repository Populator

<?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 屬性來確定。基礎設施最終會選擇適當的 repository 來處理反序列化後的物件。

要改用 XML 定義要填充 repository 的資料，可以使用 unmarshaller-populator 元素。你將其配置為使用 Spring OXM 中提供的 XML marshaller 選項之一。詳細資訊請參見Spring 參考文件。以下示例展示如何使用 JAXB 對 repository populator 進行反序列化

宣告一個使用 JAXB 的 unmarshalling Repository Populator

<?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 支援

Repository Populator

使用 `DomainClassConverter` 類

建立 `Page` 的 JSON 表示

使用 Spring Data 的 `PagedModel`

全域性啟用簡化的 `Page` 渲染

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