玩转单表查询--JPA版

1.概览

单表查询在业务开发中占比最大，是所有 CRUD Boy 的入门必备，所有人在 JavaBean 和 SQL 之间乐此不疲。而在我看来，该部分是最枯燥、最没有技术含量的“技能”。

1.1. 背景

公司规定，线上服务不允许使用 Join 语句，只能使用最简单的单表查询，开发人员成天在 输入参数、SQL执行、返回结果之间不停地折腾。

1.2. 目标

需要一个框架，可以灵活的定制简单的数据查询，但又不能过于灵活，需要对使用方式进行严格限制。

灵活定制，是为了快速开发，提升效率，降低bug；对使用进行限制，是为了将掌控权控制在开发，不会因为使用不当造成线上问题。因此，对框架有如下要求：

支持灵活的查询定义，无需手写 SQL；

支持常见的查询，包括过滤、排序、分页等；

支持扩展，应对个性化需求；

2. 快速入门

该框架依赖 Spring Data Jpa 的 JpaSpecificationExecutor 能力。

2.1. 构建 JPA 环境

首先，引入 Spring data jpa 相关依赖：

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

其次，新建 JpaUser Entity 类：

@Data
@Entity
@Table(name = "t_user")
public class JpaUser implements User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

private String name;

private Integer status;

private Date birthAt;

private String mobile;
}

新建 JpaUserRepository

public interface JpaUserRepository extends Repository<JpaUser, Long>, JpaSpecificationExecutor<JpaUser> {
}

JpaUserRepository 继承两个接口：

Repository，标记为一个仓库，由 spring data 为其创建代理类；

JpaSpecificationExecutor，使其具备 Specification 查询能力；

2.2. 添加 singlequery 支持

在 pom 中增加 singlequery 相关依赖：

<dependency>
<groupId>com.geekhalo.lego</groupId>
<artifactId>lego-starter-singlequery</artifactId>
<version>0.1.3-single_query_for_jpa-SNAPSHOT</version>
</dependency>

Starter 中的 JpaBasedSingleQueryConfiguration 将为我们完成全部配置。

2.3. 创建自己的 Repository 实现

创建 JpaUserSingleQueryService，继承自 AbstractSpecificationQueryRepository，具体如下：

@Repository
public class JpaUserSingleQueryService
extends AbstractSpecificationQueryRepository
implements UserSingleQueryService {

public JpaUserSingleQueryService(JpaUserRepository specificationExecutor) {
super(specificationExecutor, JpaUser.class);
}
}

其中，构造参数 JpaUserRepository 为 spring data jpa 为我们生成的 Proxy；
AbstractSpecificationQueryRepository 为我们提供基本的查询能力；

其中，QueryRepository 提供如下查询能力：

/**
*
* @param query 查询参数
* @param converter 结果转化器
* @param <Q>
* @param <R>
* @return
*/
<Q, R> List<R> listOf(Q query, Function<E, R> converter);

/**
*
* @param query 查询参数
* @param <Q>
* @return
*/
default <Q> List<E> listOf(Q query){
return listOf(query, e->e);
}

/**
* 获取数量
* @param query 查询参数
* @param <Q>
* @return
*/
<Q> Long countOf(Q query);

/**
* 获取单条记录
* @param query 查询参数
* @param converter 结果转化器
* @param <Q>
* @param <R>
* @return
*/
<Q, R> R get(Q query, Function<E, R> converter);

/**
* 获取单条记录
* @param query 查询参数
* @param <Q>
* @return
*/
default <Q> E get(Q query) {
return get(query, e -> e);
}

/**
* 分页查询
* @param query 查询参数
* @param converter 结果转换器
* @param <Q>
* @param <R>
* @return
*/
<Q, R> Page<R> pageOf(Q query, Function<E, R> converter);

/**
* 分页查询
* @param query
* @param <Q>
* @return
*/
default <Q> Page<E> pageOf(Q query){
return pageOf(query, e -> e);
}

2.4. 创建查询对象，添加查询注解

定义查询对象，具体如下：

