第01篇MyBatis基础应用

第01章_MyBatis快速入门

第一节 MyBatis简介

MyBatis 由 Apache 的一个开源项目 iBatis发展而来，是一款在持久层使用的SQL映射框架，可以将SQL语句单独写在XML配置文件中，或者使用带有注解的Mapper映射类来完成数据库记录到Java实体的映射。

• 2002年，Clinton Begin开发了iBatis框架，并引入了SQL映射作为持久化层开发的一种方法，不久后Clinton Begin将iBatis 捐献给Apache软件基金会。

• 2010年，这个项目由Apache 迁移到了Google Code，并改名为MyBatis。

• 2013年11月，MyBatis 迁移到目前最大的源代码托管平台Github。

MyBatis与另一款主流的 ORM(Object Relational Mapping) 框架 Hibernate 不同，属于半自动的 ORM 框架，仍然需要自己编写SQL语句，不能将各种数据库的影响隔离开，但是可以灵活地控制SQL语句的构造，将SQL语句的编写和程序的运行分离开，使用更加便捷。下面是MyBatis 的一些优势，这些优秀的特性使它成为目前最受欢迎的ORM框架之一。

• 消除了大量的JDBC冗余代码，包括参数设置、结果集封装等。

• SQL语句可控制，方便查询优化，使用更加灵活。

• 学习成本比较低，对于新用户能够快速学习使用。

• 提供了与主流IoC框架Spring的集成支持。

• 引入缓存机制，提供了与第三方缓存类库的集成支持。

第二节 MyBatis入门案例

某数据库有一张 User 表，定义如下，现要使用 MyBatis 对其进行查询操作。

​x
1
create database test01 charset utf8;
2

3
create table if not exists user(
4
    id int(11) unsigned not null auto_increment comment '用户编号'
5
    ,username varchar(32) not null comment '用户名称'
6
    ,birthday varchar(38) not null comment '用户生日'
7
    ,sex char(2) not null comment '性别，0男1女'
8
    ,address varchar(255) null comment '用户地址'
9
    ,primary key(id)
10
    )engine=innodb default charset=utf8 comment='用户表';
11

12
insert into user(username, birthday, sex, address) values('hyx', '1999-09-13', '0', '深圳市南山区');
13
commit;
14

1. 前置准备

• 假设你已经建立好一个普通的 maven 工程。

• 生成了 User 表对应的实体类。

17
1
package org.example.model;
2

3
import java.io.Serializable;
4
import java.sql.Date;
5

6
public class User implements Serializable {
7

8
  private Integer id;
9
  private String username;
10
  private Date birthday;
11
  private String sex;
12
  private String address;
13

14
    // 省略getter/setter和toString方法
15
    
16
}
17

• 并且已经写好了 DAO 层接口

9
1
package org.example.dao;
2

3
import org.example.model.User;
4

5
import java.util.List;
6

7
public interface UserDao {
8
  List<User> findAll();
9
}

如果使用传统的 JDBC 或 JdbcTemplate 模板，那么你的下一步应该是实现 DAO 接口，编写具体的 CURD 方法。但是，使用 MyBatis 后，你无需自己手写这些繁琐的实现类，这些 MyBatis 都会使用动态代理技术帮你生成。

2. 依赖导入

MyBatis 有一些必须的依赖，你可以把它加入到 CLASSPATH 路径，或者在 pom 文件中定义它的坐标。

36
1
<?xml version="1.0" encoding="UTF-8"?>
2
<project xmlns="http://maven.apache.org/POM/4.0.0"
3
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5
    <modelVersion>4.0.0</modelVersion>
6

7
    <groupId>org.example</groupId>
8
    <artifactId>demo01</artifactId>
9
    <version>1.0-SNAPSHOT</version>
10

11
    <dependencies>
12
        <!-- MyBatis 依赖-->
13
        <dependency>
14
            <groupId>org.mybatis</groupId>
15
            <artifactId>mybatis</artifactId>
16
            <version>3.4.5</version>
17
        </dependency>
18
        
19
        <!-- JDBC 驱动-->
20
        <dependency>
21
            <groupId>mysql</groupId>
22
            <artifactId>mysql-connector-java</artifactId>
23
            <version>5.1.6</version>
24
            <scope>runtime</scope>
25
        </dependency>
26

27
        <!-- Junit 用于测试-->
28
        <dependency>
29
            <groupId>junit</groupId>
30
            <artifactId>junit</artifactId>
31
            <version>4.10</version>
32
            <scope>test</scope>
33
        </dependency>
34
    </dependencies>
35

36
</project>

如果你使用的是Oracle或SqlServer数据库，应该切换如下驱动：

12
1
<dependency>
2
    <groupId>com.microsoft.sqlserver</groupId>
3
    <artifactId>sqljdbc4</artifactId>
4
    <version>4.0</version>
5
</dependency>
6

7
<dependency>
8
    <groupId>com.oracle</groupId>
9
    <artifactId>ojdbc14</artifactId>
10
    <version>10.2.0.5.0</version>
11
</dependency>
12

3. 主配置文件

现在我们需要一个配置文件来描述 MyBatis 的相关属性和行为。如果你不太明白，没关系，我们在下一章将会详细讲解！

src\main\resources\mybatis-config.xml

