通用 Mapper的集成方式

一、集成通用 Mapper

通用 Mapper 有很多种集成方式，这里会介绍大部分情况下的配置方式。

Java 编码方式集成是最少见的一种情况，但是通过这种集成方式可以很容易让大家看清通用 Mapper 集成的入口。

和 Spring 集成是最常见的，Spring Boot 也在慢慢成为主流，为了便于在集成通用 Mapper 的情况下仍然可以和第三方的工具集成，这里也会有很多种集成的方式。

目录

1.1 Java 编码方式集成

1.2 Spring 集成

1.3 Spring Boot 集成

---

 

1.1 Java 编码方式集成

Java 编码方式集成是最少见的一种情况，但是通过这种集成方式可以很容易让大家看清通用 Mapper 集成的入口，这里会提供两种方式。

1. 最直接的方式
2. 使用 Configuration 作为入口集成

1.1.1 添加依赖

在开始写代码前，先把依赖添加进来。

在 Java 编码集成方式中，首先你肯定已经引入了 MyBatis 的依赖：

  org.mybatis
  mybatis
  版本号

所有版本号看这里：http://mvnrepository.com/artifact/org.mybatis/mybatis

通用 Mapper 支持 MyBatis 3.2.4+

在 mybatis 依赖的基础上，添加通用 Mapper 的依赖即可：

    tk.mybatis
    mapper
    最新版本

最新版本看这里：http://mvnrepository.com/artifact/tk.mybatis/mapper

如果你使用的 Jar 包，你可以通过上面提供的链接下载 Jar。

1.1.2 编写代码集成

使用 Java 编码方式时，正常情况下你都会有构建 SqlSessionFactory 的代码。

在创建 SqlSessionFactory 对象前或者后对应两种配置通用 Mapper 的方法，由于没有提供 mybatis-config.xml 文件的解析类，这里会推荐使用 创建后 的方式来创建。

1.1.2.1 创建后

在创建 SqlSessionFactory 后，在任何其他调用发生前，使用下面的方式配置通用 Mapper。

//从刚刚创建的 sqlSessionFactory 中获取 session
session = sqlSessionFactory.openSession();
//创建一个MapperHelper
MapperHelper mapperHelper = new MapperHelper();
//特殊配置
Config config = new Config();
//主键自增回写方法,默认值MYSQL,详细说明请看文档
config.setIDENTITY("MYSQL");
//支持getter和setter方法上的注解
config.setEnableMethodAnnotation(true);
//设置 insert 和 update 中，是否判断字符串类型!=''
config.setNotEmpty(true);
//校验Example中的类型和最终调用时Mapper的泛型是否一致
config.setCheckExampleEntityClass(true);
//启用简单类型
config.setUseSimpleType(true);
//枚举按简单类型处理
config.setEnumAsSimpleType(true);
//自动处理关键字 - mysql
config.setWrapKeyword("`{0}`");
//设置配置
mapperHelper.setConfig(config);
//注册通用接口，和其他集成方式中的 mappers 参数作用相同
//4.0 之后的版本，如果类似 Mapper.class 这样的基础接口带有 @RegisterMapper 注解，就不必在这里注册
mapperHelper.registerMapper(Mapper.class);
//配置 mapperHelper 后，执行下面的操作
mapperHelper.processConfiguration(session.getConfiguration());

如果省略 Config 的配置，上述代码简化为：

//从刚刚创建的 sqlSessionFactory 中获取 session
session = sqlSessionFactory.openSession();
//创建一个MapperHelper
MapperHelper mapperHelper = new MapperHelper();
mapperHelper.processConfiguration(session.getConfiguration());

通用 Mapper 默认就是通过 session.getConfiguration() 获取所有的 MyBatis 方法，然后对其中属于通用方法的方法进行处理。

1.1.2.2 创建前

创建前就是通过使用 tk.mybatis.mapper.session.Configuration 替换 MyBatis 中的 org.apache.ibatis.session.Configuration 来实现。配置代码如下：

Configuration configuration = new Configuration();
//这里可以参考上面的方式来配置 MapperHelper
configuration.setMapperHelper(new MapperHelper());
sqlSessionFactory = new SqlSessionFactoryBuilder().build(configuration);

