Mapper Documentation

File: README.md Copy Chapter

MyBatis 通用 Mapper6 来了🎉🎉🎉

通用Mapper都可以极大的方便开发人员。可以随意的按照自己的需要选择通用方法，还可以很方便的开发自己的通用方法。

极其方便的使用MyBatis单表的增删改查。

支持单表操作，不支持通用的多表联合查询。

🌟 赞助支持 Copy Chapter

本项目是基于MIT协议的开源项目，无任何商业盈利，持续的维护、迭代与兼容升级全靠各位开发者和赞助者的支持。

版本匹配说明 Copy Chapter

不同分支支持不同的 Spring Boot 版本，请根据项目实际情况选择对应分支：

基于 JDK 17 + Jakarta JPA 注解 + Spring Boot 4 Copy Chapter

配置完全兼容，需要使用新版本的 JPA 注解，同步更新（copy） mybatis-spring 4.0.0 和 mybatis-spring-boot-starter 4.0.0。

此次更新主要是依赖的更新，适配最新的 Spring Boot 4.0.2，提供更好的兼容性和稳定性。

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

推荐新版本 mybatis-mapper Copy Chapter

如果你要在新项目中使用，可以看看新版本的 mybatis-mapper，完全作为 mybatis 扩展存在，
不修改 mybatis, mybatis-spring, mybatis-spring-boot-starter 任何代码，不需要额外配置，可以快速上手。

• mybatis-mapper: https://github.com/mybatis-mapper/mapper
• mybatis-mapper 文档: https://mapper.mybatis.io
• mybatis-mapper 快速入门