26
1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE configuration
3
        PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
4
        "http://mybatis.org/dtd/mybatis-3-config.dtd">
5
<configuration>
6
    <!-- 配置MyBatis的环境 -->
7
    <environments default="mysql">
8
        <!-- 配置mysql 的环境 -->
9
        <environment id="mysql">
10
            <!-- 配置事务的类型 -->
11
            <transactionManager type="JDBC"></transactionManager>
12
            <!-- 配置连接数据库的信息：用的是数据源(连接池) -->
13
            <dataSource type="POOLED">
14
                <property name="driver" value="com.mysql.jdbc.Driver"/>
15
                <property name="url" value="jdbc:mysql://42.192.223.129:3306/test01"/>
16
                <property name="username" value="root"/>
17
                <property name="password" value="root"/>
18
            </dataSource>
19
        </environment>
20
    </environments>
21

22
    <!-- 告知MyBatis映射配置的位置 -->
23
    <mappers>
24
        <mapper resource="org/example/dao/UserDao.xml"/>
25
    </mappers>
26
</configuration>

如果你使用的是Oracle或SqlServer数据库，JDBC连接四要素应修改如下：

9
1
    <property name="driver" value="oracle.jdbc.driver.OracleDriver"/>
2
    <property name="url" value="jdbc:oracle:thin:@127.0.0.1:1521:ORCLONE"/>
3
    <property name="username" value="kbssfms"/>
4
    <property name="password" value="kbssfms"/>
5

6
    <property name ="driverClassName" value ="com.microsoft.sqlserver.jdbc.SQLServerDriver"></property>
7
    <property name ="url" value ="jdbc:sqlserver://127.0.0.1:1433;DatabaseName=kbssfms"></property>
8
    <property name ="username" value ="sa"></property>
9
    <property name ="password" value ="Sa147741"></property>

4. 映射配置文件

除了主配置文件之外，还需要一个映射配置文件，告诉 MyBatis 执行什么SQL，以及参数和结果集如何处理。

src\main\resources\com\mybatis\demo\dao\UserDao.xml

11
1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE mapper
3
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
4
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
5
<mapper namespace="org.example.dao.UserDao">
6

7
    <!-- 查询所有用户 -->
8
    <select id="findAll" resultType="org.example.model.User">
9
        SELECT * FROM user
10
    </select>
11
</mapper>

5. 简单测试

现在我们可以来进行测试了！

46
1
package org.example.dao.test;
2

3
import org.apache.ibatis.io.Resources;
4
import org.apache.ibatis.session.SqlSession;
5
import org.apache.ibatis.session.SqlSessionFactory;
6
import org.apache.ibatis.session.SqlSessionFactoryBuilder;
7
import org.example.dao.UserDao;
8
import org.example.model.User;
9

10
import java.io.InputStream;
11
import java.util.List;
12

13
public class MybatisTest {
14

15
    public static void main(String[] args) throws Exception {
16
        //1.读取主配置文件
17
        InputStream in = Resources.getResourceAsStream("mybatis-config.xml");
18

19
        //2.创建 SqlSessionFactoryBuilder
20
        SqlSessionFactoryBuilder builder = new SqlSessionFactoryBuilder();
21

22
        //3. 构建 SqlSessionFactory
23
        SqlSessionFactory factory = builder.build(in);
24

25
        //4. 打开会话
26
        SqlSession session = factory.openSession();
27

28
        //5. 获取代理对象
29
        UserDao userDao = session.getMapper(UserDao.class);
30

31
        //6. 使用代理对象执行查询所有方法
32
        List<User> users = userDao.findAll();
33
        for (User user : users) {
34
            System.out.println(user);
35
        }
36

37
        //7. 释放资源
38
        if (session != null) {
39
            session.close();
40
        }
41
        if (in != null) {
42
            in.close();
43
        }
44

45
    }
46
}

运行结果如下：

上述案例的完整工程代码可参考附件 mybatis-demo/demo01 工程！

第三节 入门案例详解

1. SqlSessionFactoryBuilder

要想创建一个 Session，需要借助 SqlSeesionFactory，而 SqlSeesionFactory 必须由 SqlSessionFactoryBuilder 来进行构建， SqlSessionFactoryBuilder 有五个 build() 方法，每一种都允许你从不同的资源中创建一个 SqlSessionFactory 实例。

6
1
SqlSessionFactory build(InputStream inputStream)
2
SqlSessionFactory build(InputStream inputStream, String environment)
3
SqlSessionFactory build(InputStream inputStream, Properties properties)
4
SqlSessionFactory build(InputStream inputStream, String env, Properties props)
5
    
6
SqlSessionFactory build(Configuration config)

可以看到，前四种方式都是从一个 InputStream 流中获取配置文件(mybatis-config.xml)，然后构建 SqlSessionFactory，并且提供了不同组合的默认参数供选择，我们入门案例正是使用了这种方式。

另外，也通过接收一个 Configuration 实例来构建 SqlSessionFactory 。Configuration 类包含了对一个 SqlSessionFactory 实例你可能关心的所有内容。以下是一个简单的示例，演示如何手动配置 Configuration 实例，然后将它传递给 build() 方法来创建 SqlSessionFactory。

