1.概览

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

1.1. 背景

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

1.2. 目标

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

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

1. 支持灵活的查询定义，无需手写 SQL；
2. 支持常见的查询，包括过滤、排序、分页等；
3. 支持扩展，应对个性化需求；

2. 快速入门

该框架依赖 MyBatis 的 selectByExample 特性。

2.1. 使用 MyBatis Generator，自动生成相关代码

首先，引入 MyBatis 相关依赖：

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>2.2.2</version>
</dependency>

其次，在 maven 中增加 mybatis-generator-maven-plugin 插件：

<plugin>
    <groupId>org.mybatis.generator</groupId>
    <artifactId>mybatis-generator-maven-plugin</artifactId>
    <version>1.3.7</version>
    <configuration>
        <verbose>true</verbose>
        <overwrite>true</overwrite>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.29</version>
        </dependency>
        <dependency>
            <groupId>com.itfsw</groupId>
            <artifactId>mybatis-generator-plugin</artifactId>
            <version>1.3.10</version>
        </dependency>
    </dependencies>
</plugin>

其中，mybatis-generator-plugin 提供 limit 分页支持。

新建 generatorConfig.xml，并指定LimitPlugin。

<!-- MySQL分页插件 -->
<plugin type="com.itfsw.mybatis.generator.plugins.LimitPlugin">
    <!-- 通过配置startPage影响Example中的page方法开始分页的页码，默认分页从0开始 -->
    <property name="startPage" value="0"/>
</plugin>

运行 generator 自动生成相关文件，包括 Mapper.xml、Mapper 接口、Entity 类 和 Example 查询类。其中，Example 类是该框架的关键。

具体操作，可参照mybatis-generator 官方文档，或 google 检索。

2.2. 添加 singlequery 支持

在 pom 中增加 singlequery 相关依赖：

<dependency>
    <groupId>com.geekhalo.lego</groupId>
    <artifactId>lego-starter-singlequery</artifactId>
    <version>0.1.2-single_query-SNAPSHOT</version>
</dependency>

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

2.3. 创建自己的 Repository 实现

创建 MyBatisUserSingleQueryService，继承自 AbstractReflectBasedExampleQueryRepository，具体如下：

@Repository
public class MyBatisUserSingleQueryService
        extends AbstractReflectBasedExampleQueryRepository
        implements UserSingleQueryService {
    public MyBatisUserSingleQueryService(MyBatisUserMapper mapper){
        super(mapper, MyBatisUserExample.class);
    }
}

其中，MyBatisUserMapper 为 MyBatis Generator 生成的 Mapper 接口；MyBatisUserExample 为 Example 查询类；

其中，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 如下：

==>  Preparing: select id, name, status, birth_at, mobile from t_user WHERE ( id in ( ? , ? , ? , ? , ? , ? , ? , ? , ? , ? ) )
==> Parameters: 1(Long), 2(Long), 3(Long), 4(Long), 5(Long), 6(Long), 7(Long), 8(Long), 9(Long), 10(Long)
<==      Total: 10
==>  Preparing: select count(*) from t_user WHERE ( id in ( ? , ? , ? , ? , ? , ? , ? , ? , ? , ? ) )
==> Parameters: 1(Long), 2(Long), 3(Long), 4(Long), 5(Long), 6(Long), 7(Long), 8(Long), 9(Long), 10(Long)
<==      Total: 1

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

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));
}

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

==>  Preparing: select id, name, status, birth_at, mobile from t_user WHERE ( id > ? and status = ? and birth_at > ? )
==> Parameters: 0(Long), 1(Integer), 2018-10-01 00:00:00.0(Timestamp)
<==      Total: 13

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());
    }
}

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

==>  Preparing: select count(*) from t_user WHERE ( id > ? )
==> Parameters: 0(Long)
<==      Total: 1
==>  Preparing: select id, name, status, birth_at, mobile from t_user WHERE ( id > ? ) order by id ASC limit 0, 5
==> Parameters: 0(Long)
<==      Total: 5

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

2.7. 最大返回值管理

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

目前支持包括：

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

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

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

==>  Preparing: select id, name, status, birth_at, mobile from t_user WHERE ( id > ? )
==> Parameters: 0(Long)
<==      Total: 13
【LOG】result size is 13 more than 10, mapper is org.apache.ibatis.binding.MapperProxy@2ab8589a param is QueryByIdGreaterWithMaxResult(startUserId=0)

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