[**快速入门 - MyBatis 为什么需要通用 Mapper ?**](https://blog.csdn.net/isea533/article/details/83045335) Copy Chapter

简介: 在早期项目文档中有过类似主题的内容，但是最近我自己看文档的时候发现一个问题，文档虽然很详细，但是并不适合初次接触的人。为了方便第一次听说，第一次尝试的开发人员了解通用 Mapper，补充此文档。

强烈建议初学者阅读本文，先从整体上了解 通用 Mapper，然后再通过下面的文档更深入的了解。

[**通用 Mapper 进阶实例：为什么好久都没更新了？**](https://blog.csdn.net/isea533/article/details/104776347) Copy Chapter

通过本文，希望读者能有收获，能根据自己的需要设计通用方法，不要只是为了偷懒将自己局限在已有的通用方法中。大而全的通用方法不一定适合自己，根据自己需要选择和设计的通用方法才更满足自己的需要。

项目文档 Copy Chapter

• 文档 - Gitee

• 文档 - GitHub

• JavaDoc

• 更新日志 - Gitee

• 更新日志 - GitHub

微信公众号 Copy Chapter

作者信息 Copy Chapter

MyBatis 工具网站：https://mybatis.io

作者博客：http://blog.csdn.net/isea533 ，http://blog.mybatis.io

作者邮箱：[email protected]

推荐使用Mybatis分页插件：PageHelper分页插件

《MyBatis 从入门到精通》 Copy Chapter

简介 Copy Section

本书中从一个简单的 MyBatis 查询入手，搭建起学习 MyBatis 的基础开发环境。 通过全面的示例代码和测试讲解了在 MyBatis XML 方式和注解方式中进行增、删、改、查操作的基本用法，介绍了动态 SQL
在不同方面的应用以及在使用过程中的最佳实践方案。 针对 MyBatis 高级映射、存储过程和类型处理器提供了丰富的示例，通过自下而上的方法使读者更好地理解和掌握MyBatis 的高级用法，同时针对 MyBatis
的代码生成器提供了详细的配置介绍。 此外，本书还提供了缓存配置、插件开发、Spring、Spring Boot 集成的详细内容。 最后通过介绍 Git 和 GitHub 让读者了解MyBatis 开源项目，通过对 MyBatis
源码和测试用例的讲解让读者更好掌握 MyBatis。

购买地址： Copy Section

• 京东

相关介绍 Copy Section

• CSDN博客：http://blog.csdn.net/isea533/article/details/73555400

• GitHub项目：https://github.com/mybatis-book/book

File: all/mapper/README.md Copy Chapter

Mybatis 通用 Mapper Jar 集成

本项目默认集成了 mapper-core, mapper-extra, mapper-generator, mapper-spring, mapper-weekend 项目。

使用时，只需要添加 mapper 的依赖即可。

<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper</artifactId>
    <version>版本号</version>
</dependency>

引入该依赖时不会引入传递依赖。

File: all/dependencies/README.md Copy Chapter

Mybatis 通用 Mapper Jar 集成

本项目默认集成了 mapper-core, mapper-extra, mapper-generator, mapper-spring, mapper-weekend 项目。

使用时，只需要添加 mapper-all 的依赖即可。

<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper-all-dependencies</artifactId>
    <version>版本号</version>
</dependency>

引入后会自动引入其他依赖。

可以通过在 pom 中增加下面对应的属性来修改依赖的版本号：

<mapper-core.version>4.0.0-SNAPSHOT</mapper-core.version>
    <mapper-extra.version>1.0.0-SNAPSHOT</mapper-extra.version>
    <mapper-spring.version>1.0.0-SNAPSHOT</mapper-spring.version>
    <mapper-weekend.version>1.1.3-SNAPSHOT</mapper-weekend.version>
    <mapper-generator.version>1.0.0-SNAPSHOT</mapper-generator.version>

上面具体版本号只是示例，默认不需要自己设置。

File: all/README.md Copy Chapter

Mybatis 通用 Mapper3 适配

为了帮助用户从通用 Mapper 3.x 过渡到 4.x 和以后的版本，增加本项目。

本项目下面提供了两个子模块，基于 Maven 依赖传递的 dependencies 和基于 maven-shade-plugin 打包为一个大 jar 包的 mapper 项目。

并且本项目下面的 jar 的 Maven 为 tk.mybtis:mapper，也就是从 mapper 3.x 升级到 4.x 的时候可以只改版本号。

File: base/README.md Copy Chapter

Mybatis 通用 Mapper 基础方法实现

File: core/README.md Copy Chapter

MyBatis通用Mapper3

通用Mapper都可以极大的方便开发人员。可以随意的按照自己的需要选择通用方法，还可以很方便的开发自己的通用方法。

极其方便的使用MyBatis单表的增删改查。

支持单表操作，不支持通用的多表联合查询。

新书《MyBatis 从入门到精通》 Copy Chapter

购买地址：京东，当当，亚马逊

CSDN博客：http://blog.csdn.net/isea533/article/details/73555400

GitHub项目：https://github.com/mybatis-book/book

通用 Mapper 支持 Mybatis-3.2.4 及以上版本 Copy Chapter

不是表中字段的属性必须加 `@Transient` 注解 Copy Chapter

Spring DevTools 配置 Copy Chapter

感谢emf1002提供的解决方案。

在使用 DevTools 时，通用Mapper经常会出现 class x.x.A cannot be cast to x.x.A。

同一个类如果使用了不同的类加载器，就会产生这样的错误，所以解决方案就是让通用Mapper和实体类使用相同的类加载器即可。

DevTools 默认会对 IDE 中引入的所有项目使用 restart 类加载器，对于引入的 jar 包使用 base 类加载器，因此只要保证通用Mapper的jar包使用 restart 类加载器即可。

在 src/main/resources 中创建 META-INF 目录，在此目录下添加 spring-devtools.properties 配置，内容如下：

restart.include.mapper=/mapper-[\\w-\\.]+jar
restart.include.pagehelper=/pagehelper-[\\w-\\.]+jar

使用这个配置后，就会使用 restart 类加载加载 include 进去的 jar 包。

项目文档 Copy Chapter

https://mapperhelper.github.io Copy Section

在你打算使用通用 Mapper 前，一定要看看下面的文档，许多人在初次使用时遇到的问题，99% 都在文档中有说明！！

1. 如何集成通用Mapper
2. 如何使用通用Mapper
3. 3.3.0版本新增功能用法文档
4. 根据需要自定义接口
5. Mapper3通用接口大全
6. 扩展通用接口
7. 使用Mapper专用的MyBatis生成器插件
8. 在Spring4中使用通用Mapper
9. Mapper3常见问题和用法

如何让作者为你开发通用方法？ Copy Section

实际上，只要你看看上面的第 6 个文档，你完全可以自己开发出来。

或者你可以通过赞助作者 10~50 元来让作者根据你的需求开发一个通用方法。

赞助后保留截图，将截图和需求内容发邮件到 [email protected] 和作者联系。

你还可以通过开源中国众包购买服务开发 MyBatis 通用 Mapper 通用方法

通用 Mapper - 简单用法示例 Copy Chapter

全部针对单表操作，每个实体类都需要继承通用Mapper接口来获得通用方法。

示例代码：

CountryMapper mapper = sqlSession.getMapper(CountryMapper.class);
//查询全部
List<Country> countryList = mapper.select(new Country());
//总数
Assert.assertEquals(183, countryList.size());

//通用Example查询
Example example = new Example(Country.class);
example.createCriteria().andGreaterThan("id", 100);
countryList = mapper.selectByExample(example);
Assert.assertEquals(83, countryList.size());

//MyBatis-Generator生成的Example查询
CountryExample example2 = new CountryExample();
example2.createCriteria().andIdGreaterThan(100);
countryList = mapper.selectByExample(example2);
Assert.assertEquals(83, countryList.size());

CountryMapper代码如下：

public interface CountryMapper extends Mapper<Country> {
}

这里不说更具体的内容，如果您有兴趣，可以查看下面的项目文档

实体类注解 Copy Chapter

从上面效果来看也能感觉出这是一种类似hibernate的用法，因此也需要实体和表对应起来，因此使用了JPA注解。更详细的内容可以看下面的项目文档。

Country代码：

public class Country {
    @Id
    private Integer id;
    @Column
    private String countryname;
    private String countrycode;
    //省略setter和getter方法
}

使用Mapper专用的MyBatis Generator插件
可以方便的生成这些（带注解的）实体类。

使用 Maven Copy Chapter

<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper</artifactId>
    <version>最新版本</version>
</dependency>

如果你使用 Spring Boot 可以直接引入：

<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper-spring-boot-starter</artifactId>
    <version>最新版本</version>
</dependency>

具体用法可以参考：MyBatis-Spring-Boot

引入 Jar 包，下载地址： Copy Chapter

https://oss.sonatype.org/content/repositories/releases/tk/mybatis/mapper

http://repo1.maven.org/maven2/tk/mybatis/mapper

由于通用Mapper依赖JPA，所以还需要下载persistence-api-1.0.jar：

http://repo1.maven.org/maven2/javax/persistence/persistence-api/1.0/

[更新日志](http://git.oschina.net/free/Mapper/blob/master/wiki/Changelog.md) Copy Chapter

作者信息 Copy Chapter

MyBatis 工具网站:https://mybatis.io

作者博客：http://blog.csdn.net/isea533

作者邮箱： [email protected]

如需加群，请通过 https://mybatis.io 首页按钮加群。

推荐使用Mybatis分页插件:PageHelper分页插件

File: extra/README.md Copy Chapter

Mybatis 通用 Mapper 扩展方法

扩展方法介绍 Copy Chapter

InsertListMapper Copy Section

批量插入

• 支持批量插入的数据库都可以使用，例如 mysql,h2 等

  tk.mybatis.mapper.additional.insert.InsertListMapper

  SQL 形如 insert table(xxx) values (xxx), (xxx) ...

• Oracle特殊批量插入
  tk.mybatis.mapper.additional.dialect.oracle.InsertListMapper

  SQL 形如

  sql Copy

  INSERT ALL
   INTO demo_country ( country_id,country_name,country_code ) VALUES ( ?,?,? )
   INTO demo_country ( country_id,country_name,country_code ) VALUES ( ?,?,? )
   INTO demo_country ( country_id,country_name,country_code ) VALUES ( ?,?,? )
   SELECT 1 FROM DUAL

  由于语法限制，暂不支持序列.

UpdateByPrimaryKeySelectiveForceMapper Copy Section

空字段强制更新

针对UpdateByPrimaryKeySelectiveMapper中， 空值也需要设置的场景提供的解决方案。

参见: https://github.com/abel533/Mapper/issues/133

File: generator/README.md Copy Chapter

Mybatis 通用 Mapper 代码生成器

整个插件只有很少代码是和通用 Mapper 相关的，并且也没有直接的依赖关系。

这个代码生成器实际上是对 MyBatis Generator 的一个扩展，使用这个扩展可以很方便的使用 Freemarker 模板语言编写代码。

测试 Copy Chapter

在 src/test/java 下面，tk.mybatis.mapper.generator 包下面有一个测试类 Generator。

可以直接运行这个测试类查看生成代码的效果。所有生成的代码在 src/test/java/test 目录下，方便删除。

测试使用的 hsqldb 内存数据库，数据库建表 SQL 在 src/test/resources 下面的 CreateDB.sql 中。

代码生成器的配置在 generatorConfig.xml 中。

代码生成器文档

代码生成器是基于 MBG 插件的，所以需要配合 MBG 使用。

一个简单的 MBG 配置如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE generatorConfiguration
        PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
        "http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">

<generatorConfiguration>
    <context id="Mysql" targetRuntime="MyBatis3Simple" defaultModelType="flat">
        
        
        

        
        
            
            
            
            
            
            
            
            
        

        
        
            
            
            
            
            
        

        <jdbcConnection driverClass="org.hsqldb.jdbcDriver"
                                connectionURL="jdbc:hsqldb:mem:generator"
                                userId="sa"
                                password="">
        </jdbcConnection>

        
        <javaModelGenerator targetPackage="test.model" targetProject="./src/test/java"/>

        
    </context>
</generatorConfiguration>

在这个配置中，我们只关注 tk.mybatis.mapper.generator.TemplateFilePlugin。

基于模板的插件 `TemplateFilePlugin` Copy Chapter

这个插件中除了几个必备的属性外，还可以增加任意的属性，属性完全是为了给模板提供数据。

先看一个基本完整的配置：

下面介绍必备的属性。

1. `targetProject` Copy Section

用于指定目标项目，一般是 src/main/java 或者 src/main/resource 这样的目录。 还可以是 src/test/java 或者 src/test/resource 这样的目录。

在多模块项目中，还能通过相对路径指定为其他的目录，例如：

这个属性值有一个要求，就是目录必须存在，否则不会生成代码!

2. `targetPackage` Copy Section

用于指定包的部分，虽然是这个名字，实际上就是路径。

这个属性指定的路径如果不存在，就会自动创建。

这个属性的值可以为空。

例如 mapper/admin 用于生成 mapper/admin/ 目录，或者 tk.mybatis.mapper 生成包（本质上还是目录）。

这个属性还有一个特殊的地方，它还支持使用模板，就和下面的 fileName 一样，举个简单的使用场景。

你可能在生成前端代码的时候，希望将表对应的 JSP 生成在自己的一个目录中，此时可以配置为：

``

模板中可以用到的属性，这里都能用，其他属性后面会介绍。

通过这个路径也能看出来，配置一个插件只能根据模板在一个指定位置(targetProject 和 targetPackage 决定的目录)生成一个文件。

3. `templatePath` Copy Section

指定模板路径，可以是任意能够通过 ClassLoader 能够获取的位置，文件类型没有限制。

例如示例中的 generator/test-one.ftl。

这个属性必须指定，否则不会生成代码!

4. `fileName` Copy Section

这个属性用于指定生成文件的名字，这个值支持使用模板，例如上面的 ${tableClass.shortClassName}Test.txt，具体可用的属性会在后面介绍。

这个属性必须指定，否则不会生成代码!

5. `templateFormatter` Copy Section

这个属性可选，默认使用基于 FreeMarker 的实现!

默认情况下，你需要添加下面的依赖：

<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>2.3.23</version>
</dependency>

默认的实现类为：tk.mybatis.mapper.generator.formatter.FreemarkerTemplateFormatter。

这个类实现了两个接口 TemplateFormatter, ListTemplateFormatter。

这俩接口分别对应下面 singleMode 参数值的 true 和 false。

也就是一个表生成一个文件，或者多个表生成一个文件。

对于一般情况下，都是第一种情况。但是在配置文件中，可能会用到多个表的信息。

如果你想使用其他模板引擎，可以自己实现上面的接口。

6. `singleMode` Copy Section

上面已经提过，默认为 true。

一个表生成一个文件时，可用属性可以参考 generator/test-one.ftl，表的属性在 tableClass 中。

多个表生成一个文件时，可用属性可以参考 generator/test-all.ftl，所有表的属性在 tableClassSet 中，通过遍历可以获取单个的信息。

7. 其他你需要的属性 Copy Section

模板中需要的特殊信息都可以通过 `` 方法设置，在模板中直接使用这里定义的属性名来使用，后面例子的中的 mapperSuffix 就是这种属性。

`TemplateFilePlugin` 配置示例 Copy Chapter

因为模板需要根据业务进行设计，所以这里只提供了两个简单的 mapper 目标和两个完整属性的示例模板。

因为一个模板只能生成一类的文件，所以如果要生成多个不同的文件，就需要配置多个插件。

这种设计很灵活，因为自由度很高，所以代价就是配置的多。

但是正常情况下，根据业务设计的一套模板基本是固定的，不会有太多变化，所以用起来并不麻烦。

例如下面的示例：

前两个会生成 Dao 后缀的 Mapper 接口和 XML，其中有个针对性的参数 mapperSuffix 用于配置后缀， 还有个 mapperPackage 在生成 XML
时获取接口的包名（因为和这里的 targetPackage 可以不同）。

后两个插件用于演示所有可用的属性，而且是两种不同的模式。

在表和实体上可用的所有属性如下：

/* Detailed source-code truncated for AI context efficiency. */

测试执行 Copy Chapter

上面示例就是本项目的测试代码，在 src/test/resources/generator/generatorConfig.xml 中。

还提供了一种 Java 编码方式运行的类，src/test/java/ 中的 tk.mybatis.mapper.generator.Generator，配置上面 xml 中的数据库信息就可以生成。

测试生成的部分结果如下。

实体：

@Table(name = "`user_info`")
public class UserInfo {
    @Id
    @Column(name = "`Id`")
    @GeneratedValue(generator = "JDBC")
    private Integer id;

Dao：

package test.mapper;

import test.model.UserInfo;

/**
* 通用 Mapper 代码生成器
*
* @author mapper-generator
*/
public interface UserInfoDao extends tk.mybatis.mapper.common.Mapper {

}

XML：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="test.mapper.UserInfoDao">

</mapper>

test-one.ftl 生成的信息如下：

/* Detailed source-code truncated for AI context efficiency. */

最后 Copy Chapter

基础的代码生成器是很简单的，和 Java 拼字符串输出很像，这里只是使用了模板。

几乎所有人都在 JSP 中用过的 EL 就是一种模板，可能你会 <c:forEach 这种，但是联想不到这里的代码生成器而已。

后续会在 https://github.com/abel533/Mybatis-Spring 项目中提供一套模板做为示例。

项目的发展离不开你的支持，请作者喝杯咖啡吧！

支付宝

微信

File: spring/README.md Copy Chapter

Mybatis 通用 Mapper 和 Spring 集成

依赖 Copy Chapter

项目自身依赖不传递(<scope>provided</scope>)，因此需要自己提供其他依赖：

正常情况下，也是在这些依赖基础上增加的 mapper-spring

<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper-spring</artifactId>
    <version>版本号</version>
</dependency>

其他依赖

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>版本号</version>
</dependency>
<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper</artifactId>
    <version>版本号</version>
</dependency>
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis-spring</artifactId>
    <version>版本号</version>
</dependency>


<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>版本号</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-tx</artifactId>
    <version>版本号</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <version>版本号</version>
</dependency>

配置 Copy Chapter

本项目主要提供了两种大的配置方式。

• MapperScannerConfigurer xml bean 配置
• @MapperScan 注解

除此之外，高版本的 MyBatis (3.4.0+) 和 mybatis-spring (1.3.0+) 中还有一种推荐的 tk.mybatis.mapper.session.Configuration 配置。

通用 Mapper 3.6.0 之后会自动注册带有 @RegisterMapper 注解的基类接口，不在强制要求配置 mappers 属性，只需要给你的基类加 @RegisterMapper 注解即可。

初次使用通用 Mapper 请注意 Copy Section

下面的示例只是演示如何进行配置，具体配置那些参数要自己选择！

所有可配置参数请参考通用 Mapper 文档：

https://github.com/abel533/Mapper/blob/master/wiki/mapper3/2.Integration.md

一、`MapperScannerConfigurer` xml bean 配置 Copy Section

<value>
            mappers=tk.mybatis.mapper.common.Mapper
        </value>

注意两点：

1. 这里使用的 tk.mybatis.spring.mapper.MapperScannerConfigurer，不是官方的 org.xxx
2. 所有对通用 Mapper 的配置，参考上面的 mappers=xxx，一行写一个配置即可

二、`@MapperScan` 注解 Copy Section

纯注解使用的时候，通用 Mapper 的参数不能像原来那样直接配置，为了适应这种方式，提供了三种可用的方式。

下面按照优先级由高到低的顺序来讲注解配置用法。

1. 使用 `mapperHelperRef` 配置

@Configuration
@MapperScan(value = "tk.mybatis.mapper.mapper", mapperHelperRef = "mapperHelper")
public static class MyBatisConfigRef {
    @Bean
    public DataSource dataSource() {
        return new EmbeddedDatabaseBuilder()
                .addScript("CreateDB.sql")
                .build();
    }

    @Bean
    public DataSourceTransactionManager transactionManager() {
        return new DataSourceTransactionManager(dataSource());
    }

    @Bean
    public SqlSessionFactory sqlSessionFactory() throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource());
        return sessionFactory.getObject();
    }

    @Bean
    public MapperHelper mapperHelper() {
        Config config = new Config();
        List<Class> mappers = new ArrayList<Class>();
        mappers.add(Mapper.class);
        config.setMappers(mappers);

        MapperHelper mapperHelper = new MapperHelper();
        mapperHelper.setConfig(config);
        return mapperHelper;
    }
}

在这个例子中 @MapperScan 唯一特殊的地方在于 mapperHelperRef 属性，这个属性用于指定 MapperHelper bean 的 name，这里的名字和代码中配置的 mapperHelper()
的方法名一致。

Spring 中默认的 name 就是方法名，还可以通过 @Bean 注解指定 name。

在这种配置方式中，你可以很方便的控制 MapperHelper 中的各项配置。

2. 使用 `properties` 配置

@Configuration
@MapperScan(value = "tk.mybatis.mapper.mapper",
    properties = {
            "mappers=tk.mybatis.mapper.common.Mapper",
            "notEmpty=true"
    }
)
public static class MyBatisConfigProperties {
    @Bean
    public DataSource dataSource() {
        return new EmbeddedDatabaseBuilder()
                .addScript("CreateDB.sql")
                .build();
    }

    @Bean
    public DataSourceTransactionManager transactionManager() {
        return new DataSourceTransactionManager(dataSource());
    }

    @Bean
    public SqlSessionFactory sqlSessionFactory() throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource());
        return sessionFactory.getObject();
    }
}

