Spring Data 扩展

Doubao 中英对照 Spring Data Extensions

本节介绍一组 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 的集成，如下例所示：

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.
}

java

• 查找并返回与 Predicate 匹配的单个实体。

• 查找并返回与 Predicate 匹配的所有实体。

• 返回与 Predicate 匹配的实体数量。

• 返回是否存在与 Predicate 匹配的实体。

要使用 Querydsl 支持，请在您的仓库接口上扩展 QuerydslPredicateExecutor，如下例所示：

interface UserRepository extends CrudRepository<User, Long>, QuerydslPredicateExecutor<User> {
}

java

前述示例让您可以使用 Querydsl Predicate 实例编写类型安全的查询，如下例所示：

Predicate predicate = user.firstname.equalsIgnoreCase("dave")
	.and(user.lastname.startsWithIgnoreCase("mathews"));

userRepository.findAll(predicate);

java

Web 支持

支持仓库编程模型的 Spring Data 模块附带了多种 Web 支持。与 Web 相关的组件要求 classpath 上存在 Spring MVC JAR。其中一些甚至提供与 Spring HATEOAS 的集成。一般来说，集成支持通过在您的 JavaConfig 配置类中使用 @EnableSpringDataWebSupport 注解来启用，如下例所示：

Java

@Configuration
@EnableWebMvc
@EnableSpringDataWebSupport
class WebConfiguration {}

java

XML

<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" />

xml

@EnableSpringDataWebSupport 注解会注册一些组件，我们将在本节稍后讨论它们。它还会检测 classpath 上的 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";
  }
}

java

该方法直接接收一个 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";
  }
}

java

前述方法签名使 Spring MVC 尝试使用以下默认配置从请求参数派生一个 Pageable 实例：

表 1. 为 Pageable 实例求值的请求参数

