easy-mybatis是一个对Mybatis的增强框架（插件）。在Spring集成Mybatis的基础上，将项目开发中对数据库的常用操作统一化。使用本框架可以很便捷的对数据库进行操作，提高开发效率，减少机械行为。

更便捷的Mybatis插件——EasyMybatis_ORM

easy-mybatis

​​项目主页​​：https://mybatis.zuoyu.top​

​API文档地址​​：https://mybatis.zuoyu.top/doc/index.html​

​GitHub地址​​：https://github.com/zuoyuip/easy-mybatis​

​Gitee地址​​：https://gitee.com/zuoyuip/easy-mybatis Maven依赖引入

<!-- https://mvnrepository.com/artifact/top.zuoyu.mybatis/easy-mybatis-spring-boot-starter -->
<dependency>
    <groupId>top.zuoyu.mybatis</groupId>
    <artifactId>easy-mybatis-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle依赖引入

// https://mvnrepository.com/artifact/top.zuoyu.mybatis/easy-mybatis-spring-boot-starter
implementation 'top.zuoyu.mybatis:easy-mybatis-spring-boot-starter:1.0.0'

框架初衷

这个框架的初衷是，减少Java程序员千篇一律的数据库操作。

对于开发人员来说：

  • 精力应该花费在业务逻辑上，而非机械式的“技术”上。
  • 项目中减少无关痛痒的代码，从抽象的角度看实现。
  • 各司其职，各劳其力，追求项目角度的服务流水线。

服务分离的时代

如今已很难看到单体架构的项目（感兴趣的可以查看我对架构演变的描述​​《浅谈微服务》​​），目前的项目大都是通过​​RESTful​​、​​MQ​​、​​Socket​​的方式（协议）进行数据传输。这让我开始质疑传统​


​JavaWeb​​项目中的数据库操作模式——即​​Model(DTO)​​存在的意义。理论上，数据库设计是不可能完全遵循视图模型的，这就导致“正确”的做法是在项目中引入​​VO​​，由多个​​DTO​​来组装。

那么，为什么不能用灵活的Map来替代呢？

对一个​​Map​​的方法进行拓展，增加其对​​Json​​的解析能力，那么是不是就可以摆脱​​POJO​​的各种麻烦组装。

思考框架设计

我在思考如何设计这个框架的时候，被需要考虑的方方面面给阻挡住了。 因为一个数据库框架需要考虑的东西实在太多了，比如：

  1. 事务机制
  2. 类型转换
  3. 会话管理

··· 思来想去，发现自己方向跑偏了，我只是希望统一数据库操作的接口 + 摆脱Model，没必要重新平地起墙，完全可以在一个现有的框架基础上进行封装。 那么，对这个现有框架的选择就尤为重要了。

现有框架的选择

目前Java中主流的数据库操作框架：

  • Spring JDBC
  • Spring Data JPA
  • Mybatis
  • Hibernate

选择现有框架有一个原则——“统一数据库操作的接口 + 摆脱Model”是对该框架的加强，而非变异；不能因为“统一数据库操作的接口 + 摆脱Model”而无法使用原框架的部分功能。“


摆脱Model”这个特点，首先就要排除重度​​ORM​​框架，也就是支持​​JPA​​操作的数据库——​​Spring Data JPA​​、​​Hibernate​​；原因很简单，这两个框架的强大之处恰恰就在它完全面向​​Model​​操作。剩下的就只有两个框架了，​


​Spring JDBC​​和​​Mybatis​​。其中，​​Spring JDBC​​留给了开发人员大量的可操作空间，更加自由，但恰恰是这种自由使得它更加繁琐。而​​Mybatis​​是一个轻量​​ORM​​框架，准确来说​​Mybatis​​不能称为​​ORM​​框架，因为它并不是面向​​Model​​操作数据库，仅仅是将数据库字段与​​Model​​字段互相赋值，并没有做到​​ORM​​定义的关系映射。

抉择

由以上各框架的特点，结合国内Java语言中数据库操作框架的热度，毫无疑问的选择了​​Mybatis​​。考虑到​