如上面代码中所示，这种配置方式和 xml bean 的方式比较接近，就是通过一行一行的 xx=xxx 对通用 Mapper 进行配置，配置时参考这里的示例配置即可。

3. Spring Boot 环境中使用 `application.[yml|properties]` 配置文件

在 Spring Boot 中使用 Mapper 时，如果选择使用注解方式（可以不引入 mapper-starter 依赖），就可以选择这第 3 种方式。

特别提醒：Spring Boot 中常见的是配置文件方式，使用环境变量或者运行时的参数都可以配置，这些配置都可以对通用 Mapper 生效。

例如在 yml 格式中配置：

mapper:
  mappers:
    - tk.mybatis.mapper.common.Mapper
    - tk.mybatis.mapper.common.Mapper2
  not-empty: true

在 propertie 配置中：

mapper.mappers=tk.mybatis.mapper.common.Mapper,tk.mybatis.mapper.common.Mapper2
mapper.not-empty=true

特别提醒：Spring Boot 中支持 relax 方式的参数配置，但是前面两种方式都不支持，前两种配置参数的时候需要保证大小写一致！

三、`tk.mybatis.mapper.session.Configuration` 配置 Copy Section

使用要求：MyBatis (3.4.0+) 和 mybatis-spring (1.3.0+)

