Spring Data 扩展

本节介绍一组 Spring Data 扩展，这些扩展可以在各种上下文中启用 Spring Data 的使用。目前，大多数集成都针对 Spring MVC。

Querydsl 扩展

Querydsl 是一个框架，它通过其流畅的 API 允许构建静态类型的类似 SQL 的查询。

几个 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 参数，例如 ?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的简化版本（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字段，用于公开基本的分页元数据。

全局启用简化的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。类似地，可以使用SlicedResourcesAssembler将Slice实例转换为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。添加到方法的分页参数与PageableHandlerMethodArgumentResolver的设置匹配，以确保稍后可以解析这些链接。

假设数据库中有30个Person实例。您现在可以触发请求（GET localhost:8080/people）并查看类似于以下内容的输出

{ "links" : [
    { "rel" : "next", "href" : "https://127.0.0.1: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模块

核心模块和一些特定于存储的模块附带一组用于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。

通用基础结构注册以下域类型的绑定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处于活动状态并且所需的依赖项在类路径上可用，就会自动注册必要的转换器。对于与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运行它。

类型信息通常从方法的返回类型解析。由于该信息不一定与域类型匹配，因此最好使用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的特定绑定之前注册一个QuerydslBinderCustomizerDefaults bean，该 bean 包含默认的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>

前面的声明会导致Jackson ObjectMapper读取并反序列化data.json文件。

JSON对象反序列化的类型是通过检查JSON文档的_class属性确定的。基础结构最终会选择合适的存储库来处理已反序列化的对象。

如果您希望使用 XML 来定义存储库应填充的数据，则可以使用unmarshaller-populator元素。您可以将其配置为使用 Spring OXM 中提供的 XML 编组器选项之一。有关详细信息，请参阅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>