跳到主要内容
版本:4.1.1

自定义仓库实现

Doubao 中英对照 Custom Repository Implementations

Spring Data 提供了多种选项来以极少的代码创建查询方法。但是当这些选项不能满足你的需求时,你也可以为仓库方法提供自己的自定义实现。本节介绍如何做到这一点。

自定义单个仓库​

要用自定义功能来丰富仓库,你必须首先定义一个片段接口以及该自定义功能的实现,如下所示:

interface CustomizedUserRepository {
void someCustomMethod(User user);
}
class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

@Override
public void someCustomMethod(User user) {
// Your custom implementation
}
}
备注

与片段接口对应的类名中最重要的部分是 Impl 后缀。你可以通过设置 @Enable<StoreModule>Repositories(repositoryImplementationPostfix = …) 来自定义特定于存储的后缀。

注意

从历史上看,Spring Data 自定义仓库实现的发现遵循一种命名模式,该模式从仓库派生出自定义实现类名,实际上只允许一个自定义实现。

位于与仓库接口相同包中、匹配“仓库接口名”后接“实现后缀”的类型,会被视为自定义实现并按自定义实现处理。遵循该名称的类可能导致不期望的行为。

我们认为单自定义实现的命名方式已弃用,并建议不要使用这种模式。相反,请迁移到基于片段的编程模型。

该实现本身不依赖于 Spring Data,可以是一个常规的 Spring bean。因此,你可以使用标准的依赖注入行为来注入对其他 bean 的引用(例如 JdbcTemplate)、参与切面等等。

然后你可以让你的仓库接口扩展该片段接口,如下所示:

interface UserRepository extends CrudRepository<User, Long>, CustomizedUserRepository {

// Declare query methods here
}

用你的仓库接口扩展片段接口,将 CRUD 功能与自定义功能结合起来,并使其对客户端可用。

Spring Data 仓库是通过使用构成仓库组合的片段来实现的。片段包括基础仓库、功能切面(例如 Querydsl)以及自定义接口及其实现。每次向你的仓库接口添加一个接口时,你都会通过添加一个片段来增强该组合。基础仓库和仓库切面的实现由每个 Spring Data 模块提供。

以下示例展示了自定义接口及其实现:

interface HumanRepository {
void someHumanMethod(User user);
}

class HumanRepositoryImpl implements HumanRepository {

@Override
public void someHumanMethod(User user) {
// Your custom implementation
}
}

interface ContactRepository {

void someContactMethod(User user);

User anotherContactMethod(User user);
}

class ContactRepositoryImpl implements ContactRepository {

@Override
public void someContactMethod(User user) {
// Your custom implementation
}

@Override
public User anotherContactMethod(User user) {
// Your custom implementation
}
}

以下示例展示了一个扩展了 CrudRepository 的自定义仓库的接口:

interface UserRepository extends CrudRepository<User, Long>, HumanRepository, ContactRepository {

// Declare query methods here
}

仓库可以由多个自定义实现组成,这些实现按其声明顺序导入。自定义实现的优先级高于基础实现和仓库切面。这种排序让你可以覆盖基础仓库和切面方法,并在两个片段提供相同方法签名时解决歧义。仓库片段并不局限于在单个仓库接口中使用。多个仓库可以使用同一个片段接口,从而让你可以跨不同仓库重用自定义。

以下示例展示了一个仓库片段及其实现:

interface CustomizedSave<T> {
<S extends T> S save(S entity);
}

class CustomizedSaveImpl<T> implements CustomizedSave<T> {

@Override
public <S extends T> S save(S entity) {
// Your custom implementation
}
}

以下示例展示了一个使用前面那个仓库片段的仓库:

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

interface PersonRepository extends CrudRepository<Person, Long>, CustomizedSave<Person> {
}

配置​

仓库基础设施会通过扫描找到仓库所在包之下的类,来自动检测自定义实现片段。这些类需要遵循命名约定,即追加一个默认为 Impl 的后缀。

以下示例展示了一个使用默认后缀的仓库,以及一个为后缀设置自定义值的仓库:

示例 1. 配置示例