16
1
DataSource dataSource = BaseDataTest.createBlogDataSource();
2
TransactionFactory transactionFactory = new JdbcTransactionFactory();
3

4
Environment environment = new Environment("development", transactionFactory, dataSource);
5

6
Configuration configuration = new Configuration(environment);
7
configuration.setLazyLoadingEnabled(true);
8
configuration.setEnhancementEnabled(true);
9
configuration.getTypeAliasRegistry().registerAlias(Blog.class);
10
configuration.getTypeAliasRegistry().registerAlias(Post.class);
11
configuration.getTypeAliasRegistry().registerAlias(Author.class);
12
configuration.addMapper(BoundBlogMapper.class);
13
configuration.addMapper(BoundAuthorMapper.class);
14

15
SqlSessionFactoryBuilder builder = new SqlSessionFactoryBuilder();
16
SqlSessionFactory factory = builder.build(configuration);

2. SqlSessionFactory

有了 SqlSessionFactory 之后，我们就可以用它来创建 SqlSession 了。它有 6 个重载的方法供我们使用，具体使用哪一个，这取决于你对事务、连接和执行器类型的选择。

10
1
SqlSession openSession()  
2
SqlSession openSession(boolean autoCommit)
3
SqlSession openSession(Connection connection)
4
SqlSession openSession(TransactionIsolationLevel level) 
5
SqlSession openSession(ExecutorType execType, TransactionIsolationLevel level)
6
SqlSession openSession(ExecutorType execType)
7
SqlSession openSession(ExecutorType execType, boolean autoCommit)
8
SqlSession openSession(ExecutorType execType, Connection connection)
9
Configuration getConfiguration();
10

无参数的opensseion()方法具有下列默认行为：

• 事务作用域将会开启（也就是不自动提交）。

• 事务隔离级别将会使用驱动或数据源的默认设置。

• 将由当前环境配置的 DataSource 实例中获取 Connection 对象。

• 预处理语句不会被复用，也不会批量处理更新（采用 SIMPLE 类型执行器）。

除此之外，SqlSessionFacotry还有一个方法：getConfiguration()。这个方法会返回一个 Configuration 实例，你可以在运行时使用它来检查 MyBatis 的配置。

事物的隔离级别

对于事务隔离级别，MyBatis 使用了一个 Java 枚举包装器来表示，称为 TransactionIsolationLevel，事务隔离级别支持 JDBC 的五个隔离级别（NONE、READ_UNCOMMITTED、READ_COMMITTED、REPEATABLE_READ 和 SERIALIZABLE），并且与预期的行为一致

 

执行器类型

你可能对 ExecutorType 参数感到陌生。这个枚举类型定义了三个值:

• ExecutorType.SIMPLE：该类型的执行器没有特别的行为。它为每个语句的执行创建一个新的预处理语句。

• ExecutorType.REUSE：该类型的执行器会复用预处理语句。

• ExecutorType.BATCH：该类型的执行器会批量执行所有更新语句，如果 SELECT 在多个更新中间执行，将在必要时将多条更新语句。

3. SqlSession

SqlSession 在 MyBatis 中是非常强大的一个类。它包含了所有执行语句、提交或回滚事务以及获取映射器实例的方法。下面对其进行分类展示和介绍。

46
1
// 1. 语句执行方法
2
<T> T selectOne(String statement, Object parameter)
3
<E> List<E> selectList(String statement, Object parameter)
4
<T> Cursor<T> selectCursor(String statement, Object parameter) // 游标形式：可以借助迭代器实现数据的惰性加载
5
<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey)
6
int insert(String statement, Object parameter) // insert、update 以及 delete 方法返回的值表示受该语句影响的行数
7
int update(String statement, Object parameter)
8
int delete(String statement, Object parameter)
9

10
// 2. 语句执行方法(不需要参数的重载形式)
11
<T> T selectOne(String statement)
12
<E> List<E> selectList(String statement)
13
<T> Cursor<T> selectCursor(String statement)
14
<K,V> Map<K,V> selectMap(String statement, String mapKey)
15
int insert(String statement)
16
int update(String statement)
17
int delete(String statement)
18

19
// 3. select方法的高级版本：允许你限制返回行数的范围，或是提供自定义结果处理逻辑，通常在数据集非常庞大的情形下使用。
20
<E> List<E> selectList (String statement, Object parameter, RowBounds rowBounds)
21
<T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds)
22
<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowbounds)
23
void select (String statement, Object parameter, ResultHandler<T> handler)
24
void select (String statement, Object parameter, RowBounds rowBounds, ResultHandler<T> handler)
25

26
// 4. 批量更新方法：当使用 BATCH 执行器时，可以使用这个方法清除（执行）缓存在 JDBC 驱动类中的批量更新语句。
27
List<BatchResult> flushStatements()
28

29
// 5. 事务控制方法：在使用由 Connection 实例控制的 JDBC 事务管理器时，用于控制事务作用域。注意：这些方法不适用于外部事务管理器。
30
void commit()
31
void commit(boolean force)
32
void rollback()
33
void rollback(boolean force)
34

35
// 6. 清空本地缓存(会话缓存)
36
void clearCache()
37

38
// 7. 关闭会话
39
void close()
40
    
41
// 8. 获取 Configuration 实例
42
Configuration getConfiguration()
43
 