com.geekhalo.lego.core.singlequery.ManyResultException
    at com.geekhalo.lego.core.singlequery.mybatis.support.AbstractReflectBasedExampleQueryRepository.processForMaxResult(AbstractReflectBasedExampleQueryRepository.java:102)
    at com.geekhalo.lego.core.singlequery.mybatis.support.AbstractReflectBasedExampleQueryRepository.listOf(AbstractReflectBasedExampleQueryRepository.java:77)
    at com.geekhalo.lego.core.singlequery.QueryRepository.listOf(QueryRepository.java:31)

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

==>  Preparing: select id, name, status, birth_at, mobile from t_user WHERE ( id > ? ) limit 10
==> Parameters: 0(Long)
<==      Total: 10
【SET_LIMIT】result size is 10 more than 10, please find and fix, mapper is org.apache.ibatis.binding.MapperProxy@697a92af param is QueryByIdGreaterWithMaxResult(startUserId=0)

3. 设计&扩展

3.1. 核心设计

核心设计，主要是将输入的 Query 对象转换为 Example，整体流程如下：

SingelQuery-MyBatis

核心流程如下：

1. ExampleConverter 将输入的 Query Object 转换为 XXXExample 实例；
2. 使用 XXXExample 实例 调用 XXXMapper 的 selectByExample 方法获取返回值；
3. 返回值通过 ResultConverter 将 Entity 转换为最终结果；

其中，从 QueryObject 到 Example 实例的转换为框架的核心，主要包括如下几部分：

1. Pageable。从 QueryObject 中读取 Pageable 属性，并设置 Example 对象的 offset 和 rows 属性；
2. Sort。从 QueryObject 中读取 Sort 属性，并设置 Example 对象的 orderByClause 属性；
3. 过滤注解。遍历 QueryObject 中属性，根据注解查找到注解处理器，由注解处理器为 Example 添加 Criteria，以进行数据过滤；

3.2. 功能扩展

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

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

1. 自定义注解；
2. 编写注解处理器；
3. 将注解处理器注册为 Spring Bean；

我们以 @FieldEqualTo 为例，如下：

3.2.1. 新增注解 @FieldEqualTo

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

1. @Target({ElementType.FIELD}) 说明注解应用于 字段；
2. @Retention(RetentionPolicy.RUNTIME) 说明注解适用于运行时阶段，这样在运行时通过反射便可读取出来；
3. String value() 用于配置应用字段；

3.2.2. 实现 FieldEqualToHandler

FieldEqualToHandler 类集成自 AbstractFilterAnnotationHandler，实现 FieldAnnotationHandler接口，具体如下：

public class FieldEqualToHandler
        extends AbstractFilterAnnotationHandler<FieldEqualTo>
        implements FieldAnnotationHandler<FieldEqualTo> {
    public FieldEqualToHandler() {
        super(FieldEqualTo.class);
    }
    @Override
    public void addCriteria(Object criteria, FieldEqualTo fieldEqualTo, Object value) throws Exception{
        addCriteria(criteria, fieldEqualTo.value(), "EqualTo", value);
    }
    @Override
    public Method getCriteriaMethod(Class criteriaCls, FieldEqualTo fieldEqualTo, Class valueCls) throws Exception {
        return getCriteriaMethod(criteriaCls, fieldEqualTo.value(), "EqualTo", valueCls);
    }
}

其中，FieldAnnotationHandler 接口定义如下：

public interface FieldAnnotationHandler<A extends Annotation> {
    /**
     * 是否能支持 A 注解
     * @param a
     * @return
     */
    boolean support(A a);
    /**
     * 读取数据，并添加 Criteria 条件
     * @param criteria criteria 对象
     * @param a 注解
     * @param value 字段值
     * @throws Exception
     */
    void addCriteria(Object criteria, A a, Object value) throws Exception;
    /**
     * 获取 CriteriaMethod，用于判断配置是否生效
     * @param criteriaCls criteria类型信息
     * @param a 注解
     * @param valueCls 字段值类型
     * @return
     * @throws Exception
     */
    Method getCriteriaMethod(Class criteriaCls, A a, Class valueCls) throws Exception;
}

3.2.3. 将 FieldEqualToHandler 注册为 Spring Bean

@Bean
public FieldEqualToHandler fieldEqualToHandler(){
    return new FieldEqualToHandler();
}

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

4. 项目信息

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

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