@EnableRedisRepositories(repositoryImplementationPostfix = "MyPostfix")
class Configuration { … }

前面示例中的第一个配置会尝试查找名为 com.acme.repository.CustomizedUserRepositoryImpl 的类作为自定义仓库实现。第二个示例会尝试查找 com.acme.repository.CustomizedUserRepositoryMyPostfix。

歧义的解决​

如果在不同包中找到多个类名匹配的实现,Spring Data 会使用 bean 名称来确定使用哪一个。

对于前面展示的 CustomizedUserRepository 的以下两个自定义实现,会使用第一个实现。它的 bean 名称是 customizedUserRepositoryImpl,这与片段接口(CustomizedUserRepository)加上后缀 Impl 的名称相匹配。

示例 2. 歧义实现的解决

class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

// Your custom implementation
}
@Component("specialCustomImpl")
class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

// Your custom implementation
}

如果你用 @Component("specialCustom") 注解 UserRepository 接口,那么 bean 名称加上 Impl 就会与在 com.acme.impl.two 中为仓库实现定义的那个相匹配,并使用它而不是第一个。

手动装配​

如果你的自定义实现仅使用基于注解的配置和自动装配,那么前面展示的方法就能很好地工作,因为它被当作任何其他 Spring bean 一样对待。如果你的实现片段 bean 需要特殊的装配,你可以按照前一节中描述的约定声明该 bean 并为其命名。然后基础设施会按名称引用手动定义的 bean 定义,而不是自己创建一个。以下示例展示了如何手动装配自定义实现:

示例 3. 自定义实现的手动装配

class MyClass {
MyClass(@Qualifier("userRepositoryImpl") UserRepository userRepository) {
…
}
}

用 spring.factories 注册片段​

正如在配置一节中已经提到的,基础设施只会在仓库基包内自动检测片段。因此,位于其他位置或希望由外部归档提供的片段,如果不共享共同的命名空间,就不会被发现。在 spring.factories 中注册片段可以让你绕过这一限制,如下节所述。

设想你想利用文本搜索索引,为你的组织提供一些可跨多个仓库使用的自定义搜索功能。

首先你只需要片段接口。注意泛型 <T> 参数,用于使片段与仓库领域类型保持一致。

public interface SearchExtension<T> {

List<T> search(String text, Limit limit);
}

假设实际的全文搜索可以通过一个 SearchService 获得,该 SearchService 在上下文中注册为一个 Bean,这样你就可以在我们的 SearchExtension 实现中使用它。运行搜索所需要的只是集合(或索引)名称以及一个对象映射器,它将搜索结果转换为实际的领域对象,如下所示。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Limit;
import org.springframework.data.repository.core.RepositoryMethodContext;

class DefaultSearchExtension<T> implements SearchExtension<T> {

private final SearchService service;

DefaultSearchExtension(SearchService service) {
this.service = service;
}

@Override
public List<T> search(String text, Limit limit) {
return search(RepositoryMethodContext.getContext(), text, limit);
}

List<T> search(RepositoryMethodContext metadata, String text, Limit limit) {

Class<T> domainType = metadata.getRepository().getDomainType();

String indexName = domainType.getSimpleName().toLowerCase();
List<String> jsonResult = service.search(indexName, text, 0, limit.max());

return jsonResult.stream().map(…).collect(toList());
}
}

在上面的示例中,RepositoryMethodContext.getContext() 用于检索实际方法调用的元数据。RepositoryMethodContext 暴露附加到仓库的信息,例如领域类型。在本例中,我们使用仓库领域类型来标识要搜索的索引名称。

暴露调用元数据代价高昂,因此默认禁用。要访问 RepositoryMethodContext.getContext(),你需要通知负责创建实际仓库的仓库工厂暴露方法元数据。

向片段实现添加 RepositoryMetadataAccess 标记接口会触发基础设施,并为使用该片段的那些仓库启用元数据暴露。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Limit;
import org.springframework.data.repository.core.support.RepositoryMetadataAccess;
import org.springframework.data.repository.core.RepositoryMethodContext;

