![]()
2021年8月12日 - 1.0.0 发布了🎉🎉🎉
项目地址：https://mapper.mybatis.io
介绍
这是一个不需要任何配置就可以直接使用的通用 Mapper，通过简单的学习就可以直接在项目中使用。
1.1 主要目标
1. 开箱即用，无需任何配置，继承基类 Mapper 即可获得大量通用方法；
2. 随心所欲，通过复制粘贴的方式可以组建自己的基类 Mapper；
3. 全面贴心，提供 Service 层的封装方便业务使用和理解 Mapper；
4. 简单直观，提供 ActiveRecord 模式，结合 Spring Boot 自动配置直接上手用；
5. 自定义方法，简单几行代码即可实现自定义通用方法；
6. 轻松扩展，通过 Java SPI 轻松扩展。
1.2 系统要求
MyBatis Mapper 要求 MyBatis 最低版本为3.5.1，推荐使用最新版本。
和 MyBatis 框架一样，最低需要 Java 8。
1.3 安装
如果你使用 Maven，在你的 pom.xml 添加下面的依赖：
<dependencies>
<dependency>
<groupId>io.mybatis</groupId>
<artifactId>mybatis-mapper</artifactId>
<version>1.0.1</version>
</dependency>
<!-- TODO 按需选择依赖 -->
<!-- 使用 Service 层封装时 -->
<dependency>
<groupId>io.mybatis</groupId>
<artifactId>mybatis-service</artifactId>
<version>1.0.1</version>
</dependency>
<!-- TODO 按需选择依赖 -->
<!-- 使用 ActiveRecord 模式时 -->
<dependency>
<groupId>io.mybatis</groupId>
<artifactId>mybatis-activerecord</artifactId>
<version>1.0.1</version>
</dependency>
</dependencies>
如果使用 Gradle，在 `build.gradle` 中添加：
dependencies {
compile("io.mybatis:mybatis-mapper:1.0.1")
// 使用 Service 层封装时
compile("io.mybatis:mybatis-service:1.0.1")
// 使用 ActiveRecord 模式时
compile("io.mybatis:mybatis-activerecord:1.0.1")
}
1.4 快速设置
MyBatis Mapper 的基本原理是将实体类映射为数据库中的表和字段信息，因此实体类需要通过注解配置基本的元数据，配置好实体后，只需要创建一个继承基础接口的 Mapper 接口就可以开始使用了。
1.4.1 实体类配置
假设有一个表：
create table user
(
id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 1) PRIMARY KEY,
name VARCHAR(32) DEFAULT 'DEFAULT',
sex VARCHAR(2)
);
对应的实体类：
import io.mybatis.provider.Entity;
@Entity.Table("user")
public class User {
@Entity.Column(id = true)
private Long id;
@Entity.Column("name")
private String username;
@Entity.Column
private String sex;
//省略set和get方法
}
实体类上必须添加@Entity.Table注解指定实体类对应的表名，建议明确指定表名，不提供表名的时候，使用类名作为表名。所有属于表中列的字段，必须添加@Entity.Column注解，不指定列名时，使用字段名（不做任何转换），通过 id=true可以标记字段为主键。
@Entity中包含的这两个注解提供了大量的配置属性，想要使用更多的配置，参考 实体类注解 中的内容，下面是一个简单示例：
@Entity.Table(value = "sys_user", remark = "系统用户", autoResultMap = true)
public class User {
@Entity.Column(id = true, remark = "主键", updatable = false, insertable = false)
private Long id;
@Entity.Column(value = "name", remark = "帐号")
private String userName;
//省略其他
}
1.4.2 Mapper接口定义
有了 User实体后，直接创建一个继承了 Mapper 的接口即可：
//io.mybatis.mapper.Mapper
public interface UserMapper extends Mapper<User, Long> {
}
这个接口只要被 MyBatis 扫描到即可直接使用。
下面是几种常见的扫描配置：
1. MyBatis 自带的配置文件方式 mybatis-config.xml：
<mappers>
<!-- 扫描指定的包 -->
<package name="com.example.mapper"/>
</mappers>
2. Spring 中的 spring.xml 配置：
<bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
<property name="basePackage" value="com.example.mapper"/>
<property name="markerInterface" value="io.mybatis.service.mapper.RoleMarker"/>
<property name="sqlSessionFactoryBeanName" value="sqlSessionFactoryRole"/>
</bean>
3. Spring Boot 配置，启动类注解方式：
@MapperScan(basePackages = "com.example.mapper")
@SpringBootApplication
public class SpringBootDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SpringBootDemoApplication.class, args);
}
}
Spring Boot 中，还可以直接给接口添加 @org.apache.ibatis.annotations.Mapper 注解，增加注解后可以省略 @MapperScan 配置。
可以注意到上面都是 MyBatis 自己的配置方式，新版 mybatis-mapper 本身不需要任何配置即可使用。
1.4.3 使用
定义好接口后，就可以获取 UserMapper 使用，下面是简单示例：
User user = new User();
user.setUserName("测试");
userMapper.insert(user);
//保存后自增id回写，不为空
Assert.assertNotNull(user.getId());
//根据id查询
user = userMapper.selectByPrimaryKey(user.getId());
//删除
Assert.assertEquals(1, userMapper.deleteByPrimaryKey(user.getId()));
看到这里，可以发现除了 MyBatis 自身的配置外，MyBatis Mapper 只需要配置实体类注解，
创建对应的 Mapper 接口就可以直接使用，没有任何繁琐的配置。
上面的示例只是简单的使用了 MyBatis Mapper，还有很多开箱即用的功能没有涉及，
建议在上述示例运行成功后，继续查看本项目其他模块的详细文档，熟悉各部分文档后，
在使用 MyBatis Mapper 时会更得心应手，随心所欲。
更多用法可以通过 https://mapper.mybatis.io 进行了解。
#开发过程
2014年11月开源的 tk.mybatis.mapper 算得上是 MyBatis 的一个重要里程碑，从 通用Mapper 开始， MyBatis 有了真正意义上的通用 DAO 层，增删改查真的不用在手写或者自动生成，极大的方便了开发人员。
通用Mapper 经历过几次大的重构，每次都从底层使用新的思路重新实现，从第一个版本发布到2020年发布的 4.1.5 版本， 一直是兼容性升级，虽然底层变化了很多，集成方式有了变化，但是业务上集成的接口一直兼容。
虽然经历了几次大的重构，但是由于MyBatis内部的机制，导致无法以更方便更简洁的形式来实现通用Mapper， 从2018年就一直想要从根去解决这个问题，在 2019年3月份给 MyBatis 提交的 pr#1391合并后（对应 3.5.1 版本，最低要求版本）， 终于能以更简单的方式来实现通用 Mapper 了。
2019年实现过一版新的通用Mapper，但是感觉不够好。2020年本来是要写新一版的《MyBatis 从入门到精通》的， 写的过程中也在想着如何把通用Mapper结合到书中，在写书的过程中，逐渐形成了一个新的思路， 结果把目标从写书转移到了开源项目（不务正业），由于工作经常 996， 直到2020年底才基本完成新的实现。本来计划在2021年1月份发布正式版， 为了提供一个更灵活的代码生成器（Mybatis 的 MBG太死板，扩展麻烦）， 工作重心又转移到了代码生成器，最终实现了一个代码简单， 功能却异常强大的代码生成器 睿Rui（没开源，作为工具包含在当前项目中直接使用）， 此时又过去了好几个月，想着在2021年中发布正式版， 为了尝试在新版本中尽可能通过扩展 100% 兼容 tk-mapper，又增加了一些 SPI 扩展接口。 结果一直拖到了8月份。直到这个月才把 1.0.0 发布了。
整个项目从构思到最终发布经历了近3年的时间，虽然已经花了无数的时间， 但是仍然不能保证有不完美的地方，项目初期，大家发现BUG或者有任何想法都可以提 issues。
#为什么新版本是 1.0.0？
这是一个全新的版本的，采用了新的包名 io.mybatis，采用了全新的实现，核心代码是独立的 mybatis-provider 项目，在此项目之上形成了 mybaits-mapper ，这个版本不需要任何配置（不会再因为配置出错），可以简单快速的集成并使用。
关于新版本的特点，建议通过 快速上手 进行了解。
2021年8月16日 - 1.0.1 发布了🎉🎉🎉
-
核心项目 mybatis-provider 项目升级到 1.0.1，主要解决一个bug：
当在注解 @Entity.Table(value = "user_auto", autoResultMap = true) 中使用 autoResultMap = true，默认把所有 @SelectProvider 方法的返回值设置为了自动生成的 <resultMap>，这会导致 selectCount 这种返回值不是实体类类型的查询出错，本次更新解决了这个问题。 同时直接使用 mybatis 的方式获取返回值类型，因此支持 mybatis 本身的注解设置返回值类型，例如 @ResultType 注解。
-
mybatis-mapper 项目升级为 1.0.1，主要解决了一个 autoResultMap = true 时相关的问题，当使用 <resultMap> 时， 其中的配置包含了数据库列 column 和 Java 对象属性名 property 的映射关系，因此在 select 查询时， 不需要通过 column As property 方式设置别名，在 Example 和 Fn 的实现中缺少对这种情况的处理， 本次更新已解决该问题。