44
// 9. 获取映射器：映射器相对上述CURD方法，最大的优点是符合类型安全，并且对IDE和单元测试也更加友好。
45
<T> T getMapper(Class<T> type)
46
    

关于 RowBounds 和 ResultHandler 在官网有更详细的解释，可以点击这：https://mybatis.org/mybatis-3/zh/java-api.html。

4. 映射器实例

SqlSeesion中的各个 insert、update、delete 和 select 方法都很强大，但也有些繁琐，它们并不符合类型安全，对你的 IDE 和单元测试也不是那么友好。因此，使用映射器类来执行映射语句是更常见的做法。

我们已经在之前的入门案例中见到过一个使用映射器的示例。一个映射器类就是一个仅需声明与 SqlSession 方法相匹配方法的接口。下面的示映射器例展示了一些方法签名以及它们是如何映射到 SqlSession 上的。

14
1
public interface AuthorMapper {
2
  Author selectAuthor(int id); // (Author) selectOne("selectAuthor",5);
3

4
  List<Author> selectAuthors(); // (List<Author>) selectList(“selectAuthors”)
5

6
  @MapKey("id")
7
  Map<Integer, Author> selectAuthors(); // (Map<Integer,Author>) selectMap("selectAuthors", "id")
8

9
  int insertAuthor(Author author); // insert("insertAuthor", author)
10

11
  int updateAuthor(Author author); // updateAuthor("updateAuthor", author)
12

13
  int deleteAuthor(int id); // delete("deleteAuthor",5)
14
}

总之，每个映射器方法签名有与之相关联的 SqlSession 方法。

映射器接口可以继承自其他接口。在使用 XML 来绑定映射器接口时，保证语句处于合适的命名空间中即可。唯一的限制是，不能在两个具有继承关系的接口中拥有相同的方法签名（这是潜在的危险做法，不可取）。

你也可以传递多个参数给一个映射器方法。在多个参数的情况下，默认它们将会以 param 加上它们在参数列表中的位置来命名，比如：#{param1}、#{param2}等。如果你想（在有多个参数时）自定义参数的名称，那么你可以在参数上使用 @Param("paramName") 注解。

除外之外，你还可以给方法传递一个 RowBounds 实例来限制查询结果等。

5. 使用注解替换映射器配置

MyBatis 针对映射器配置，定义了一套注解，可以让我们更加方便的进行相关配置。

• 在接口加上注解，同时删去 UserDao.xml 文件(删除对应方法配置亦可)。

5
1
public interface UserDao {
2
  @Select("SELECT * FROM USER")
3
  List<User> findAll();
4
}
5

• 修改mybatis-config.xml，让 MyBatis 去扫描注解。

5
1
<!-- 告知MyBatis映射配置的位置 -->
2
<mappers>
3
    <mapper class="com.mybatis.demo.dao.UserDao"/>
4
</mappers>
5

注意 同一个方法，不能同时存在映射配置文件和注解两种配置方式，MyBatis将检测并抛出异常！

注解使用案例可以参考mybatis-demo02。

6. 添加日志输出

MyBatis在运行时会按照下列顺序检测日志实现，如果没有找到这些实现时，将会禁用日志功能。

• SLF4J

• Apache Commons Logging (Tomcat 和 WebShpere 应用服务器的默认日志)

• Log4j 2

• Log4j

• JDK logging

当然，你也可以在mybatis-config.xml配置文件中显示指定日志实现。

8
1
<configuration>
2
  <settings>
3
    ...
4
    <setting name="logImpl" value="LOG4J"/>
5
    ...
6
  </settings>
7
</configuration>
8
      

可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了 org.apache.ibatis.logging.Log 接口，且构造方法以字符串为参数的类完全限定名。

你也可以在调用其它 MyBatis 方法之前调用以下任一方法来切换日志实现：

5
1
org.apache.ibatis.logging.LogFactory.useSlf4jLogging();
2
org.apache.ibatis.logging.LogFactory.useLog4JLogging();
3
org.apache.ibatis.logging.LogFactory.useJdkLogging();
4
org.apache.ibatis.logging.LogFactory.useCommonsLogging();
5
org.apache.ibatis.logging.LogFactory.useStdOutLogging();

注意，仅当运行时类路径中存在该日志实现时，日志实现的切换才会生效，否则会使用默认顺序来查找日志实现。

你可以通过在包、映射类的全限定名、命名空间或全限定语句名上开启日志功能，来查看 MyBatis 的日志语句。具体的配置步骤与日志实现有关，下面以 Log4J 作为示范。

首先，你应该确保应用的类路径下有 Log4J 的jar 包，或导入了相应的 maven 坐标。

5
1
<dependency>
2
    <groupId>log4j</groupId>
3
    <artifactId>log4j</artifactId>
4
    <version>1.2.12</version>
5
</dependency>

然后，添加 log4j.properties配置文件到应用类路径下，简单配置如下。

10
1
## 全局日志配置
2
log4j.rootLogger=ERROR, stdout
3

4
## MyBatis 日志配置
5
log4j.logger.org.mybatis.example.BlogMapper=TRACE
6

7
## 控制台输出
8
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
9
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
10
log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n

上述配置将使 Log4J 详细打印 org.mybatis.example.BlogMapper 的日志，对于应用的其它部分，只打印错误信息。