注意该类的包名，这个类继承了 MyBatis 的 Configuration 类，并且重写了 addMappedStatement 方法，如下：

@Override
public void addMappedStatement(MappedStatement ms) {
    try {
        super.addMappedStatement(ms);
        //在这里处理时，更能保证所有的方法都会被正确处理
        if (this.mapperHelper != null) {
            this.mapperHelper.processMappedStatement(ms);
        }
    } catch (IllegalArgumentException e) {
        //这里的异常是导致 Spring 启动死循环的关键位置，为了避免后续会吞异常，这里直接输出
        e.printStackTrace();
        throw new RuntimeException(e);
    }
}

tk.mybatis.mapper.session.Configuration 提供了 3 种配置通用 Mapper 的方式，如下所示：

/**
 * 直接注入 mapperHelper
 *
 * @param mapperHelper
 */
public void setMapperHelper(MapperHelper mapperHelper) {
    this.mapperHelper = mapperHelper;
}

/**
 * 使用属性方式配置
 *
 * @param properties
 */
public void setMapperProperties(Properties properties) {
    if (this.mapperHelper == null) {
        this.mapperHelper = new MapperHelper();
    }
    this.mapperHelper.setProperties(properties);
}

/**
 * 使用 Config 配置
 *
 * @param config
 */