@Data
public class QueryByIdIn {
@FieldIn(value = "id", fieldType = Long.class)
private List<Long> ids;
}

其中，@FieldIn 表明过滤字段和过滤方式；

编写测试用例如下：

@Test
void getByIds() {
List<Long> ids = Arrays.asList(1L, 2L, 3L, 4L, 5L, 6L, 7L, 8L, 9L, 10L);
QueryByIdIn queryByIdIn = new QueryByIdIn();
queryByIdIn.setIds(ids);
{
List<User> users = this.getSingleQueryService().listOf(queryByIdIn);
Assertions.assertNotNull(users);
Assertions.assertTrue(CollectionUtils.isNotEmpty(users));
Assertions.assertEquals(10, users.size());
}
{
Long count = this.getSingleQueryService().countOf(queryByIdIn);
Assertions.assertEquals(10L, count);
}
}

运行用例，控制台打印 SQL 如下：

Hibernate: select
jpauser0_.id as id1_0_, jpauser0_.birth_at as birth_at2_0_, jpauser0_.mobile as mobile3_0_, jpauser0_.name as name4_0_, jpauser0_.status as status5_0_
from t_user jpauser0_
where jpauser0_.id in (? , ? , ? , ? , ? , ? , ? , ? , ? , ?)
Hibernate: select
count(jpauser0_.id) as col_0_0_
from t_user jpauser0_
where jpauser0_.id in (? , ? , ? , ? , ? , ? , ? , ? , ? , ?)

当前支持的过滤注解包括：

注解

含义

FieldEqualTo

等于

FieldGreaterThan

大于

FieldGreaterThanOrEqualTo

大于等于

FieldIn

in 操作

FieldIsNull

是否为 null

FieldLessThan

小于

FieldLessThanOrEqualTo

小于等于

FieldNotEqualTo

不等于

FieldNotIn

not in

EmbeddedFilter

嵌入查询对象

2.5. 嵌入对象查询

新建 嵌入对象 QueryByStatusAndBirth，在类上增加过滤注解，具体如下：

@Data
public class QueryByStatusAndBirth {
@FieldEqualTo("status")
private Integer status;

@FieldGreaterThan("birthAt")
private Date birthAfter;
}

新建查询对象 QueryByEmbeddedFilter，使用 @EmbeddedFilter 标注嵌入对象，具体如下：

@Data
public class QueryByEmbeddedFilter {
@FieldGreaterThan("id")
private Long id;

@EmbeddedFilter
private QueryByStatusAndBirth statusAndBirth;
}

编写测试用例：

@Test
void queryByEmbeddedFilter() throws Exception{
QueryByEmbeddedFilter query = new QueryByEmbeddedFilter();
query.setId(0L);
QueryByStatusAndBirth queryByStatusAndBirth = new QueryByStatusAndBirth();
query.setStatusAndBirth(queryByStatusAndBirth);
queryByStatusAndBirth.setStatus(1);
queryByStatusAndBirth.setBirthAfter(DateUtils.parseDate("2018-10-01", "yyyy-MM-dd"));

List<User> users = getSingleQueryService().listOf(query);

Assertions.assertTrue(CollectionUtils.isNotEmpty(users));
}

运行测试，获取如下结果：

Hibernate: select
jpauser0_.id as id1_0_, jpauser0_.birth_at as birth_at2_0_, jpauser0_.mobile as mobile3_0_, jpauser0_.name as name4_0_, jpauser0_.status as status5_0_
from t_user jpauser0_
where jpauser0_.id>0 and jpauser0_.status=1 and jpauser0_.birth_at>?

2.6. 排序&分页

新建的查询对象 PageByIdGreater，具体如下：

@Data
public class PageByIdGreater {
@FieldGreaterThan("id")
private Long startId;

private Pageable pageable;

private Sort sort;
}

除过滤注解外，新增 Pageable 和 Sort 两个属性。

添加 单元测试 如下：

