|
此版本仍在开发中，尚未被视为稳定版本。如需使用最新的稳定版本，请使用 Spring Data Relational 4.0.4！ |
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 支持，请在您的仓库接口中继承 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 相关的组件要求 classpath 中包含 Spring MVC 的 JAR 文件。
其中一些甚至提供了与 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 注解会注册若干组件。
我们将在本节稍后部分讨论这些组件。
它还会检测类路径上是否存在 Spring HATEOAS，并在存在时为其注册相应的集成组件。
基本 Web 支持
上一节中所示的配置注册了几个基本组件：
-
使用
DomainClassConverter类 让 Spring MVC 从请求参数或路径变量中解析由仓库管理的领域类实例。 -
HandlerMethodArgumentResolver实现，使 Spring MVC 能够从请求参数中解析Pageable和Sort实例。 -
Jackson 模块，用于对
Point和Distance等类型进行序列化/反序列化，或根据所使用的 Spring Data 模块存储特定类型。
使用DomainClassConverter类
DomainClassConverter 类允许您在 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类型，然后最终通过调用为该领域类型注册的仓库实例上的findById(…)方法来获取。
目前，该仓库必须实现 CrudRepository 才有资格被发现用于转换。 |
用于 Pageable 和 Sort 的 HandlerMethodArgumentResolvers
上一节中所示的配置片段还会注册一个 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)，但你可以通过在 @PageableDefault 参数上使用 Pageable 注解来自定义它。
创建 JSON 表示形式以用于Page
Spring MVC 控制器通常会尝试最终向客户端渲染一个 Spring Data 分页对象（Page）的表示形式。
虽然可以直接从处理方法中返回 Page 实例，让 Jackson 按原样进行序列化，但我们强烈不建议这样做，因为其底层实现类 PageImpl 是一个领域类型（domain type）。
这意味着我们可能出于无关的原因需要更改其 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 omitted
@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，你可以通过如下方式调整 PageImpl 注解，从而启用将 PagedModel 实例自动转换为 @EnableSpringDataWebSupport 的功能：
@EnableSpringDataWebSupport(pageSerializationMode = VIA_DTO)
class MyConfiguration { }这将允许您的控制器仍然返回 Page 实例，并且它们会自动被渲染为简化表示形式：
@Controller
class MyController {
private final MyRepository repository;
// Constructor omitted
@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 的工作方式完全相同：
@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" : "http://localhost: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 模块，例如org.springframework.data.geo.Distance和org.springframework.data.geo.Point，由 Spring Data 域使用。
这些模块仅导入一次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
|
单个模块可能提供额外的 |
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 处理器方法的参数，或者在 ParameterizedTypeReference 的某个方法上使用 RestTemplate。
上述方法声明会尝试在给定文档的任意位置查找 firstname。
lastname 的 XML 查找是在传入文档的顶层进行的。
而其 JSON 变体则首先尝试在顶层查找 lastname，如果未找到值，还会尝试在 lastname 子文档中嵌套查找 user。
通过这种方式，即使源文档的结构发生变化，也能轻松缓解影响，而无需修改调用这些公开方法的客户端代码（这通常是基于类的载荷绑定的一个缺点）。
支持如投影（Projections）中所述的嵌套投影。
如果方法返回一个复杂的非接口类型，则会使用 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 来执行它。
类型信息通常从方法的返回类型解析得出。
由于该信息不一定与领域类型匹配，因此使用 root 的 QuerydslPredicate 属性可能是个不错的主意。 |
以下示例展示了如何在方法签名中使用 @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 | 将查询字符串参数解析为与 Predicate 匹配的 User。 |
默认绑定如下：
-
Object用于简单属性，如eq。 -
在集合类属性上使用
Object的contains方法。 -
Collection用于简单属性，如in。
你可以通过 bindings 注解的 @QuerydslPredicate 属性来定制这些绑定，或者利用 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 | 从 password 解析中排除 Predicate 属性。 |
你可以在应用来自仓库或 QuerydslBinderCustomizerDefaults 的特定绑定之前，注册一个包含默认 Querydsl 绑定的 @QuerydslPredicate Bean。 |
存储库填充器
如果你使用 Spring JDBC 模块，可能已经熟悉通过 SQL 脚本填充 DataSource 的功能。
在仓库（repositories）层面也提供了类似的抽象，但由于它必须与底层存储无关，因此并未使用 SQL 作为数据定义语言。
因此，这些填充器（populators）支持使用 XML（通过 Spring 的 OXM 抽象）和 JSON（通过 Jackson）来定义用于填充仓库的数据。
假设你有一个名为 data.json 的文件，其内容如下：
[ { "_class" : "com.acme.Person",
"firstname" : "Dave",
"lastname" : "Matthews" },
{ "_class" : "com.acme.Person",
"firstname" : "Carter",
"lastname" : "Beauford" } ]您可以使用 Spring Data Commons 中提供的 repository 命名空间的 populator 元素来填充您的仓库。
要将上述数据填充到您的 PersonRepository 中，请声明一个类似于以下内容的 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 来定义应填充到仓库中的数据，可以使用 unmarshaller-populator 元素。
您可以将其配置为使用 Spring OXM 中提供的任一 XML 编组器选项。
有关详细信息，请参阅Spring 参考文档。
以下示例展示了如何使用 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>