public void setConfig(Config config) {
    if (mapperHelper == null) {
        mapperHelper = new MapperHelper();
    }
    mapperHelper.setConfig(config);
}

使用 tk.mybatis.mapper.session.Configuration 有两种和 Spring 集成的配置方法

1. Spring XML 配置

配置如下：

<value>
            notEmpty=true
        </value>

特别注意：这种情况下的 MapperScannerConfigurer 是官方 mybatis-spring 中提供的类，不是 tk 开头的！

参考这里的配置即可，注意和其他方式的区别。

这里直接配置一个 tk 中提供的 Configuration，然后注入到 SqlSessionFactoryBean 中。

2. 注解方式

@Bean
public SqlSessionFactory sqlSessionFactory() throws Exception {
    SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
    sessionFactory.setDataSource(dataSource());
    //创建 Configuration，设置通用 Mapper 配置
    tk.mybatis.mapper.session.Configuration configuration = new tk.mybatis.mapper.session.Configuration();
    //有 3 种配置方式
    configuration.setMapperHelper(new MapperHelper());
    sessionFactory.setConfiguration(configuration);
    
    return sessionFactory.getObject();
}

看上述代码以及注释。

File: spring-boot-starter/README.md Copy Chapter

MyBatis Mapper integration with Spring Boot