​SpringBoot​​对​​Mybatis​​优秀的支持级别，我决定基于​​mybatis-spring-boot-starter​​开发这款框架，准备来说应该称其为“插件”。

框架特性

  • 更便捷

摒弃传统​​mybatis​​的​​model​​、​​xml​​、​​dao​​数据库操作模式，避繁就简，快速开发。

  • 更高效

采用预编译​​SQL​​，拒绝运行期间反射生成​​SQL​​，性能更高效。

  • 无侵入

只是对Mybatis-Spring的增强插件，对已有工程不做任何修改，仍可使用原生框架的功能，仅仅是简化了开发阶段对数据库的操作。

  • 统一操作接口

对数据库的所有操作共用一个接口，降低使用门槛，轻松操作数据库。

  • 统一操作对象

使用​​JsonObject​​为数据对象，提供一系列操作方法，方便从持久化对象组装为视图对象。

  • 易上手

整个框架只提供了一个接口、一个注解、两个对象，仅仅一行配置便可完成对数据库进行常用操作。

  • ...

安利

  • 在​​mybatis-spring-boot​​环境下，使用该框架（插件），可以减少传统​​Mybatis​​使用中对​​model​​、​​xml​​、​​dao​​的机械式开发。
  • 所有的数据库操作均使用​​MapperRepository​​接口，通过注解​​@Magic("xxx")​​标记接口的数据表归属，即可直接使用。
  • 该框架（插件）不妨碍同时使用传统​​Mybatis​​中​​model​​、​​xml​​、​​dao​​的数据库开发方式。

快速上手

安装

  • 安装​​mybatis-spring-boot​​​环境

mybatis-spring-boot的Maven依赖

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>${spring-boot.version}</version>
        <relativePath/>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>${mybatis-spring-boot.version}</version>
        </dependency>
    </dependencies>

mybatis-spring-boot的Gradle依赖

    plugins {
    id 'org.springframework.boot' version '${springBootVersion}'
    id 'io.spring.dependency-management' version '${springManagementVersion}'
    id 'java'
    }

    dependencies {
    implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:${mybatisSpringVersion}'
    }
  • 安装本框架（插件）

Maven依赖引入

<!-- https://mvnrepository.com/artifact/top.zuoyu.mybatis/easy-mybatis-spring-boot-starter -->
<dependency>
    <groupId>top.zuoyu.mybatis</groupId>
    <artifactId>easy-mybatis-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle依赖引入

// https://mvnrepository.com/artifact/top.zuoyu.mybatis/easy-mybatis-spring-boot-starter
implementation 'top.zuoyu.mybatis:easy-mybatis-spring-boot-starter:1.0.0'

配置

这里以​​MySQL​​数据库为例，​​Oracle​​数据库配置请参考配置说明

  1. 配置​​spring-boot-jdbc​​​数据库
spring:
  datasource:
    type: com.zaxxer.hikari.HikariDataSource
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://172.0.0.1:3306/xxxx
    username: xxxx
    password: xxxx

关于​​springBoot​​的配置，这里不多赘述，更多移步​​springBoot官网​​。

  1. 配置​​easy-mybatis​​​支持的表名（例子）
easy-mybatis:
  table-names: teacher, student

这里的​​table-names​​配置，表示需要​​easy-mybatis​​框架支持的数据表名，多个表名使用逗号隔开。即可使用​


​easy-mybatis​​框架操作​​teacher​​和​​student​​两个数据表，如果需要支持其他数据表，需要在此配置。

操作数据库（例子）

@SpringBootTest
class DemoApplicationTests {

    // 表示该接口用来操作名称为'teacher'的数据表
    @Magic("teacher")
    private MapperRepository teacherRepository;

    // 表示该接口用来操作名称为'student'的数据表
    @Magic("student")
    private MapperRepository studentRepository;


    // 查询teacher表下所有数据
    @Test
    void teacherTest() {
        teachertRepository.selectList().forEach(System.out::println);
    }

