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来自定义它，该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投影（在Projections中描述）通过使用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。这样，可以轻松地减轻源文档结构的更改，而无需客户端调用公开的方法（通常是基于类的有效负载绑定的缺点）。

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

对于Spring MVC，一旦@EnableSpringDataWebSupport处于活动状态并且所需的依赖项在类路径上可用，就会自动注册必要的转换器。对于与RestTemplate一起使用，请手动注册ProjectingJackson2HttpMessageConverter（JSON）或XmlBeamHttpMessageConverter。

有关更多信息，请参阅规范Spring Data Examples存储库中的web projection示例。

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中的特定绑定之前，注册一个包含默认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编组器选项之一。有关详细信息，请参阅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>