4.0.changelog.md

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://github.com/abel533/Mapper/wiki

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

• https://github.com/abel533/mapper-parent

全新文档

Wiki 地址

• https://gitee.com/free/Mapper/wikis/Home
• https://github.com/abel533/Mapper/wiki

Wiki 目录

1. 集成通用 Mapper

   • 1.1 Java 编码方式
   • 1.2 和 Spring 集成
   • 1.3 和 Spring Boot 集成

2. 对象关系映射

   • 2.1 简单示例
   • 2.2 数据库映射
   • 2.3 主键策略
   • 2.4 乐观锁
3. 配置介绍

4. 代码生成器

   • 4.1 专用代码生成器
   • 4.2 通用代码生成器
5. 扩展通用接口
6. Example 用法

7. 其他配置和用法

   • 7.1 二级缓存配置
   • 7.2 TypeHandler 用法
8. 常见问题
9. 更新日志

新增功能和参数

1. 增加 @RegisterMapper 自动注册 Mapper 接口标记
   通用 Mapper 所有已有方法都增加了该注解，MapperHelper 中实现对该注解的检测和自动配置。
   实现自己的基类接口时也可以自己添加，例如： ```java @RegisterMapper public interface MyMapper extends Mapper {

}

<br />增加该注解后会自动注册该接口到通用 Mapper（不需要配置 `mappers` 参数指定该接口了）。
> 即使不增加该接口，如果只用到了通用 Mapper 提供的方法，也可以自动注册，通用 Mapper 会自动向上查找带有该注解的父接口。
> 如果是自己开发的通用方法，建议加上该注解，否则还需要自己配置 mappers 参数。
2. 
增加 `@KeySql` 注解，用于配置主键策略，替换 JPA 中的复杂用法，可以查看 [2.3 主键策略](https://github.com/abel533/Mapper/wiki/2.3-generatedvalue) 了解详细用法。
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) 无法识别类型。
> 新增的参数可以参考 [配置介绍](https://github.com/abel533/Mapper/wiki/3.config)。
<a name="2ae95aea"></a>
### 完善和修复问题
- 解决使用 Config 对象配置通用 Mapper 时，部分参数不起作用的问题
- 添加完善 `@ColumnType` 注解的测试用例
- 添加完善 `Id,Table,Column` 三个注解的测试
- 增加全面的 `TypeHandler` 测试。
- update 上面的 `@Options` 注解在 3.2.x 版本时会影响清空二级缓存，已经去掉该注解。
- 兼容 Spring Boot 2.0.0-RELEASE 版本。
<a name="ed0ce562"></a>
### 移除的功能或参数
- 移除 UUID 参数，不再支持 OGNL 方式对主键设置 UUID，如果有需要请通过 SQL 方式。
- 移除对 `@SequenceGenerator` 注解的支持，IDENTITY 参数去掉了该注解提供的序列名，现在支持3个参数，顺序为列名(`{0}`)、属性名(`{1}`)、表名(`{2}`)。
<a name="60942774"></a>
### 项目升级
只需要升级版本号，例如通用 Mapper：
```xml
<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>
<!-- 如果需要通用 Mapper 自带的 Mapper 接口和系列方法，需要引入本依赖 -->
<!-- 拆分 base 项目的目的在于以后可能会提供其他的方式来实现接口 -->
<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>
<!-- 基于 Java8 方法引用的类 Example 对象 Weekend -->
<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>
<!-- Spring 集成必备 -->
<dependency>
  <groupId>tk.mybatis</groupId>
  <artifactId>mapper-spring</artifactId>
  <version>${mapper-spring.version}</version>
</dependency>
<!-- Spring Boot 自动配置 -->
<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 对象类型。