Spring Data 扩展

DeepSeek V3 中英对照 Spring Data Extensions

本节记录了一系列 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 的集成，如下例所示：

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

设置注解处理

为了在 Spring Data JPA 中使用 Querydsl，你需要在构建系统中设置注解处理，以生成 Q 类。虽然你可以手动编写 Q 类，但建议使用 Querydsl 注解处理器来为你生成这些类，以确保 Q 类与你的领域模型保持同步。

大多数 Spring Data 用户并不使用 Querydsl，因此对于无法从 Querydsl 中受益的项目来说，要求额外的强制依赖是没有意义的。因此，你需要在构建系统中激活注解处理。

以下示例展示了如何在 Maven 和 Gradle 中通过提及依赖项和编译器配置更改来设置注解处理：

Maven

<dependencies>
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-jpa</artifactId>
        <version>${querydslVersion}</version>
        <classifier>jakarta</classifier>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
            <annotationProcessorPaths>
                <!-- Explicit opt-in required via annotationProcessors or
                        annotationProcessorPaths on Java 22+, see https://bugs.openjdk.org/browse/JDK-8306819 -->
                <annotationProcessorPath>
                    <groupId>com.querydsl</groupId>
                    <artifactId>querydsl-apt</artifactId>
                    <version>${querydslVersion}</version>
                    <classifier>jakarta</classifier>
                </annotationProcessorPath>
                <annotationProcessorPath>
                    <groupId>jakarta.persistence</groupId>
                    <artifactId>jakarta.persistence-api</artifactId>
                </annotationProcessorPath>
              </annotationProcessorPaths>

                <!-- Recommended: Some IDE's might require this configuration to include generated sources for IDE usage -->
                <generatedTestSourcesDirectory>target/generated-test-sources</generatedTestSourcesDirectory>
                <generatedSourcesDirectory>target/generated-sources</generatedSourcesDirectory>
            </configuration>
        </plugin>
    </plugins>
</build>

xml

Gradle

dependencies {

    implementation 'com.querydsl:querydsl-jpa:${querydslVersion}:jakarta'
    annotationProcessor 'com.querydsl:querydsl-apt:${querydslVersion}:jakarta'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api'

    testAnnotationProcessor 'com.querydsl:querydsl-apt:${querydslVersion}:jakarta'
    testAnnotationProcessor 'jakarta.persistence:jakarta.persistence-api'
}

groovy

请注意，上述设置展示了最简单的用法，省略了项目可能需要的任何其他选项或依赖项。

Web 支持

支持仓库编程模型的 Spring Data 模块附带了各种 Web 支持。与 Web 相关的组件需要将 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 注解注册了一些组件。我们将在本节后续部分讨论这些组件。它还会检测类路径中的 Spring HATEOAS，并为其注册集成组件（如果存在）。

基本网页支持

在 XML 中启用 Spring Data 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|DESC)(,IgnoreCase) 格式排序的属性。默认排序方向是区分大小写的升序。如果你想切换方向或大小写敏感性，可以使用多个 sort 参数 — 例如，?sort=firstname&sort=lastname,asc&sort=city,ignorecase。 |

要自定义此行为，可以分别注册一个实现了 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 简化版本（位于 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
  }
}

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 ommitted

  @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。同样，Slice 实例可以使用 SlicedResourcesAssembler 转换为 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 参考文档。

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

Spring Data Jackson 模块

核心模块以及一些特定于存储的模块附带了一组用于类型的 Jackson 模块，例如 org.springframework.data.geo.Distance 和 org.springframework.data.geo.Point，这些类型由 Spring Data 领域使用。
一旦启用了 Web 支持 并且 com.fasterxml.jackson.databind.ObjectMapper 可用，这些模块就会被导入。

在初始化过程中，SpringDataJacksonModules 和 SpringDataJacksonConfiguration 一样，会被基础架构自动识别，从而使得声明的 com.fasterxml.jackson.databind.Module 能够被 Jackson 的 ObjectMapper 使用。

公共基础设施为以下领域类型注册了数据绑定混合器。

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），如下例所示：

@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 激活并且所需的依赖项在类路径上可用，必要的转换器将自动注册。对于与 RestTemplate 一起使用的情况，需要手动注册 ProjectingJackson2HttpMessageConverter（JSON）或 XmlBeamHttpMessageConverter。

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

Querydsl Web 支持

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

考虑以下查询字符串：

?firstname=Dave&lastname=Matthews

text

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

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

text

备注

当在类路径中发现 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 解析中排除。

提示

你可以在应用来自仓库或 @QuerydslPredicate 的特定绑定之前，注册一个包含默认 Querydsl 绑定的 QuerydslBinderCustomizerDefaults bean。

存储库填充器

如果你使用 Spring JDBC 模块，你可能熟悉使用 SQL 脚本来填充 DataSource 的支持。在仓库（repositories）级别也有类似的抽象，尽管它不使用 SQL 作为数据定义语言，因为它必须与存储无关。因此，填充器（populators）支持通过 Spring 的 OXM 抽象来使用 XML，以及通过 Jackson 来使用 JSON，定义用于填充仓库的数据。

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

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

javascript

您可以使用 Spring Data Commons 中提供的 repository 命名空间的 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 编组器之一。详情请参阅 Spring 参考文档。以下示例展示了如何使用 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>

xml