    // 查询student表下符合特定条件的数据
    @Test
    void studentTest() {
        studentRepository.selectListByExample(
          new JsonObject().put("birthday", "2009/12/12 12:12:12")
          ).forEach(System.out::println);
    }

}

使用​​MapperRepository​​接口对数据库进行操作，需要使用​​@Magic("表名称")​​标记该接口的数据表归属。在本例中，​


​@Magic("teacher")​​表示该​​MapperRepository​​为​​"teacher"​​数据表的操作接口，可以通过​​teacherRepository​​调用一系列方法完成对​​"teacher"​​数据表的操作。

配置说明

该框架（插件）的全部相关配置

#easy-mybatis的相关配置
easy-mybatis:
  #表示需要载入的数据库表
  table-names: SYS_USER, SYS_DEPT
  #默认的日期字符串格式
  data-format: yyyy-MM-dd HH:mm:ss
  #当数据库为Oracle时，数据表对应的主键SEQ名称
  sequences:
    SYS_USER: SEQ_SYS_USER,
    SYS_DEPT: SEQ_SYS_DEPT
  #当数据库为Oracle时，数据表的日期类型字段格式
  oracle-date-format: yyyy-mm-dd hh24:mi:ss

详细说明

  1. ​​table-names​​

此配置表示需要载入的数据表，多个表名由逗号隔开，只有在此处配置了的数据表，才能在项目中使用​​@Magic("表名称")​​标记​​MapperRepository​​接口的数据表归属。

  1. ​​data-format​​

此配置表示在​​JsonObject​​中的日期存在格式，​​JsonObject​​中对日期的存储类型为​​String​​类型，可通过此配置自定义存储格式，默认格式为​​yyyy-MM-dd HH:mm:ss​​。

注意

当​​data-format​​的格式修改，请务必将​​oracle-date-format​​的格式与之匹配。

  1. ​​sequences​​

此配置表示当数据库为Oracle时，每个数据表的主键生成器名称，以键值对的格式进行参数配置。若此处没有对数据表的主键生成器进行配置，那么在做该数据表的数据插入行为时需自定义填充主键数值。

  1. ​​oracle-date-format​​

此配置表示当数据库为Oracle时，传入日期格式字段时的参数格式，即​​TO_DATE(field, '$dateFormat')​​。

注意

当​​oracle-date-format​​的格式修改，请务必将​​data-format​​的格式与之匹配。

操作接口约定

本框架（插件）的数据库操作唯一接口——​​top.zuoyu.mybatis.service.MapperRepository​​。

  1. 以​​ByExample​​​为结尾的方法

此类是根据​​JsonObject​​类型的参数​​example​​中键值对，对符合要求的数据进行操作，例如：

    // 构建example，这里指字段"birthday"为"2009/12/12 12:12:12"
    JsonObject example = new JsonObject().put("birthday", "2009/12/12 12:12:12");
    // 查询所有字段"birthday"为"2009/12/12 12:12:12"的学生数据
    List<JsonObject> studentList = studentRepository.selectListByExample(example);

这里的​​selectListByExample​​方法就是根据参数​​example​​中键值对查找符合要求的数据。同理， ​


​countByExample​​方法就是获取符合参数​​example​​中键值对的数据总量...

  1. 以​​By​​​为结尾的方法

此类是根据​​String​​类型的参数​​suffixSql​​对方法追加参数中SQL语句的内容，例如：

    // 查找"is_delete"字段为0的数据，并以年龄进行排序
    List<JsonObject> teachers = teacherRepository.selectListBy("WHERE is_delete = 0 ORDER BY age");

    // 将"birthday"字段大于"1990/1/1 00:00:00"的数据，"salary"字段改为20000。 （也就是出生日期在1990年之前的老师，工资改为2W）
    JsonObject example = new JsonObject().put("salary", 20000);
    int count = teacherRepository.updateBy(example, "WHERE birthday < '1990/1/1 00:00:00'");