你可以按需调整日志输出的粒度，参考如下。

8
1
## 只打印语句 selectBlog 的日志
2
log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE
3

4
## 打印一组映射器的日志
5
log4j.logger.org.mybatis.example=TRACE
6

7
## 只想查看SQL语句，而忽略结果集，一般用于返回大量数据的场景(因为SQL语句的日志级别是 DEBUG，而返回的结果集是 TRACE )
8
log4j.logger.org.mybatis.example=DEBUG

配置文件 log4j.properties 的余下内容用来配置输出器（appender），这一内容已经超出本文档的范围。关于 Log4J 的更多内容，可以参考 Log4J 的官方网站。

第02章_全局配置文件详解

MyBatis 的配置文件包含了会深深影响 MyBatis 行为的设置和属性信息。 配置文档的顶层结构如下：

• configuration（配置）

  • properties（属性）

  • settings（设置）

  • typeAliases（类型别名）

  • typeHandlers（类型处理器）

  • objectFactory（对象工厂）

  • plugins（插件）

  • environments（环境配置）

    • environment（环境变量）

      • transactionManager（事务管理器）

      • dataSource（数据源）

  • databaseIdProvider（数据库厂商标识）

  • mappers（映射器）

在开发过程中，可以参考配置文件头部的DTD约束来进行配置！

第一节 properties标签

1. property的定义和使用

property 是一个 key-value 键值对，可以直接在 properties 标签内部用 property 子标签定义，也可以从外部资源文件引入，并且可以进行动态替换。

4
1
<properties resource="org/mybatis/example/config.properties">
2
  <property name="username" value="dev_user"/>
3
  <property name="password" value="F2Fa3!33TYyg"/>
4
</properties>

tips：properties标签也可以使用 url 属性引入网络资源或本地磁盘文件。

设置好的属性可以在整个配置文件中用来替换需要动态配置的属性值。

6
1
<dataSource type="POOLED">
2
  <property name="driver" value="${driver}"/>
3
  <property name="url" value="${url}"/>
4
  <property name="username" value="${username}"/>
5
  <property name="password" value="${password}"/>
6
</dataSource>

这个例子中的占位符 ${username} 和 ${password} 将会由 property 标签中设置的相应值来替换。${driver} 和 ${url} 将会由 config.properties 文件中对应的值来替换。这样就为配置提供了诸多灵活选择。

除此之外，也可以在 SqlSessionFactoryBuilder.build() 方法中传入属性值。例如：

3
1
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, props); 
2
// ... 或者 ...
3
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment, props);

2. property的优先级

如果一个属性在不只一个地方进行了配置，那么，MyBatis 将按照下面的顺序来加载：

• 首先读取在 properties 标签体内指定的属性。

• 然后根据 properties 元素中的 resource 属性读取类路径下属性文件，或根据 url 属性指定的路径读取属性文件，并覆盖之前读取过的同名属性。

• 最后读取作为方法参数传递的属性，并覆盖之前读取过的同名属性。

因此，通过方法参数传递的属性具有最高优先级，resource/url 属性中指定的配置文件次之，最低优先级的则是 properties 元素中指定的属性。

3. 设置占位符的默认值

从 MyBatis 3.4.2 开始，你可以为占位符指定一个默认值。例如：

5
1
<dataSource type="POOLED">
2
  <!-- 如果属性 'username' 没有被配置，'username' 属性的值将为 'ut_user' -->
3
  <property name="username" value="${username:ut_user}"/> 
4
</dataSource>
5

这个特性默认是关闭的。要启用这个特性，需要添加一个特定的属性来开启这个特性。

4
1
<properties resource="org/mybatis/example/config.properties">
2
    <!-- 启用默认值特性 -->
3
  <property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/> 
4
</properties>

由于占位符默认值的分隔符默认为:，如果你在属性名中使用了 ":" 字符（如：db:username），或者在 SQL 映射中使用了 OGNL 表达式的三元运算符（如： ${tableName != null ? tableName : 'global_constants'}），就需要设置特定的属性来修改分隔属性名和默认值的字符。

11
1
<properties resource="org/mybatis/example/config.properties">
2
<!-- 修改默认值的分隔符 -->
3
  <property name="org.apache.ibatis.parsing.PropertyParser.default-value-separator" value="?:"/> 
4
</properties>
5

6

7
<dataSource type="POOLED">
8
  <!-- 如果属性 'db:username' 没有被配置，'db:username' 属性的值将为 'ut_user' -->
9
  <property name="username" value="${db:username?:ut_user}"/>
10
</dataSource>
11

第二节 settings标签

settings 标签是 MyBatis 中极为重要的调整设置，它们会改变 MyBatis 的运行时行为。 下表描述了设置中各项设置的含义、默认值等。

下面是一个配置完整的 settings 元素的示例。

17
1
<settings>
2
  <setting name="cacheEnabled" value="true"/>
3
  <setting name="lazyLoadingEnabled" value="true"/>
4
  <setting name="multipleResultSetsEnabled" value="true"/>
5
  <setting name="useColumnLabel" value="true"/>
6
  <setting name="useGeneratedKeys" value="false"/>
7
  <setting name="autoMappingBehavior" value="PARTIAL"/>
8
  <setting name="autoMappingUnknownColumnBehavior" value="WARNING"/>
