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 的整合，示例如下
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，示例如下
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 註解來啟用整合支援，示例如下
-
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 支援
上一節中顯示的配置註冊了一些基本元件
-
一個使用
DomainClassConverter類的元件，允許 Spring MVC 從請求引數或路徑變數解析 repository 管理的域類例項。 -
HandlerMethodArgumentResolver實現，允許 Spring MVC 從請求引數解析Pageable和Sort例項。 -
Jackson 模組，用於反序列化/序列化
Point和Distance等型別，或特定於儲存的型別，具體取決於使用的 Spring Data 模組。
使用 DomainClassConverter 類
DomainClassConverter 類允許您直接在 Spring MVC 控制器方法簽名中使用域型別，這樣您就不需要手動透過 repository 查詢例項，示例如下
@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 的 HandlerMethodArgumentResolver
上一節中顯示的配置片段還註冊了一個 PageableHandlerMethodArgumentResolver 以及一個 SortHandlerMethodArgumentResolver 例項。此註冊使得 Pageable 和 Sort 成為有效的控制器方法引數，示例如下
@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 例項
|
您要檢索的頁碼。從 0 開始計數，預設為 0。 |
|
您要檢索的頁面大小。預設為 20。 |
|
需要排序的屬性，格式為 |
要自定義此行為，請分別註冊實現 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 的簡化版本（位於 org.springframework.data.web 包中的 Spring Data 版本）。它可以用於包裝 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 欄位，其中公開了基本的 pagination 元資料。
全域性啟用簡化的 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。類似地，Slice 例項可以使用 SlicedResourcesAssembler 轉換為 SlicedModel。以下示例展示瞭如何將 PagedResourcesAssembler 用作控制器方法引數，SlicedResourcesAssembler 的工作方式完全相同
@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。新增到方法的 pagination 引數與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 作為構建 pagination 連結的基礎來對其進行自定義，這會過載 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。
通用基礎設施為以下域型別註冊了資料繫結 mixin。
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
|
各個模組可能提供額外的 |
Web 資料繫結支援
您可以使用 Spring Data 投影（在投影中描述）透過使用 JSONPath 表示式（需要 Jayway JsonPath）或 XPath 表示式（需要 XmlBeam）來繫結傳入的請求載荷，示例如下
@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 projection 示例。
Querydsl Web 支援
對於那些集成了 Querydsl 的儲存，您可以從請求查詢字串中包含的屬性派生查詢。
考慮以下查詢字串
?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 預設方法並將 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 屬性。 |
您可以在應用來自 repository 或 @QuerydslPredicate 的特定繫結之前，註冊一個持有預設 Querydsl 繫結的 QuerydslBinderCustomizerDefaults bean。 |
Repository 填充器
如果您使用 Spring JDBC 模組，您可能熟悉使用 SQL 指令碼填充 DataSource 的支援。在 repository 級別也有類似的抽象，儘管它不使用 SQL 作為資料定義語言，因為它必須獨立於儲存。因此，填充器支援 XML（透過 Spring 的 OXM 抽象）和 JSON（透過 Jackson）來定義用於填充 repository 的資料。
假設您有一個名為 data.json 的檔案，其內容如下
[ { "_class" : "com.acme.Person",
"firstname" : "Dave",
"lastname" : "Matthews" },
{ "_class" : "com.acme.Person",
"firstname" : "Carter",
"lastname" : "Beauford" } ]您可以使用 Spring Data Commons 提供的 repository 名稱空間的填充器元素來填充您的 repository。要將前面的資料填充到您的 PersonRepository，請宣告一個類似於以下的填充器
<?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 填充器
<?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>