这里的​​selectListBy​​方法就是查找出符合参数中SQL语句要求的内容，​​updateBy​​方法就是将符合参数中SQL语句要求的数据修改为​​example​​定义的数值。同理，​


​countBy​​方法就是获取符合参数中SQL语句要求的数据总量...

  1. ​​insert​​​、​​insertBatch​​方法

当数据库为MySQL时，如果数据表主键自增，则无需定义主键数值；若主键为非自增，则需定义主键数值。 当数据库为Oracle时，如果在配置中定义了数据表的主键生成器，则无需定义主键数值；反之，则需定义主键数值。

  • ​​MapperRepository​​提供了丰富的方法，以方便对数据库的CURD操作，更多关于​​MapperRepository​​的使用说明请移步MapperRepository说明、​​MapperRepository的API文档​​。

操作对象约定

数据库接口的操作对象主要为​​JsonObject​​类型和​​JsonArray​​类型。

  1. 其中​​top.zuoyu.mybatis.json.JsonObject​​​为键值对容器，以键值的形式装载，数据结构为：
{
    'field1' : 'value1',
    'field2' : 'value2',
    'field3' : 'value3',
    ...
}

键的类型为​​java.lang.String​​类型，值的类型可以为任何类型。​


​JsonObject​​提供了丰富的方法，以方便操作键值对和类型转换，更多关于​​JsonObject​​的使用说明请移步JsonObject说明、​​JsonObject的API文档​​。

  1. 其中​​top.zuoyu.mybatis.json.JsonArray​​​为数组容器，以多个单位的形式装载，数据结构为：
[
    object1,
    object2,
    object3,
    ...
]

每个单位可以为任何类型，且各单位类型允许与其他单位类型不同。 ​​JsonArray​​提供了丰富的方法，以方便操作键值对和类型转换，更多关于​​JsonArray​​的使用说明请移步JsonArray说明、​​JsonArray的API文档​​。

具体方法可参考​​API文档​​。

MapperRepository说明

查询所有​​selectList​​

    /**
     * 查询所有
     *
     * @return 所有数据
     */
    List<JsonObject> selectList();

查询符合样例的数据​​selectListByExample​​

    /**
     * 根据已有键值查询
     *
     * @param example - 已有键值
     * @return 符合要求的数据集合
     */
    List<JsonObject> selectListByExample(JsonObject example);

根据主键查询唯一对象​​selectByPrimaryKey​​

    /**
     * 根据主键查询唯一对象
     *
     * @param primaryKey - 主键
     * @return 唯一对象
     */
    JsonObject selectByPrimaryKey(Serializable primaryKey);

查询符合条件的数据​​selectListBy​​

    /**
     * 查询符合条件的数据
     *
     * @param suffixSql - 条件语句（例如：where field = xxx）
     * @return 数据数量
     */
    List<JsonObject> selectListBy(String suffixSql);

查询特定的字段或结果​​selectFields​​

    /**
     * 查询特定的字段或结果
     * （例如："fieldA, fieldB, fieldC"）
     * （例如："COUNT(field)"）
     *
     * @param fields - 特定的字段或结果
     * @return 特定的字段或结果
     */
    JsonArray selectFields(String fields);

根据样例查询特定的字段或结果​​selectFieldsByExample​​

    /**
     * 根据已有键值查询特定的字段或结果
     * （例如："fieldA, fieldB, fieldC"）
     * （例如："COUNT(field)"）
     *
     * @param fields  - 特定的字段或结果
     * @param example - 已有键值
     * @return 特定的字段或结果
     */
    JsonArray selectFieldsByExample(String fields, JsonObject example);

根据主键查询特定的字段或结果​​selectFieldsByPrimaryKey​​

    /**
     * 根据主键查询特定的字段或结果
     *
     * @param fields     - 特定的字段或结果（例如："fieldA, fieldB, fieldC"）
     * @param primaryKey - 主键
     * @return 特定的字段或结果
     */
    JsonArray selectFieldsByPrimaryKey(String fields, Serializable primaryKey);