9
  <setting name="defaultExecutorType" value="SIMPLE"/>
10
  <setting name="defaultStatementTimeout" value="25"/>
11
  <setting name="defaultFetchSize" value="100"/>
12
  <setting name="safeRowBoundsEnabled" value="false"/>
13
  <setting name="mapUnderscoreToCamelCase" value="false"/>
14
  <setting name="localCacheScope" value="SESSION"/>
15
  <setting name="jdbcTypeForNull" value="OTHER"/>
16
  <setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString"/>
17
</settings>

第三节 typeAliases标签

1. 配置JavaBean的别名

类型别名可为 Java 类型设置一个缩写名字。 它仅用于 XML 配置，意在降低冗余的全限定类名书写。例如：

4
1
<typeAliases>
2
  <typeAlias alias="Author" type="domain.blog.Author"/>
3
  <typeAlias alias="Blog" type="domain.blog.Blog"/>
4
</typeAliases>

当这样配置时，Blog 可以用在任何使用 domain.blog.Blog 的地方。

也可以指定一个包名，MyBatis 会在包名下面搜索需要的 Java Bean，比如：

3
1
<typeAliases>
2
  <package name="domain.blog"/>
3
</typeAliases>

每一个在包 domain.blog 中的 Java Bean，在没有注解的情况下，会使用 Bean 的首字母小写的非限定类名来作为它的别名。 比如 domain.blog.Author 的别名为 author；若有注解，则别名为其注解值。见下面的例子：

4
1
@Alias("author")
2
public class Author {
3
    ...
4
}

2. 内置的类型别名

下面是一些为常见的 Java 类型内建的类型别名。它们都是不区分大小写的，注意，为了应对原始类型的命名重复，采取了特殊的命名风格。

第四节 typehandlers标签

1. 默认类型处理器

MyBatis 在设置预处理语句（PreparedStatement）中的参数或从结果集中取出一个值时， 都会用类型处理器将获取到的值以合适的方式转换成 Java 类型。下表描述了一些默认的类型处理器

tips：从 3.4.5 开始，MyBatis 默认支持 JSR-310（日期和时间 API）

2. 自定义类型处理器

你可以创建你自己的类型处理器或重写已有的类型处理器来处理不支持的或非标准的类型。只需要实现 org.apache.ibatis.type

.TypeHandler 接口， 或继承一个很便利的类 org.apache.ibatis.type.BaseTypeHandler， 并且可以（可选地）将它映射到一个 JDBC 类型。

25
1
// ExampleTypeHandler.java 将java类型 String 映射到JDBC类型 VARCHAR
2
@MappedJdbcTypes(JdbcType.VARCHAR)
3
public class ExampleTypeHandler extends BaseTypeHandler<String> {
4

5
  @Override
6
  public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException {
7
    ps.setString(i, parameter);
8
  }
9

10
  @Override
11
  public String getNullableResult(ResultSet rs, String columnName) throws SQLException {
12
    return rs.getString(columnName);
13
  }
14

15
  @Override
16
  public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
17
    return rs.getString(columnIndex);
18
  }
19

20
  @Override
21
  public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
22
    return cs.getString(columnIndex);
23
  }
24
}
25

如果想要这个类型处理器生效，则必须在主配置文件的typehandlers标签进行配置，这样拦截器链才会进行调用。

8
1
<!-- mybatis-config.xml -->
2
<typeHandlers>
3
  <!-- 注册自定义类型处理器 -->
4
  <typeHandler handler="org.mybatis.example.ExampleTypeHandler"/>
5
    
6
    <!-- 也可以使用自动查找类型处理器(注意：此时JDBC 的类型仅能通过注解方式来指定) -->
7
    <!-- <package name="org.mybatis.example"/> -->
8
</typeHandlers>

使用上述的类型处理器将会覆盖已有的处理 Java String 类型的属性以及 VARCHAR 类型的参数和结果的类型处理器。 要注意 MyBatis 不会通过检测数据库元信息来决定使用哪种类型，所以你必须在参数和结果映射中指明字段是 VARCHAR 类型， 以使其能够绑定到正确的类型处理器上。这是因为 MyBatis 直到语句被执行时才清楚数据类型。

通过类型处理器的泛型，MyBatis 可以得知该类型处理器处理的 Java 类型，不过这种行为可以通过两种方法改变：

• 在类型处理器的配置元素（typeHandler 元素）上增加一个 javaType 属性（比如：javaType="String"）；

• 在类型处理器的类上增加一个 @MappedTypes 注解指定与其关联的 Java 类型列表。 如果在 javaType 属性中也同时指定，则注解上的配置将被忽略。

还可以通过两种方式来指定关联的 JDBC 类型：

• 在类型处理器的配置元素上增加一个 jdbcType 属性（比如：jdbcType="VARCHAR"）；

• 在类型处理器的类上增加一个 @MappedJdbcTypes 注解指定与其关联的 JDBC 类型列表。 如果在 jdbcType 属性中也同时指定，则注解上的配置将被忽略。