@Test
void pageOf(){
{
PageByIdGreater pageByIdGreater = new PageByIdGreater();
pageByIdGreater.setStartId(0L);
Pageable pageable = new Pageable();
pageByIdGreater.setPageable(pageable);
pageable.setPageNo(0);
pageable.setPageSize(5);

Sort sort = new Sort();
pageByIdGreater.setSort(sort);
Sort.Order order = Sort.Order.<Orders>builder()
.orderField(Orders.ID)
.direction(Sort.Direction.ASC)
.build();

sort.getOrders().add(order);

Page<User> userPage = this.getSingleQueryService().pageOf(pageByIdGreater);

Assertions.assertTrue(userPage.hasContent());
Assertions.assertEquals(5, userPage.getContent().size());

Assertions.assertEquals(0, userPage.getCurrentPage());
Assertions.assertEquals(5, userPage.getPageSize());
Assertions.assertEquals(3, userPage.getTotalPages());
Assertions.assertEquals(13, userPage.getTotalElements());

Assertions.assertTrue(userPage.isFirst());
Assertions.assertFalse( userPage.hasPrevious());

Assertions.assertTrue( userPage.hasNext());
Assertions.assertFalse(userPage.isLast());
}
}

运行单元测试，获取如下结果：

Hibernate: select
jpauser0_.id as id1_0_, jpauser0_.birth_at as birth_at2_0_, jpauser0_.mobile as mobile3_0_, jpauser0_.name as name4_0_, jpauser0_.status as status5_0_
from t_user jpauser0_
where jpauser0_.id>0 order by jpauser0_.id asc limit ?
Hibernate: select
count(jpauser0_.id) as col_0_0_
from t_user jpauser0_
where jpauser0_.id>0

先通过 count 查询获取总量，然后通过 limit 进行分页查询获取数据，最终将两者封装成 Page 对象。

2.7. 最大返回值管理

单次返回太多值是数据库性能杀手，框架通过 @MaxResult 对其进行部分支持。

目前支持包括：

策略

含义

LOG

返回结果超过配置值后，打印日志，进行跟踪

ERROR

返回结果超过配置值后，直接抛出异常

SET_LIMIT

将 limit 最大值设置为 配置值，对返回值进行限制

新建查询对象 QueryByIdGreaterWithMaxResult，在类上增加 @MaxResult 注解，具体如下：

@Data
@MaxResult(max = 10, strategy = MaxResultCheckStrategy.LOG)
public class QueryByIdGreaterWithMaxResult {
@FieldGreaterThan(value = "id")
private Long startUserId;
}

其中，max 指最大返回值，strategy 为 日志，运行结果如下：

Hibernate: select
jpauser0_.id as id1_0_, jpauser0_.birth_at as birth_at2_0_, jpauser0_.mobile as mobile3_0_, jpauser0_.name as name4_0_, jpauser0_.status as status5_0_
from t_user jpauser0_
where jpauser0_.id>0
【LOG】result size is 13 more than 10, dao is org.springframework.data.jpa.repository.support.SimpleJpaRepository@77d959f1 param is QueryByIdGreaterWithMaxResult(startUserId=0)

将 strategy 修改为 ERROR，运行测试，抛出异常：

com.geekhalo.lego.core.singlequery.ManyResultException
at com.geekhalo.lego.core.singlequery.support.AbstractQueryRepository.processForMaxResult(AbstractQueryRepository.java:34)
at com.geekhalo.lego.core.singlequery.jpa.support.AbstractSpecificationQueryRepository.listOf(AbstractSpecificationQueryRepository.java:107)

将 strategy 修改为 SET_LIMIT，运行测试，观察 SQL，通过 limit 自动对返回值进行限制。

Hibernate: select
jpauser0_.id as id1_0_, jpauser0_.birth_at as birth_at2_0_, jpauser0_.mobile as mobile3_0_, jpauser0_.name as name4_0_, jpauser0_.status as status5_0_
from t_user jpauser0_
where jpauser0_.id>0 limit ?
【SET_LIMIT】result size is 10 more than 10, please find and fix, dao is org.springframework.data.jpa.repository.support.SimpleJpaRepository@35841d6 param is QueryByIdGreaterWithMaxResult(startUserId=0)