根据主键集合查询特定的字段或结果​​selectFieldsByPrimaryKeys​​

    /**
     * 根据主键集合查询特定的字段或结果
     *
     * @param fields      - 特定的字段或结果（例如："fieldA, fieldB, fieldC"）
     * @param primaryKeys - 主键集合
     * @return 特定的字段或结果
     */
    JsonArray selectFieldsByPrimaryKeys(String fields, Serializable[] primaryKeys);

查询符合条件的数据​​selectFieldsBy​​

    /**
     * 查询符合条件的数据
     *
     * @param fields    - 特定的字段或结果（例如："fieldA, fieldB, fieldC"）
     * @param suffixSql - 条件语句（例如：where field = xxx）
     * @return 特定的字段或结果
     */
    JsonArray selectFieldsBy(String fields, String suffixSql);

查询符合条件的数据数量​​countBy​​

    /**
     * 查询符合条件的数据数量
     *
     * @param suffixSql - 条件语句（例如：where field = xxx）
     * @return 数据数量
     */
    long countBy(String suffixSql);

查询是否存在符合样例的数据数量​​countByExample​​

    /**
     * 根据已有键值查询是否存在符合条件的数据数量
     *
     * @param example - 已有键值
     * @return 数据数量
     */
    long countByExample(JsonObject example);

是否存在符合条件的数据​​existsBy​​

    /**
     * 是否存在符合条件的数据
     *
     * @param suffixSql - 条件语句（例如：where field = xxx）
     * @return 是否存在
     */
    boolean existsBy(String suffixSql);

是否存在符合样例的数据​​existsByExample​​

    /**
     * 根据已有键值查询是否存在符合条件的数据
     *
     * @param example - 已有键值
     * @return 是否存在
     */
    boolean existsByExample(JsonObject example);

新增对象​​insert​​

    /**
     * 新增对象
     *
     * @param jsonObject - 对象键值
     * @return 变动数据的数量
     */
    int insert(JsonObject jsonObject);

批量新增对象​​insertBatch​​

    /**
     * 批量新增对象
     *
     * @param jsonObjects - 对象键值集合
     * @return 变动数据的数量
     */
    int insertBatch(List<JsonObject> jsonObjects);

根据主键修改对象属性​​updateByPrimaryKey​​

    /**
     * 根据主键修改对象属性
     *
     * @param jsonObject - 包含主键对象键值
     * @return 变动数据的数量
     */
    int updateByPrimaryKey(JsonObject jsonObject);

修改特定条件的对象属性​​updateBy​​

    /**
     * 修改特定条件的对象属性
     *
     * @param jsonObject - 要修改的键值
     * @param suffixSql  - 条件语句（例如：where field = xxx）
     * @return 变动数据的数量
     */
    int updateBy(JsonObject jsonObject, String suffixSql);

批量根据主键修改对象属性​​updateByPrimaryKeyBatch​​

    /**
     * 批量根据主键修改对象属性
     *
     * @param jsonObjects - 对象键值集合
     * @return 变动数据的数量
     */
    int updateByPrimaryKeyBatch(List<JsonObject> jsonObjects);

根据主键删除对象​​deleteByPrimaryKey​​

    /**
     * 根据主键删除对象
     *
     * @param primaryKey - 主键
     * @return 变动数据的数量
     */
    int deleteByPrimaryKey(Serializable primaryKey);

删除符合条件的数据​​deleteBy​​

    /**
     * 删除符合条件的数据
     *
     * @param suffixSql - 条件语句（例如：where field = xxx）
     * @return 变动数据的数量
     */
    int deleteBy(String suffixSql);

批量根据主键删除对象​​deleteByPrimaryKeys​​

    /**
     * 批量根据主键删除对象
     *
     * @param primaryKeys - 主键组
     * @return 变动数据的数量
     */
    int deleteByPrimaryKeys(Serializable[] primaryKeys);

根据样例删除对象​​deleteByExample​​

    /**
     * 根据已有键值删除对象
     *
     * @param example - 已有键值
     * @return 变动数据的数量
     */
    int deleteByExample(JsonObject example);