Mapper-Spring-Boot-Starter 帮助你集成通用 Mapper 到 Spring Boot。

Mapper-Spring-Boot-Starter will help you use Mapper with Spring Boot.

How to use Copy Chapter

在 pom.xml 中添加如下依赖：

Add the following dependency to your pom.xml:

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

1.2.3 - 2018-01-24 Copy Chapter

• 增加 tk.mybatis.spring.mapper.SpringBootBindUtil，使用原生方式兼容 Spring Boot 1.x 和 2.x 版本，已经不存在 relax 值问题，以前的配置不需要修改即可使用。
• 特别注意，如果使用了 @MapperScan 注解，请使用 tk.mybatis.spring.annotation.MapperScan 注解。
• 通用 Mapper 升级到 3.5.2 版本。

1.2.2 Copy Chapter

• 由于 weekend 版本依赖问题，这个版本存在问题，不作为正式发布版本。

1.2.1 - 2018-01-10 Copy Chapter

• 为了增强兼容性，MapperAutoConfiguration
  增加 @AutoConfigureBefore(name = "org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration")
  即使依赖中存在 MyBatis 的 starter，Mapper 也可以优先使用自动配置，MyBatis后续就不会触发生成 @Bean

• 支持简单的 relax 绑定，例如 not-empty 会转换为 notEmpty 使用，兼容 spring boot 配置方式