3. 设计&扩展

3.1. 核心设计

核心设计，主要是将输入的 Query 对象转换为 Specification 和 Pageable、Sort 等对象，然后基于 SpecificationExecutor 完成查询，整体流程如下：

SingelQuery-JPA

核心流程如下：

SpecificationConverter 将输入的 Query Object 转换为 Specification、Pagebale、Sort等 实例；

使用 SpecificationExecutor 实例的查询方法获取返回值；

返回值通过 ResultConverter 将 Entity 转换为最终结果；

其中，从 QueryObject 到 相关输入参数的转换为框架的核心，主要包括如下几部分：

Pageable。从 QueryObject 中读取 Pageable 属性，并转化为 Spring data 的 Pageable 实例；

Sort。从 QueryObject 中读取 Sort 属性，并转换为Spring data 的 Sort 实例；

过滤注解。遍历 QueryObject 中属性，根据注解查找到注解处理器，由注解处理器将其转化为 Predicate 实例，最终封装为 Specification 示例。

3.2. 功能扩展

对于数据过滤，框架提供了一套灵活的扩展方案。

系统自带的组件，比如 @FieldEqualTo 都是通过扩展方式实现。核心步骤包括：

自定义注解；

编写注解处理器；

将注解处理器注册为 Spring Bean；

我们以 @FieldEqualTo 为例，如下：

3.2.1. 新增注解 @FieldEqualTo

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface FieldEqualTo {
String value();
}

@Target({ElementType.FIELD}) 说明注解应用于 字段；

@Retention(RetentionPolicy.RUNTIME) 说明注解适用于运行时阶段，这样在运行时通过反射便可读取出来；

String value() 用于配置应用字段；

3.2.2. 实现 JpaFieldEqualToHandler

JpaFieldEqualToHandler 类集成自 AbstractJpaAnnotationHandler，实现 JpaAnnotationHandler接口，具体如下：

public class JpaFieldEqualToHandler
extends AbstractJpaAnnotationHandler<FieldEqualTo>
implements JpaAnnotationHandler<FieldEqualTo>{

public JpaFieldEqualToHandler() {
super(FieldEqualTo.class);
}

@Override
public <E> Predicate create(Root<E> root, CriteriaQuery<?> query, CriteriaBuilder criteriaBuilder, FieldEqualTo fieldEqualTo, Object value) {
return criteriaBuilder.equal(root.get(fieldNameOf(fieldEqualTo)), value);
}

@Override
protected boolean matchField(Field field, Class queryType) {
return queryType == field.getType();
}

@Override
protected String fieldNameOf(FieldEqualTo fieldEqualTo) {
return fieldEqualTo.value();
}
}

其中，JpaAnnotationHandler 接口定义如下：

/**
* Created by taoli on 2022/8/30.
* gitee : https://gitee.com/litao851025/lego
* 编程就像玩 Lego
*/
public interface JpaAnnotationHandler<A extends Annotation> extends SmartComponent<Annotation> {

/**
* 是否支持 Annotion
* @param annotation
* @return
*/
@Override
boolean support(Annotation annotation);

/**
* 创建 Predicate
* @param root
* @param query
* @param criteriaBuilder
* @param annotation
* @param value
* @param <E>
* @return
*/
<E> Predicate create(Root<E> root, CriteriaQuery<?> query, CriteriaBuilder criteriaBuilder, A annotation, Object value);

/**
* 查找 Entity 中的属性，主要用于配置检测
* @param entityCls
* @param a
* @param queryType
* @param <E>
* @return
*/
<E> Field findEntityField(Class<E> entityCls, A a, Class queryType);
}

3.2.3. 将 FieldEqualToHandler 注册为 Spring Bean

@Bean
public JpaFieldEqualToHandler jpaFieldEqualToHandler(){
return new JpaFieldEqualToHandler();
}

这样，就可以在项目中使用该注解进行数据过滤。

4. 项目信息

项目仓库地址：https://gitee.com/litao851025/lego

项目文档地址：https://gitee.com/litao851025/lego/wikis/support/SingleQuery-JPA