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 支持，请在您的仓库接口上扩展 QuerydslPredicateExecutor，如下例所示

仓库上的 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 支持

支持仓库编程模型的 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 可以从请求参数或路径变量中解析仓库管理的领域类实例。
HandlerMethodArgumentResolver 实现，让 Spring MVC 可以从请求参数中解析 Pageable 和 Sort 实例。
Jackson 模块，用于序列化/反序列化 Point 和 Distance 等类型，或存储特定类型，具体取决于使用的 Spring Data 模块。

使用 `DomainClassConverter` 类

DomainClassConverter 类允许您直接在 Spring MVC 控制器方法签名中使用领域类型，这样您就不必手动通过仓库查找实例，如下例所示

在方法签名中使用领域类型的 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 成为有效的控制器方法参数，如下例所示

使用 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=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)，但您可以使用 @PageableDefault 注解在 Pageable 参数上进行自定义。

为 `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 字段，暴露了基本的 pagination 元数据。

全局启用简化的 `Page` 渲染

如果您不想修改所有现有控制器以添加映射步骤，从返回 Page 改为返回 PagedModel，您可以通过如下方式调整 @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 的用法完全相同

将 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。添加到方法的 pagination 参数与 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 封套格式不遵循任何正式指定的结构，并且不保证稳定，我们可能随时更改它。强烈建议启用渲染为支持超媒体的官方媒体类型，例如 HAL，Spring HATEOAS 支持此类型。可以通过使用其 @EnableHypermediaSupport 注解来激活这些类型。更多信息请参见Spring HATEOAS 参考文档。

组装器生成了正确的 URI，并采用了默认配置将参数解析为即将到来的请求的 Pageable。这意味着，如果您更改该配置，链接会自动遵循更改。默认情况下，组装器指向调用它的控制器方法，但您可以通过传递一个自定义 Link 作为构建 pagination 链接的基础来自定义这一点，这重载了 PagedResourcesAssembler.toModel(…) 方法。

Spring Data Jackson 模块

核心模块和一些特定存储模块附带了一套用于 Spring Data 领域使用的类型（如 org.springframework.data.geo.Distance 和 org.springframework.data.geo.Point）的 Jackson 模块。
一旦启用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 处于活动状态且类路径中存在所需依赖项，就会自动注册必要的转换器。对于与 RestTemplate 一起使用，请手动注册 ProjectingJackson2HttpMessageConverter (JSON) 或 XmlBeamHttpMessageConverter。

更多信息，请参阅规范的Spring Data Examples repository 中的web projection example。

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` 属性。

您可以注册一个 QuerydslBinderCustomizerDefaults bean，该 bean 在应用仓库或 @QuerydslPredicate 的特定绑定之前持有默认的 Querydsl 绑定。

仓库填充器

如果您使用 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 marshaller 选项之一。详细信息请参见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` 的超媒体支持