1.2.0 - 2018-01-08 Copy Chapter

• 通用 Mapper 3.5.0
• 去掉 mybatis-spring-boot-starter 依赖，不在使用 mybatis 官方 starter，使用通用 Mapper 时不要再引入官方 starter
• 参考 mybatis 官方 starter 重新实现，解决 mapper
  初始化可能存在的问题 pr#5 by fengcbo
• 如果需要使用 @MapperScan 请选择 tk 开头的 tk.mybatis.spring.annotation.MapperScan

1.1.7 - 2017-12-17 Copy Chapter

• 通用 Mapper 3.4.6
• spring-boot 1.5.9.RELEASE

1.1.6 - 2017-11-11 Copy Chapter

• 通用 Mapper 3.4.5

1.1.5 - 2017-10-21 Copy Chapter

• 通用 Mapper 3.4.4
• mybatis-starter 1.3.1
• spring-boot 1.5.8.RELEASE

1.1.4 - 2017-08-18 Copy Chapter

• 通用 Mapper 3.4.3

1.1.3 - 2017-07-18 Copy Chapter

• 通用 Mapper 3.4.2

1.1.2 - 2017-07-17 Copy Chapter

• 通用 Mapper 3.4.1
• mybatis 3.4.4
• mybatis-spring-boot 1.3.0
• spring-boot 1.5.4.RELEASE