实现原理：

这种配置方式是通过重写原 Configuration 中的 addMappedStatement 方法来实现的：

@Override
public void addMappedStatement(MappedStatement ms) {
  try {
    super.addMappedStatement(ms);
    //没有任何配置时，使用默认配置
    if (this.mapperHelper == null) {
      this.mapperHelper = new MapperHelper();
    }
    this.mapperHelper.processMappedStatement(ms);
  } catch (IllegalArgumentException e) {
    //这里的异常是导致 Spring 启动死循环的关键位置，为了避免后续会吞异常，这里直接输出
    e.printStackTrace();
    throw new RuntimeException(e);
  }
}

通过上面其中一种方式配置后，通用方法都会生效。

接下来请继续看下一章内容。

1.1.3 细化依赖的用法

首先不推荐 Maven 初学者看这里，也不建议通用 Mapper 初学者看这里。

在决定是否看之前，先看看细化依赖用法的特点：

• 可以以最精简的方式引入通用 Mapper，按照需要引入。
• 可以将某个依赖替换为自己的实现或者选择特定版本的依赖（比如某些依赖可以选择 Java 6 或者 Java 8 的版本）。

当你需要自己选择具体的依赖时，继续看下面的介绍。

通用 Mapper4 中，原来的 tk.mybatis:mapper 项目已经拆分，1.1.1 中添加的依赖是通过特殊打包方式将所有拆分的项目合并到了一个 jar 包中。

如果需要对依赖进行详细的定制，可以分别引入下面的依赖：

  tk.mybatis
  mapper-core
  ${mapper-core.version}




  tk.mybatis
  mapper-base
  ${mapper-base.version}



  tk.mybatis
  mapper-extra
  ${mapper-extra.version}



  tk.mybatis
  mapper-weekend
  ${mapper-weekend.version}



  tk.mybatis
  mapper-generator
  ${mapper-generator.version}

这些依赖的版本号可以通过 mapper-all 子模块进行查看

https://github.com/abel533/Mapper/tree/master/mapper-all/pom.xml

还可以通过下面的目录查找

http://central.maven.org/maven2/tk/mybatis/

1.2 Spring 集成

这是 MyBatis 最常用的一种的环境。通用 Mapper 提供了多种方式来和 Spring 进行集成。

1.2.1 添加依赖

在开始配置前，先添加相关的依赖。

正常情况下，Spring 和 MyBatis 的集成环境中，应该已经存在下面的依赖：

  org.mybatis
  mybatis
  版本号


  org.mybatis
  mybatis-spring
  版本号


  org.springframework
  spring-context
  版本号


  org.springframework
  spring-tx
  版本号


  org.springframework
  spring-jdbc
  版本号

相关依赖和版本可以通过 http://mvnrepository.com/ 进行搜索

通用 Mapper 支持 MyBatis 3.2.4+

集成通用 Mapper 在上面的基础上添加下面的依赖：

    tk.mybatis
    mapper
    最新版本

通用 Mapper 最新版本看这里：http://mvnrepository.com/artifact/tk.mybatis/mapper

tk.mybatis:mapper 依赖包含了通用 Mapper 的基础代码以及和 Spring 集成必须的代码

1.2.2 和 Spring 集成

和 Spring 进行集成时，分为 XML 和注解配置两种方式，每种方式又有不同的配置方式。

这里提供了很多配置方式，使用时选择一种改动最小的方式即可！

1.2.2.1 XML 配置

1.使用 MapperScannerConfigurer

和通用 Mapper 以前版本一样，可以直接使用 tk.mybatis 提供的 tk.mybatis.spring.mapper.MapperScannerConfigurer 进行配置，这个配置和 MyBatis 官方提供的 org.mybatis.spring.mapper.MapperScannerConfigurer 区别只是第一层的包名，tk 和 org。所以使用这种方式时，如果你项目已经使用 org. 进行了配置，只需要改成 tk. 即可。

如果你需要对通用 Mapper 进行特殊配置，可以按下面的方式进行配置：

    
    
    
        
            参数名=值
            参数名2=值2
            ...
        
    

