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

上一节中展示的配置片段还注册了 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（位于 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 字段，暴露了重要的分页元数据。

全局启用简化 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 的工作方式完全相同

使用 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 信封格式不遵循任何正式规范的结构，并且不保证稳定，我们可能随时更改它。强烈建议启用渲染为由 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 可用。

通用基础设施注册了以下领域类型的数据绑定 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

各个模块可能提供额外的 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 存储库中的 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 方法，如下所示

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 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 的 HandlerMethodArgumentResolver

创建 Page 的 JSON 表示

使用 Spring Data 的 PagedModel

全局启用简化 Page 渲染

对 Page 和 Slice 的超媒体支持

Spring Data Jackson 模块

Web 数据绑定支持

Querydsl Web 支持

存储库填充器

使用 `DomainClassConverter` 类