1.1.1 - 2017-03-28 Copy Chapter

• 解决 1.1.0 版本不一致的问题
• 增加对多数据源的支持，感谢 邱占波的 PR #2

1.1.0 - 2017-02-19 Copy Chapter

• mybatis 升级到 3.4.2
• mapper 升级到 3.4.0
• mybatis-spring 升级到 1.3.1
• mybatis-spring-boot 升级到 1.2.0
• spring-boot 升级到 1.4.4.RELEASE

Example Copy Chapter

https://github.com/abel533/MyBatis-Spring-Boot

Special Configurations Copy Chapter

一般情况下，你不需要做任何配置。

Normally, you don't need to do any configuration.

如果需要配置，可以使用如下方式进行配置：

You can config PageHelper as the following:

application.properties:

mapper.propertyName=propertyValue

示例:

mapper.mappers[0]=tk.mybatis.sample.mapper.BaseMapper
mapper.mappers[1]=tk.mybatis.mapper.common.Mapper

默认情况下，没有 mappers 配置时，会自动注册 tk.mybatis.mapper.common.Mapper

因为通用 Mapper 是固定的属性，所以接收参数使用的对象，按照 Spring Boot 配置规则，大写字母都变了带横线的小写字母。针对如 IDENTITY（对应i-d-e-n-t-i-t-y）提供了全小写的 identity 配置，如果
IDE 能自动提示，看自动提示即可。

IDE 应该可以自动提示：

MyBatis Mapper Copy Chapter

https://github.com/abel533/Mapper