可用配置的参数请看后续的配置文档，配置参数时一行写一个值。

2.XML 配置使用 Configuration

如果某些第三方也需要特殊的 MapperScannerConfigurer 时，就不能用上面的方式进行配置了，此时可以选择下面这种方式，这种方式要求使用MyBatis (3.4.0+) 和 mybatis-spring (1.3.0+)，配置方式如下：

    
    
        
            notEmpty=true
        
    



    
    




    
    

这里使用了 tk.mybatis.mapper.session.Configuration ，也就是不能通过读取 mybatis-config.xml进行配置，上面这种配置更直接，使用 Spring setter 配置属性更方便。当需要配置通用 Mapper 时，使用 mapperProperties 属性配置即可，配置方式和前面的相同，一行一个配置即可。

配置了一个 mybatisConfig 的 bean 后，在 SqlSessionFactoryBean 中注入即可。

后面的 MapperScannerConfigurer 只是为了说明这里不需要使用 tk. 开头的类进行配置。

这种配置方式基本上和任何第三方都不会冲突，如果你遇到了第三方重写 SqlSessionFactoryBean 的情况，就使用前一种方式配置即可。

1.2.2.2 使用 @MapperScan 注解

如果要使用该注解进行配置，请确认选择的是 tk.mybatis.spring.annotation.MapperScan 注解（必须使用官方的注解时，看下面其他配置方式）。

tk 提供的这个注解相比官方的多了下面两个属性：

/**
 * 通用 Mapper 的配置，一行一个配置
 *
 * @return
 */
String[] properties() default {};

/**
 * 还可以直接配置一个 MapperHelper bean
 *
 * @return
 */
String mapperHelperRef() default "";

这两个配置方式中，mapperHelperRef 优先级更高，只需要选择其中一种方式进行配置即可。

1.使用 properties 配置时：

@Configuration
@MapperScan(value = "tk.mybatis.mapper.annotation",
    properties = {
            "mappers=tk.mybatis.mapper.common.Mapper",
            "notEmpty=true"
    }
)
public class MyBatisConfigProperties {

和 XML 中很像，仍然一个一个配置。

2.使用 mapperHelperRef 配置时：

@Configuration
@MapperScan(value = "tk.mybatis.mapper.annotation", mapperHelperRef = "mapperHelper")
public static class MyBatisConfigRef {
    //其他
 
    @Bean
    public MapperHelper mapperHelper() {
        Config config = new Config();
        List mappers = new ArrayList();
        mappers.add(Mapper.class);
        config.setMappers(mappers);

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

这里配置 mapperHelperRef = "mapperHelper"，并且提供了一个名为 mapperHelper 的 bean。对通用 Mapper 的任何配置直接通过编码对 MapperHelper 进行配置。

3.使用 Configuration 进行配置

这里可以使用 tk 或者 MyBatis 官方的 @MapperScan 注解。

@Configuration
@MapperScan(value = "tk.mybatis.mapper.annotation")
public static class MyBatisConfigRef {

    @Bean
    public SqlSessionFactory sqlSessionFactory() throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource());
        //tk.mybatis.mapper.session.Configuration
        Configuration configuration = new Configuration();
        //可以对 MapperHelper 进行配置后 set
        configuration.setMapperHelper(new MapperHelper());
        //设置为 tk 提供的 Configuration
        sessionFactory.setConfiguration(configuration);
        return sessionFactory.getObject();
    }
}

@MapperScan 注解在 Spring Boot 集成中还会提到。

文档到这里就集成好通用 Mapper 了，接下来请继续看下一章内容。

1.2.3 细化依赖的用法

首先不推荐 Maven 初学者看这里，也不建议通用 Mapper 初学者看这里。

在决定是否看之前，先看看细化依赖用法的特点：

• 可以以最精简的方式引入通用 Mapper，按照需要引入。
• 可以将某个依赖替换为自己的实现或者选择特定版本的依赖（比如某些依赖可以选择 Java 6 或者 Java 8 的版本）。
• 支持 Spring 高版本的特殊用法（例如多个 @MapperScan注解，暂时还没提供）

通用 Mapper4 中，原来的 tk.mybatis:mapper 项目已经拆分，1.2.1 中添加的依赖是通过特殊打包方式将所有拆分的项目合并到了一个 jar 包中。

如果需要对依赖进行详细的定制，可以分别引入下面的依赖：