JsonObject说明

​​top.zuoyu.mybatis.json.JsonObject​​为键值对容器，以键值的形式装载，数据结构为：

{
    'field1' : 'value1',
    'field2' : 'value2',
    'field3' : 'value3',
    ...
}

键的类型为​​java.lang.String​​类型，值的类型可以为任何类型。

类型转换

内部默认已包含常规的类型转换，默认支持以下类型：

  • ​​java.math.BigInteger​​
  • ​​java.math.BigDecimal​​
  • ​​java.lang.Boolean​​
  • ​​java.lang.Byte​​
  • ​​java.lang.Character​​
  • ​​java.util.Date​​
  • ​​java.lang.Double​​
  • ​​java.lang.Float​​
  • ​​java.lang.Integer​​
  • ​​java.lang.Long​​
  • ​​java.lang.Short​​
  • ​​java.lang.String​​

如果默认的转换器无法满足需求，或者需要转换为其他类型，可通过自定义转换器​​ConvertClass​​进行实现，接口方法：

public interface ConvertClass<T> {

    /**
     * 将给定的 value 对象转换为 T 类型
     *
     * @param value - 给定对象
     * @return 目标转换类型的对象
     */
    T convert(Object value);

    /**
     * 将给定的 value 对象转换为 T 类型， 否则返回  defaultValue
     *
     * @param value        - 给定对象
     * @param defaultValue - 默认值
     * @return 目标转换类型的对象
     */
    T convert(Object value, T defaultValue);
}

示例

    @Test
    void convertTest() {
        // 使用JSON字符串初始化对象
        JsonObject student = new JsonObject(studentJSON);

        // 获取学生的性别，如果无法转换则返回"未知"
        String sex = student.getValue("sex", new SexConvert());

        // 获取学生的性别，如果无法转换则返回"未录入"
        String sexOrDefault = student.getValue("sex", new SexConvert(), "未录入");
    }

    static class SexConvert implements ConvertClass<String> {

        @Override
        public String convert(Object value) {
            if (value instanceof Integer) {
                if ((Integer) value == 1) {
                    return "男";
                } else if ((Integer)value == 0) {
                    return "女";
                }
            }
            return "未知";
        }

        @Override
        public String convert(Object value, String defaultValue) {
            if (value instanceof Integer) {
                if ((Integer) value == 1) {
                    return "男";
                } else if ((Integer)value == 0) {
                    return "女";
                }
            }
            return defaultValue;
        }
    }

本示例也可使用​​StringConvert​​转换器，​​StringConvert​​为​​ConvertClass​​的子接口。

也可以通过​​toClass​​​方法，将​​JsonObject​​对象转换为指定类型的实体类。

子接口：

  • ​​BigDecimalConvert​​
  • ​​BigIntegerConvert​​
  • ​​BooleanConvert​​
  • ​​ByteConvert​​
  • ​​CharacterConvert​​
  • ​​DateConvert​​
  • ​​DoubleConvert​​
  • ​​FloatConvert​​
  • ​​IntegerConvert​​
  • ​​LongConvert​​
  • ​​ShortConvert​​
  • ​​StringConvert​​

更多方法请移步​​JsonObject的API文档​​。

JsonArray说明

​​top.zuoyu.mybatis.json.JsonArray​​为数组容器，以多个单位的形式装载，数据结构为：

[
    object1,
    object2,
    object3,
    ...
]

每个单位可以为任何类型，且各单位类型允许与其他单位类型不同。

类型转换

具体使用方法与​​JsonObject​​在类型转换操作一致，参考JsonObject的类型转换操作

更多方法请移步​​JsonArray的API文档​​。

开源地址

​​项目主页​​：https://mybatis.zuoyu.top​

​API文档地址​​：https://mybatis.zuoyu.top/doc/index.html​

​GitHub地址​​：https://github.com/zuoyuip/easy-mybatis​

​Gitee地址​​：https://gitee.com/zuoyuip/easy-mybatis