当在 ResultMap 中决定使用哪种类型处理器时，此时 Java 类型是已知的（从结果类型中获得），但是 JDBC 类型是未知的。 因此 Mybatis 使用 javaType=[Java 类型], jdbcType=null 的组合来选择一个类型处理器。 这意味着使用 @MappedJdbcTypes 注解可以限制类型处理器的作用范围，并且可以确保，除非显式地设置，否则类型处理器在 ResultMap 中将不会生效。 如果希望能在 ResultMap 中隐式地使用类型处理器，那么设置 @MappedJdbcTypes 注解的 includeNullJdbcType=true 即可。 然而从 Mybatis 3.4.0 开始，如果某个 Java 类型只有一个注册的类型处理器，即使没有设置 includeNullJdbcType=true，那么这个类型处理器也会是 ResultMap 使用 Java 类型时的默认处理器。

3. 泛型类型处理器

你可以创建能够处理多个类的泛型类型处理器。为了使用泛型类型处理器， 需要增加一个接受该类的 class 作为参数的构造器，这样 MyBatis 会在构造一个类型处理器实例的时候传入一个具体的类。

10
1
//GenericTypeHandler.java
2
public class GenericTypeHandler<E extends MyObject> extends BaseTypeHandler<E> {
3

4
  private Class<E> type;
5

6
  public GenericTypeHandler(Class<E> type) {
7
    if (type == null) throw new IllegalArgumentException("Type argument cannot be null");
8
    this.type = type;
9
  }
10
  ...

EnumTypeHandler 和 EnumOrdinalTypeHandler 都是泛型类型处理器，我们将会在接下来的部分详细探讨。

若想映射枚举类型 Enum，则需要从 EnumTypeHandler 或者 EnumOrdinalTypeHandler 中选择一个来使用。

• EnumTypeHandler

比如说我们想存储取近似值时用到的舍入模式。默认情况下，MyBatis 会利用 EnumTypeHandler 来把 Enum 值转换成对应的名字。

注意 EnumTypeHandler 在某种意义上来说是比较特别的，其它的处理器只针对某个特定的类，而它不同，它会处理任意继承了 Enum 的类。

• EnumOrdinalTypeHandler

不过，我们可能不想存储名字，相反我们的 DBA 会坚持使用整形值代码。那也一样简单：在配置文件中把 EnumOrdinalTypeHandler 加到 typeHandlers 中即可， 这样每个 RoundingMode 将通过他们的序数值来映射成对应的整形数值。

4
1
<!-- mybatis-config.xml -->
2
<typeHandlers>
3
  <typeHandler handler="org.apache.ibatis.type.EnumOrdinalTypeHandler" javaType="java.math.RoundingMode"/>
4
</typeHandlers>

但要是你想在一个地方将 Enum 映射成字符串，在另外一个地方映射成整形值呢？自动映射器（auto-mapper）会自动地选用 EnumOrdinalTypeHandler 来处理枚举类型， 所以如果我们想用普通的 EnumTypeHandler，就必须要显式地为那些 SQL 语句设置要使用的类型处理器。

16
1
<!-- 在 resultMap 中指定枚举类型处理器 -->
2
<resultMap type="org.apache.ibatis.submitted.rounding.User" id="usermap2">
3
    <id column="id" property="id"/>
4
    <result column="name" property="name"/>
5
    <result column="funkyNumber" property="funkyNumber"/>
6
    <result column="roundingMode" property="roundingMode" 
7
            typeHandler="org.apache.ibatis.type.EnumTypeHandler"/>
8
</resultMap>
9

10
<!-- 在 行内参数映射 指定枚举类型处理器 -->
11
<insert id="insert2">
12
    insert into users2 (id, name, funkyNumber, roundingMode) values (
13
    #{id}, #{name}, #{funkyNumber}, #{roundingMode, typeHandler=org.apache.ibatis.type.EnumTypeHandler}
14
    )
15
</insert>
16

第五节 objectFactory标签

每次 MyBatis 创建结果对象的新实例时，它都会使用一个对象工厂（ObjectFactory）实例来完成实例化工作。 默认的对象工厂需要做的仅仅是实例化目标类，要么通过默认无参构造方法，要么通过存在的参数映射来调用带有参数的构造方法。 如果想覆盖对象工厂的默认行为，可以通过创建自己的对象工厂来实现。比如：

14
1
// ExampleObjectFactory.java
2
public class ExampleObjectFactory extends DefaultObjectFactory {
3
  public Object create(Class type) {
4
    return super.create(type);
5
  }
6
  public Object create(Class type, List<Class> constructorArgTypes, List<Object> constructorArgs) {
7
    return super.create(type, constructorArgTypes, constructorArgs);
8
  }
9
  public void setProperties(Properties properties) {
10
    super.setProperties(properties);
11
  }
12
  public <T> boolean isCollection(Class<T> type) {
13
    return Collection.class.isAssignableFrom(type);
14
  }}

4
1
<!-- mybatis-config.xml -->
2
<objectFactory type="org.mybatis.example.ExampleObjectFactory">
3
  <property name="someProperty" value="100"/>
4
</objectFactory>

ObjectFactory 接口很简单，它包含两个创建实例用的方法，一个是处理默认无参构造方法的，另外一个是处理带参数的构造方法的。 另外，setProperties 方法可以被用来配置 ObjectFactory，在初始化你的 ObjectFactory 实例后， objectFactory 元素体中定义的属性会被传递给 setProperties 方法。

第六节 plugins标签

MyBatis 允许你在映射语句执行过程中的某一点进行拦截调用。默认情况下，MyBatis 允许使用插件来拦截的方法调用包括：

• Executor (update, query, flushStatements, commit, rollback, getTransaction, close, isClosed)

• ParameterHandler (getParameterObject, setParameters)

• ResultSetHandler (handleResultSets, handleOutputParameters)

• StatementHandler (prepare, parameterize, batch, update, query)

这些类中方法的细节可以通过查看每个方法的签名来发现，或者直接查看 MyBatis 发行包中的源代码。 如果你想做的不仅仅是监控方法的调用，那么你最好相当了解要重写的方法的行为。 因为在试图修改或重写已有方法的行为时，很可能会破坏 MyBatis 的核心模块。 这些都是更底层的类和方法，所以使用插件的时候要特别当心。

通过 MyBatis 提供的强大机制，使用插件是非常简单的，只需实现 Interceptor 接口，并指定想要拦截的方法签名即可。

18
1
// ExamplePlugin.java
2
@Intercepts({@Signature(
3
  type= Executor.class,
4
  method = "update",
5
  args = {MappedStatement.class,Object.class})})
6
public class ExamplePlugin implements Interceptor {
7
  private Properties properties = new Properties();
8
  public Object intercept(Invocation invocation) throws Throwable {
9
    // implement pre processing if need
10
    Object returnObject = invocation.proceed();
11
    // implement post processing if need
12
    return returnObject;
13
  }
14
  public void setProperties(Properties properties) {
15
    this.properties = properties;
16
  }
17
}
18

6
1
<!-- mybatis-config.xml -->
2
<plugins>
3
  <plugin interceptor="org.mybatis.example.ExamplePlugin">
4
    <property name="someProperty" value="100"/>
5
  </plugin>
6
</plugins>

上面的插件将会拦截在 Executor 实例中参数匹配的 “update” 方法调用， 这里的 Executor 是负责执行底层映射语句的内部对象。

案例：下面是一个统计SQL执行时间的插件

53
1
/**
2
 * Mybatis SQL拦截器,记录每个sqlId对应的执行时间
3
 *
4
 * @author huangyuanxin
5
 * @date 2021-07-30
6
 */
7
@Intercepts(value = {
8
        @Signature(type = Executor.class, method = "update", args = {MappedStatement.class, Object.class}),
9
        @Signature(type = Executor.class, method = "query", args = {MappedStatement.class, Object.class,
10
                RowBounds.class, ResultHandler.class}),
11
        @Signature(type = Executor.class, method = "query", args = {MappedStatement.class, Object.class,
12
                RowBounds.class, ResultHandler.class, CacheKey.class, BoundSql.class})})
13
public class MyBatisExcutorInterceptor implements Interceptor {
14
    @Override
15
    public Object intercept(Invocation invocation) {
16
        // 获取参数传入的MappedStatement
17
        MappedStatement mappedStatement = (MappedStatement) invocation.getArgs()[0];
18

19
        // 获取MappedStatementId ==> com.**.dao.**Dao.selectByPrimaryKey
20
        String sqlId = mappedStatement.getId();
21

22
        // 记录开始时间
23
        long start = System.currentTimeMillis();
24

25
        try {
26
            // 放行
27
            return invocation.proceed();
28
        } catch (Exception e) {
29
            // SQL执行出现异常
30
            System.out.println(sqlId + "执行失败！");
31
            return null;
32
        } finally {
33
            // 结束时间
34
            long time = System.currentTimeMillis() - start;
35

36
            // 输出到控制台 或 打印日志
37
            System.out.println(sqlId + "：cost time " + time + " ms");
38
        }
39
    }
40

41
    @Override
42
    public Object plugin(Object arg0) {
43
        // JDK动态代码，InvocationHandler为Plugin
44
        // Plugin拦截行为为调用被代理对象的intercept方法
45
        // 多个MyBatis拦截器则会被多次动态代理，包装多次！
46
        return Plugin.wrap(arg0, this);
47
    }
48

49
    @Override
50
    public void setProperties(Properties arg0) {
51
        // NULL 该拦截器不支持配置属性
52
    }
53
}

提示 覆盖配置类也可以修改mybatis的核心行为

除了用插件来修改 MyBatis 核心行为以外，还可以通过完全覆盖配置类来达到目的。只需继承配置类后覆盖其中的某个方法，再把它传递到 SqlSessionFactoryBuilder.build(myConfig) 方法即可。再次重申，这可能会极大影响 MyBatis 的行为，务请慎之又慎。

第七节 environments 标签

1. 配置 environment

environments 标签定义了 SQL 执行环境相关的配置，并且支持多个 environment 子标签的定义。

16
1
<environments default="development">
2
  <!--开发环境：development-->
3
  <environment id="development">
4
    <transactionManager type="JDBC">
5
      <property name="..." value="..."/>
6
    </transactionManager>
7
    <dataSource type="POOLED">
8
      <property name="driver" value="${driver}"/>
9
      <property name="url" value="${url}"/>
10
      <property name="username" value="${username}"/>
11
      <property name="password" value="${password}"/>
12
    </dataSource>
13
  </environment>
14
    
15
  <!-- 其他 environment 子标签-->
16
</environments>