page	您要检索的页。从 0 开始索引，默认为 0。
size	您要检索的页大小。默认为 20。
sort	应据以排序的属性，格式为 `property,property(,ASC

important

从请求参数解析出的 Sort.Order 实例是普通的传输对象，原样携带属性名，不会针对领域模型做任何校验。应用程序有责任验证这些值，以防止意外的排序。

要自定义此行为，请分别注册一个实现 PageableHandlerMethodArgumentResolverCustomizer 接口或 SortHandlerMethodArgumentResolverCustomizer 接口的 bean。它的 customize() 方法会被调用，让您能够更改设置，如下例所示：

@Bean SortHandlerMethodArgumentResolverCustomizer sortCustomizer() {
    return s -> s.setPropertyDelimiter("<-->");
}

java

如果对现有 MethodArgumentResolver 设置属性不足以满足您的需求，可以扩展 SpringDataWebConfiguration 或启用了 HATEOAS 的等效配置，重写 pageableResolver() 或 sortResolver() 方法，并导入您自定义的配置文件，而不是使用 @Enable 注解。

如果您需要从请求中解析多个 Pageable 或 Sort 实例（例如用于多张表），可以使用 Spring 的 @Qualifier 注解来区分它们。此时请求参数必须加上 ${qualifier}_ 前缀。以下示例展示了最终的方法签名：

String showUsers(Model model,
      @Qualifier("thing1") Pageable first,
      @Qualifier("thing2") Pageable second) { … }

java

您必须填充 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 omitted

  @GetMapping("/page")
  PagedModel<?> page(Pageable pageable) {
    return new PagedModel<>(repository.findAll(pageable)); 1
  }
}

java

• 将 Page 实例包装进 PagedModel。

这将生成如下所示的 JSON 结构：

{
  "content" : [
     … // Page content rendered here
  ],
  "page" : {
    "size" : 20,
    "totalElements" : 30,
    "totalPages" : 2,
    "number" : 0
  }
}

javascript

请注意该文档如何包含一个 page 字段，用于暴露关键的分页元数据。

全局启用简化的 Page 渲染

如果您不想更改所有现有控制器来添加映射步骤以返回 PagedModel 而不是 Page，可以通过如下方式调整 @EnableSpringDataWebSupport，启用将 PageImpl 实例自动转换为 PagedModel：

@EnableSpringDataWebSupport(pageSerializationMode = VIA_DTO)
class MyConfiguration { }

java

这将允许您的控制器仍然返回 Page 实例，而它们会被自动渲染为简化表示：

@Controller
class MyController {

  private final MyRepository repository;

  // Constructor omitted

  @GetMapping("/page")
  Page<?> page(Pageable pageable) {
    return repository.findAll(pageable);
  }
}

java

对 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));
  }
}

java

如前述示例所示，启用该配置后，PagedResourcesAssembler 即可用作控制器方法参数。对其调用 toModel(…) 会产生以下效果：

• Page 的内容成为 PagedModel 实例的内容。

• PagedModel 对象会附加一个 PageMetadata 实例，其中填充了来自 Page 及底层 Pageable 的信息。

• 根据页的状态，PagedModel 可能会附加 prev 和 next 链接。这些链接指向该方法所映射的 URI。添加到方法上的分页参数与 PageableHandlerMethodArgumentResolver 的设置相匹配，以确保这些链接日后能够被解析。

假设数据库中有 30 个 Person 实例。您现在可以触发一个请求（GET [localhost:8080/people](http://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
  }
}

javascript

注意

此处所示的 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 支持 且 classpath 上存在 tools.jackson.databind.ObjectMapper（Jackson 3），这些模块就会被导入。

备注

tools.jackson.databind 是 Jackson 3 的包前缀。Jackson 2 使用 com.fasterxml.jackson.databind。Jackson 2 支持已被弃用，并将在未来版本中移除；升级说明请参阅 Jackson 3 迁移指南。

在初始化期间，SpringDataJackson3Modules 与 SpringDataJackson3Configuration 一样会被基础设施拾取，从而使声明的 tools.jackson.databind.JacksonModule 对 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

备注

各个模块可能提供额外的 SpringDataJackson3Modules。
更多细节请参阅特定存储部分。

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();
}

java

您可以将前述示例中所示的类型用作 Spring MVC 处理方法参数，或在 RestTemplate 的某个方法上使用 ParameterizedTypeReference。前述方法声明会尝试在给定文档的任意位置查找 firstname。lastname 的 XML 查找在传入文档的顶层进行。其 JSON 变体先尝试顶层 lastname，如果前者未返回值，则还会尝试嵌套在 user 子文档中的 lastname。这样，源文档结构的变化可以轻松得到缓解，而无需客户端调用暴露的方法（这通常是基于类的载荷绑定的一个缺点）。

嵌套投影受支持，如投影中所述。如果方法返回复杂的非接口类型，则使用 Jackson ObjectMapper 来映射最终值。

对于 Spring MVC，一旦 @EnableSpringDataWebSupport 生效且所需依赖在 classpath 上可用，必要的转换器会自动注册。若要与 RestTemplate 一起使用，请手动注册 ProjectingJacksonHttpMessageConverter（JSON）或 XmlBeamHttpMessageConverter。

更多信息，请参阅标准 Spring Data Examples 仓库 中的 Web 投影示例。

备注

默认情况下，绑定集合类属性时上限为 1024 个条目。您可以通过 spring.properties 文件或作为系统属性设置 spring.data.web.projection.collection-limit 属性来覆盖此限制。

Querydsl Web 支持

对于那些集成了 Querydsl 的存储，您可以从 Request 查询字符串中包含的属性派生查询。

考虑以下查询字符串：

?firstname=Dave&lastname=Matthews

text

给定前面示例中的 User 对象，您可以使用 QuerydslPredicateArgumentResolver 将查询字符串解析为以下值，如下所示：

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

text

备注

当在 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";
  }
}

java

• 将查询字符串参数解析为与 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
  }
}

java

• QuerydslPredicateExecutor 提供对用于 Predicate 的特定查找方法的访问。

• 定义在仓库接口上的 QuerydslBinderCustomizer 会被自动拾取，并简化 @QuerydslPredicate(bindings=…​) 的使用。

• 将 username 属性的绑定定义为简单的 contains 绑定。

• 将 String 属性的默认绑定定义为不区分大小写的 contains 匹配。

• 将 password 属性排除在 Predicate 解析之外。

提示

您可以注册一个持有默认 Querydsl 绑定的 QuerydslBinderCustomizerDefaults bean，然后再应用来自仓库或 @QuerydslPredicate 的特定绑定。

仓库填充器

如果您使用 Spring JDBC 模块，可能熟悉用 SQL 脚本填充 DataSource 的支持。在仓库层面也提供了类似的抽象，只不过它不使用 SQL 作为数据定义语言，因为它必须与存储无关。因此，填充器支持 XML（通过 Spring 的 OXM 抽象）和 JSON（通过 Jackson）来定义用于填充仓库的数据。

假设您有一个名为 data.json 的文件，内容如下：

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

javascript

您可以使用 Spring Data Commons 中提供的仓库命名空间的 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>

xml

前述声明会导致 data.json 文件被读取，并由 Jackson ObjectMapper 反序列化。

JSON 对象被反编组到的类型，是通过检查 JSON 文档的 _class 属性来确定的。基础设施最终会选择合适的仓库来处理反序列化出的对象。

若要改用 XML 来定义应填充仓库的数据，可以使用 unmarshaller-populator 元素。您将其配置为使用 Spring OXM 中可用的 XML marshaller 选项之一。详情请参阅 Spring 参考文档。以下示例展示了如何用 JAXB 反编组一个仓库 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>

xml