class DefaultSearchExtension<T> implements SearchExtension<T>, RepositoryMetadataAccess {

// ...
}

在片段声明和实现都就绪之后,你可以在 META-INF/spring.factories 文件中注册该扩展,并在需要时打包。

com.acme.search.SearchExtension=com.acme.search.DefaultSearchExtension

现在你就可以使用你的扩展了;只需将该接口添加到你的仓库中。

import com.acme.search.SearchExtension;
import org.springframework.data.repository.CrudRepository;

interface MovieRepository extends CrudRepository<Movie, String>, SearchExtension<Movie> {

}

自定义基础仓库​

当你想自定义基础仓库行为以使所有仓库都受影响时,前一节中描述的方法需要对每个仓库接口进行自定义。要改为更改所有仓库的行为,你可以创建一个扩展了特定于持久化技术的仓库基类的实现。该类随后充当仓库代理的自定义基类,如下例所示:

class MyRepositoryImpl<T, ID>
extends SimpleJpaRepository<T, ID> {

private final EntityManager entityManager;

MyRepositoryImpl(JpaEntityInformation entityInformation,
EntityManager entityManager) {
super(entityInformation, entityManager);

// Keep the EntityManager around to used from the newly introduced methods.
this.entityManager = entityManager;
}

@Override
@Transactional
public <S extends T> S save(S entity) {
// implementation goes here
}
}
警告

该类需要具有特定于存储的仓库工厂实现所使用的超类构造函数。如果仓库基类有多个构造函数,请重写那个接受 EntityInformation 加上特定于存储的基础设施对象(例如 EntityManager 或模板类)的构造函数。

最后一步是让 Spring Data 基础设施感知到自定义的仓库基类。在配置中,你可以使用 repositoryBaseClass 来做到这一点,如下例所示:

示例 4. 配置自定义仓库基类

@Configuration
@EnableRedisRepositories(repositoryBaseClass = MyRepositoryImpl.class)
class ApplicationConfiguration { … }

自定义仓库工厂​

通过 RepositoryFactoryCustomizer 自定义仓库工厂,可以直接访问参与仓库实例创建的组件。当你想调整代理创建的某些方面而又不想引入一个完全自定义的仓库工厂 bean 时,这种机制很有用。以下示例展示了如何注册额外的监听器和代理通知器:

factoryBean.addRepositoryFactoryCustomizer(repositoryFactory -> {
repositoryFactory.addInvocationListener(…);
repositoryFactory.addQueryCreationListener(…);

repositoryFactory.addRepositoryProxyPostProcessor((factory, repositoryInformation) -> factory.addAdvice(…));
});

一个 RepositoryFactoryCustomizer 与特定的仓库工厂 bean 相关联,理想情况下是通过 BeanPostProcessor,这样只有特定的仓库会受影响。请注意,customizer bean 不会自动应用,以防止不必要的装配,这种问题在多仓库安排或使用多个 Spring Data 模块时尤为突出。

自定义仓库工厂 Bean​

自定义仓库创建的最强大方法是提供一个自定义仓库工厂 bean,通常是 RepositoryFactorySupport、TransactionalRepositoryFactoryBeanSupport 或特定于存储的仓库工厂 bean 的子类。

自定义仓库工厂 bean 让你可以完全访问底层仓库工厂,从而彻底更改仓库创建。

请注意,这种方法需要最多的工作量,通常只在你想更改仓库创建的核心方面时才需要。此外,你还需要考虑用于识别查询方法、基础实现方法和自定义实现的仓库元数据派生。以下摘要概述了关键方面:

  • repositoryBaseClass:仓库基类定义哪些方法由基类实现,哪些方法需要通过切面或自定义实现进行额外处理。
  • repositoryFragmentsContributor:一个 RepositoryFragmentsContributor 允许在收集完所有标准片段之后对仓库组合做出贡献。存储模块使用这种机制来添加功能,例如 Querydsl 或 Query-by-Example 支持。它还充当第三方扩展的 SPI。
  • exposeMetadata:控制是否可以通过 RepositoryMethodContext.getContext() 获取调用元数据。