通用 Mapper 4.0.0 版本发布

绝地灬酷狼 2022-05-29 06:14 248阅读 0赞

通用 Mapper4 是一个可以实现任意 MyBatis 通用方法的框架，项目提供了常规的增删改查操作以及Example 相关的单表操作。通用 Mapper 是为了解决 MyBatis 使用中 90% 的基本操作，使用它可以很方便的进行开发，可以节省开发人员大量的时间。

> 项目地址：  
> [https://gitee.com/free/Mapper][https_gitee.com_free_Mapper]  
> [https://github.com/abel533/Mapper][https_github.com_abel533_Mapper]

## 4.0 更新日志 ##

此次更新最大的变化是项目结构调整了，将原来的 mapper 拆分成了 core, base, extra, generator, spring 五个子模块，将独立的 mapper-weekend 和 spring-boot-starter 项目添加到 mapper 中作为两个子项目，拆分后的整个项目如下：

*  all - 为了方便开发人员使用，屏蔽模块细节，提供的整合，下面两个子模块是具体实现，具体包含了 core, base, extra, generator, spring, weekend 六个项目。  
    
    
     *  dependencies - 以依赖方式整合，包含 tk.mybatis:mapper 的完整功能。
     *  mapper - 通过 maven-shade-plugin 打包整合，和原来的 tk.mybatis:mapper 完全一样，并且 Maven 坐标就是 tk.mybatis:mapper。
 *  base - 所有 `Mapper<T>` 等接口的实现，独立出来后方便整体替换这部分实现。
 *  core - 通用 Mapper 的核心，依赖 core 可以实现自己的通用方法，base 就是以此为依赖的一种实现。
 *  extra - base 方法扩展，提供有局限性的通用接口。
 *  generator - 代码生成器，包含了通用 Mapper 代码生成器和一个通用的全功能代码生成器插件。
 *  spring - 通用 Mapper 和 Spring 集成需要的关键类，重写了 MyBatis 几个实现类。
 *  spring-boot-starter - 通用 Mapper 和 Spring Boot 集成。
 *  weekend - 基于 Java8 方法引用的 Example 替代对象 Weekend，可以避免字符串形式的字段名。

除了上面的模块外，mapper 下面还有一个 wiki 目录，该目录是对 wiki 仓库的引用，wiki 的两个仓库分别如下：

*  [https://gitee.com/free/Mapper/wikis/Home][https_gitee.com_free_Mapper_wikis_Home]
 *  [https://github.com/abel533/Mapper/wiki][https_github.com_abel533_Mapper_wiki]

此外，项目中各个模块的父依赖为 mapper-parent 项目：

*  [https://github.com/abel533/mapper-parent][https_github.com_abel533_mapper-parent]

### 全新文档 ###

#### Wiki 地址 ####

*  [https://gitee.com/free/Mapper/wikis/Home][https_gitee.com_free_Mapper_wikis_Home]
 *  [https://github.com/abel533/Mapper/wiki][https_github.com_abel533_Mapper_wiki]

#### Wiki 目录 ####

1.  [集成通用 Mapper][Mapper]  
    
    
     *  [1.1 Java 编码方式][1.1 Java]
     *  [1.2 和 Spring 集成][1.2 _ Spring]
     *  [1.3 和 Spring Boot 集成][1.3 _ Spring Boot]
2.  [对象关系映射][Link 1]  
    
    
     *  [2.1 简单示例][2.1]
     *  [2.2 数据库映射][2.2]
     *  [2.3 主键策略][2.3]
     *  [2.4 乐观锁][2.4]
3.  [配置介绍][Link 2]
4.  代码生成器  
    
    
     *  [4.1 专用代码生成器][4.1]
     *  [4.2 通用代码生成器][4.2]
5.  [扩展通用接口][Link 3]
6.  [Example 用法][Example]
7.  其他配置和用法  
    
    
     *  [7.1 二级缓存配置][7.1]
     *  [7.2 TypeHandler 用法][7.2 TypeHandler]
8.  [常见问题][Link 4]
9.  [更新日志][Link 5]

### 新增功能和参数 ###

1.  增加 `@RegisterMapper` 自动注册 Mapper 接口标记
    
    通用 Mapper 所有已有方法都增加了该注解，MapperHelper 中实现对该注解的检测和自动配置。
    
    实现自己的基类接口时也可以自己添加，例如：
    
        @RegisterMapper
        public interface MyMapper<T> extends Mapper<T> { 
        
        }
    
    增加该注解后会自动注册该接口到通用 Mapper（不需要配置 `mappers` 参数指定该接口了）。
    
    > 即使不增加该接口，如果只用到了通用 Mapper 提供的方法，也可以自动注册，通用 Mapper 会自动向上查找带有该注解的父接口。
    > 
    > 如果是自己开发的通用方法，建议加上该注解，否则还需要自己配置 mappers 参数。
2.  增加 `@KeySql` 注解，用于配置主键策略，替换 JPA 中的复杂用法，可以查看 [2.3 主键策略][2.3] 了解详细用法。
3.  增加 `resolveClass` 参数，可以配置 `EntityResolve` 接口的实现类，可以替换默认转换 entity 到 table 的过程，替换后原来支持的一些配置会失效。
4.  当特殊类型的字段标记 `@Column` 或 `@ColumnType` 注解时，可以作为表字段进行使用（例如枚举，复杂类型，需要配合 TypeHandler）。
5.  `EntityColumn` 增加 blob 属性，给 WithBLOBs 系列方法做准备。
6.  增加参数 `usePrimitiveType`，配置为 `true` 后，简单类型会包含 8 种基本类型。
7.  引入 MyBatis 中的 Log 接口，方便记录更多的操作信息。
8.  增加 `safeDelete` 参数，配置为 `true` 后，`delete` 和 `deleteByExample` 都必须设置查询条件才能删除，否则会抛出异常（`org.apache.ibatis.exceptions.PersistenceException`）。
9.  增加 `safeUpdate` 参数，配置为 `true` 后，`updateByExample` 和 `updateByExampleSelective` 都必须设置查询条件才能更新，否则会抛出异常（`org.apache.ibatis.exceptions.PersistenceException`）。常用的两个 `updateByPrimaryKey` 和 `updateByPrimaryKeySelective` 由于要求必须使用主键，不存在这个问题。
10. 增加 `useJavaType` 参数，设置 `true` 时如`{id, javaType=java.lang.Long}`，对于使用 `User extends Pk<Long>` 形式时，需要设置，否则 mybatis 低版本(<3.4.0) 无法识别类型。

> 新增的参数可以参考 [配置介绍][Link 2]。

### 完善和修复问题 ###

*  解决使用 Config 对象配置通用 Mapper 时，部分参数不起作用的问题
 *  添加完善 `@ColumnType` 注解的测试用例
 *  添加完善 `Id,Table,Column` 三个注解的测试
 *  增加全面的 `TypeHandler` 测试。
 *  update 上面的 `@Options` 注解在 3.2.x 版本时会影响清空二级缓存，已经去掉该注解。
 *  兼容 Spring Boot 2.0.0-RELEASE 版本。

### 移除的功能或参数 ###

*  移除 UUID 参数，不再支持 OGNL 方式对主键设置 UUID，如果有需要请通过 SQL 方式。
 *  移除对 `@SequenceGenerator` 注解的支持，IDENTITY 参数去掉了该注解提供的序列名，现在支持3个参数，顺序为列名(`{0}`)、属性名(`{1}`)、表名(`{2}`)。

### 项目升级 ###

只需要升级版本号，例如通用 Mapper：

<dependency>
        <groupId>tk.mybatis</groupId>
        <artifactId>mapper</artifactId>
        <version>4.0.0</version>
    </dependency>

使用 Spring Boot 时：

<dependency>
        <groupId>tk.mybatis</groupId>
        <artifactId>mapper-spring-boot-starter</artifactId>
        <version>2.0.0</version>
    </dependency>

虽然项目拆分了，但是在项目打包发布上屏蔽了这些细节。

后续如果想要更深入的定制，还可以按下面的方式引入依赖：

<dependency>
      <groupId>tk.mybatis</groupId>
      <artifactId>mapper-core</artifactId>
      <version>${mapper-core.version}</version>
    </dependency>
    
    
    <dependency>
      <groupId>tk.mybatis</groupId>
      <artifactId>mapper-base</artifactId>
      <version>${mapper-base.version}</version>
    </dependency>
    
    <dependency>
      <groupId>tk.mybatis</groupId>
      <artifactId>mapper-extra</artifactId>
      <version>${mapper-extra.version}</version>
    </dependency>
    
    <dependency>
      <groupId>tk.mybatis</groupId>
      <artifactId>mapper-weekend</artifactId>
      <version>${mapper-weekend.version}</version>
    </dependency>
    
    <dependency>
      <groupId>tk.mybatis</groupId>
      <artifactId>mapper-generator</artifactId>
      <version>${mapper-generator.version}</version>
    </dependency>
    
    <dependency>
      <groupId>tk.mybatis</groupId>
      <artifactId>mapper-spring</artifactId>
      <version>${mapper-spring.version}</version>
    </dependency>
    
    <dependency>
        <groupId>tk.mybatis</groupId>
        <artifactId>mapper-spring-boot-starter</artifactId>
        <version>${mapper-starter.version}</version>
    </dependency>

以后会提供稍微复杂的示例，比如增加一个 `mapper-base` 的替代，用于实现下面这种类型的接口定义：

public interface Mapper<T, P, E> extends xxx,xxx { }

其中 `T,P,E` 分别代表实体类类型，主键类型，Example 对象类型。

[https_gitee.com_free_Mapper]: https://gitee.com/free/Mapper
[https_github.com_abel533_Mapper]: https://github.com/abel533/Mapper
[https_gitee.com_free_Mapper_wikis_Home]: https://gitee.com/free/Mapper/wikis/Home
[https_github.com_abel533_Mapper_wiki]: https://github.com/abel533/Mapper/wiki
[https_github.com_abel533_mapper-parent]: https://github.com/abel533/mapper-parent
[Mapper]: https://github.com/abel533/Mapper/wiki/1.integration
[1.1 Java]: https://github.com/abel533/Mapper/wiki/1.1-java
[1.2 _ Spring]: https://github.com/abel533/Mapper/wiki/1.2-spring
[1.3 _ Spring Boot]: https://github.com/abel533/Mapper/wiki/1.3-spring-boot
[Link 1]: https://github.com/abel533/Mapper/wiki/2.orm
[2.1]: https://github.com/abel533/Mapper/wiki/2.1-simple
[2.2]: https://github.com/abel533/Mapper/wiki/2.2-mapping
[2.3]: https://github.com/abel533/Mapper/wiki/2.3-generatedvalue
[2.4]: https://github.com/abel533/Mapper/wiki/2.4-version
[Link 2]: https://github.com/abel533/Mapper/wiki/3.config
[4.1]: https://github.com/abel533/Mapper/wiki/4.1.mappergenerator
[4.2]: https://github.com/abel533/Mapper/wiki/4.2.codegenerator
[Link 3]: https://github.com/abel533/Mapper/wiki/5.extend
[Example]: https://github.com/abel533/Mapper/wiki/6.example
[7.1]: https://github.com/abel533/Mapper/wiki/7.1.cache
[7.2 TypeHandler]: https://github.com/abel533/Mapper/wiki/7.2.typehandler
[Link 4]: https://github.com/abel533/Mapper/wiki/faq
[Link 5]: https://github.com/abel533/Mapper/wiki/changelog