  tk.mybatis
  mapper-core
  ${mapper-core.version}




  tk.mybatis
  mapper-base
  ${mapper-base.version}



  tk.mybatis
  mapper-extra
  ${mapper-extra.version}



  tk.mybatis
  mapper-weekend
  ${mapper-weekend.version}



  tk.mybatis
  mapper-generator
  ${mapper-generator.version}



  tk.mybatis
  mapper-spring
  ${mapper-spring.version}

这些依赖的版本号可以通过 mapper-all 子模块进行查看

https://github.com/abel533/Mapper/tree/master/mapper-all/pom.xml

还可以通过下面的目录查找

http://central.maven.org/maven2/tk/mybatis/

1.3 Spring Boot 集成

Spring Boot 在微服务领域中已经成为主流。

这里介绍通用 Mapper 如何同 Spring Boot 进行集成。

为了能适应各种情况的用法，这里也提供了多种集成方式，基本上分为两大类。

• 基于 starter 的自动配置
• 基于 @MapperScan 注解的手工配置

1.3.1 mapper-spring-boot-starter

在 starter 的逻辑中，如果你没有使用 @MapperScan 注解，你就需要在你的接口上增加 @Mapper注解，否则 MyBatis 无法判断扫描哪些接口。

这里的第一种用法没有用 @MapperScan 注解，所以你需要在所有接口上增加 @Mapper 注解。

以后会考虑增加其他方式。

你只需要添加通用 Mapper 提供的 starter 就完成了最基本的集成，依赖如下：

  tk.mybatis
  mapper-spring-boot-starter
  版本号

最新版本号如上所示，你也可以从下面地址查看：

http://mvnrepository.com/artifact/tk.mybatis/mapper-spring-boot-starter

注意：引入该 starter 时，和 MyBatis 官方的 starter 没有冲突，但是官方的自动配置不会生效！

如果你需要对通用 Mapper 进行配置，你可以在 Spring Boot 的配置文件中配置 mapper. 前缀的配置。

例如在 yml 格式中配置：

mapper:
  mappers:
    - tk.mybatis.mapper.common.Mapper
    - tk.mybatis.mapper.common.Mapper2
  notEmpty: true

在 properties 配置中：

mapper.mappers=tk.mybatis.mapper.common.Mapper,tk.mybatis.mapper.common.Mapper2
mapper.notEmpty=true

由于 Spring Boot 支持 Relax 方式的参数，因此你在配置 notEmpty 时更多的是用 not-empty，也只有在 Spring Boot 中使用的时候参数名不必和配置中的完全一致。

如果你对 Spring Boot 的 Environment 了解，你可以用 Spring Boot 支持的所有方式进行配置。

关于通用 Mapper 支持的所有配置请看后续的文档。

1.3.2 @MapperScan 注解配置

你可以给带有 @Configuration 的类配置该注解，或者直接配置到 Spring Boot 的启动类上，如下：

@tk.mybatis.spring.annotation.MapperScan(basePackages = "扫描包")
@SpringBootApplication
public class SampleMapperApplication implements CommandLineRunner {

注意：这里使用的 tk.mybatis.spring.annotation.MapperScan !

你可以直接在 Spring Boot 的配置文件中直接配置通用 Mapper（参考1.3.1中的配置），还可以使用注解中提供的两个属性进行配置：

/**
 * 通用 Mapper 的配置，一行一个配置
 *
 * @return
 */
String[] properties() default {};

/**
 * 还可以直接配置一个 MapperHelper bean
 *
 * @return
 */
String mapperHelperRef() default "";

使用这种方式进行配置时，请参考 1.2.2.2 中的内容。

注意：这两个属性配置方式的优先级更高，所以建议在 Spring Boot 中通过配置文件（或 Environment）配置。

接下来请继续看下一章内容。