MyBatis全局配置详解

全局配置详解

配置文件结构

MyBatis全局配置文件包含了会深深影响MyBatis行为的设置和属性信息,配置文件使用xml文档进行配置,其文档结构如下：

• configuration(根元素)
  • properties(属性变量)
    • property
  • settings(设置)
    • setting
  • typeAliases(类型别名)
    • typeAlias
    • package
  • plugins(插件)
    • plugin
      • property
  • objectFactory(对象工厂)
    • property
  • objectWrapperFactory(对象包装器工厂)
  • reflectorFactory(反射器工厂)
  • environments(环境变量)
    • environment
      • transactionManager
        • property
      • dataSource
        • property
  • databaseIdProvider(数据库厂商)
    • property
  • typeHandlers(类型处理器)
    • typeHandler
  • mappers(SQL映射)
    • mapper
    • package

MyBatis在解析这些元素的过程中,大至上会按照顺序解析完后封装保存到configuration对象中。

properties元素

在properties中可以定义应用程序或者MyBatis需要使用到的变量信息,比如数据库连接信息等。properties元素是MyBatis最先解析的一个元素。可以通过类路径resource或网络路径url属性指定外部属性文件加载属性信息,也可以通过properties的子元素property进行定义，可以只是用一种方式定义属性,也可以同时使用两种方式(resource和property或url和property，resource和url不能同时使用)进行定义。定义属性时，如果属性重复定义，前面定义的属性值将被覆盖,属性的值将以后面定义的为准。一个简单的示例如下

其中,使用resource属性指定加载当前资源目录下的db.properties文件,比如db.properties的内容如下

jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://192.168.101.28:3306/mybatis?characterEncoding=utf8
jdbc.username=mybatis
jdbc.password=123456
user.name=sqcheng
user.password=20200111

上面的例子中使用了resource加载外部属性文件的同时,也使用了propety子元素定义了一些属性,部分property元素的value中还使用了占位符${}引用其它的属性。以上例子中,会发现jdbc.username和jdbc.password属性被重复定义了(在db.properties和property元素),这种情况下,相同属性名的属性将会出现覆盖。MyBatis按照下面的顺序来读取属性信息

• 首先读取properties元素体内的property属性
• 然后读取properties元素中的resource或url属性指定的属性文件，并覆盖已读取的同名属性
• 最后读取作为方法参数传递的属性，并覆盖已读取的同名属性

从这个顺序可以了解,以上例子中使用property定义的jdbc.username和jdbc.password将会被db.properties属性文件中定义的jdbc.username和jdbc.password覆盖。另外,username和password分别引用了user.name和user.password。MyBatis解析完成后的最终结果如下

jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://192.168.101.28:3306/mybatis?characterEncoding=utf8
jdbc.username=mybatis
jdbc.password=123456
user.name=sqcheng
user.password=20200111
username=sqcheng
password=20200111
otherPropertyName=otherPropertyValue

settings元素

这是MyBatis中极为重要的调整设置，它们会改变MyBatis的运行时行为。MyBatis提供了非常多的配置项,总共有28项之多,下表比较常接触到的一些设置项、默认值及其描述

设置项	描述	取值范围	默认值
cacheEnabled	缓存开关(全局),开启或关闭配置文件中的所有映射器已经配置的缓存。	true | false	true
lazyLoadingEnabled	延迟加载开关(全局)。开启时，所有关联对象都会延迟加载。	true | false	false
lazyLoadTriggerMethods	指定对象的哪个方法触发一次延迟加载。	用逗号分隔的方法列表	equals,clone,hashCode,toString
defaultExecutorType	缺省执行器。SIMPLE 就是普通的执行器；REUSE 执行器会重用预处理语句（prepared statements）； BATCH 执行器将重用语句并执行批量更新。	SIMPLE | REUSE | BATCH	SIMPLE
defaultStatementTimeout	设置超时时间，它决定驱动等待数据库响应的秒数。	任意正整数	null(未设置)
defaultFetchSize	查询结果最大记录数	任意正整数	null(未设置)
localCacheScope	本地缓存（一级缓存）作用域或生命周期。 默认值为 SESSION，这种情况下会缓存一个会话中执行的所有查询。 若设置值为 STATEMENT，本地会话仅用在语句执行上，对相同 SqlSession 的不同调用将不会共享数据。	SESSION | STATEMENT	SESSION
defaultScriptingLanguage	指定动态 SQL 生成的默认语言。	一个类型别名或完全限定类名。	org.apache.ibatis.scripting.xmltags.XMLLanguageDriver
logImpl	指定 MyBatis 所用日志的具体实现，未指定时将自动查找,未查找到将关闭日志。	SLF4J | LOG4J | LOG4J2 | JDK_LOGGING | COMMONS_LOGGING | STDOUT_LOGGING | NO_LOGGING	未设置
proxyFactory	指定 Mybatis 创建具有延迟加载能力的对象所用到的代理工厂。	CGLIB | JAVASSIST	JAVASSIST （MyBatis 3.3+）

用到比较多的如数据库查询或执行超时等待时长defaultStatementTimeout、一级缓存声生命周期localCacheScope、日志logImpl等,很多设置MyBatis已经提供的默认的配置,甚至可以零配置。更多的设置可以参考Mybatis官方网站
。以下是官网提供的一个完整的settings配置示例

typeAliases元素

类型别名是为Java类型设置一个短的名字，配置之后,在各个XML文件中原来需要使用完全限定名的地方，可以改为使用较短的别名，用来减少类完全限定名的冗余。Mybatis默认提供或内置了很多类型别名，包括JAVA中8种基本类型、String类型、集合类型(Conllection)、数组,以及事务管理器工厂、数据源工厂等类型别名。

类型别名可以通过package或typeAlias元素进行定义,下面是一个简单示例

以上例子中,typeAlias元素的type属性指定Java类型的完全限定名,alias属性定义别名。package元素的name属性指定了一个包路径,MyBatis将扫描该包路径下的JavaBean,在没有注解的情况下，会使用 Bean 的简单类名小写来作为它的别名。假设该包下有一个BookMark类即com.fandou.sqlmapper.mapper.book.BookMark,在没有注解的情况下,其类型别名为bookmark；如果在BookMark类上加了别名注解如

@Alias("Book")
public class BookMark implements Serializable {
    ...
}

将使用注解的名字Book小写后的book作为别名,即使这里使用了首字母大写进行了注解。类型别名解析后,会被注册到configuration对象持有的类型别名注册表中,注册时,如果该别名已经被其它类型注册，解析过程将会抛出异常，即一个别名不允许被多个类型注册,但一个类型可以注册多个别名。
如果typeAlias元素的没有配置alias属性和Javabean没有添加@Alias注解的情况时一样的,都会使用简单类名小写被注册到类型别名注册表中。

通过测试或查看MyBatis的源码,实际上,所有类型别名都会被转为小写后再注册到类型别名注册表中,即类型别名不区分大小写,大写小写都一样,都会被认为是同一个类型,所以,最佳的做法是,在配置或引用类型别名的时候,统一使用小写。

Mybatis默认提供或内置了的Java类型别名见下表,一共有27种,其中基本类型和其包装类被注册为不同类型

别名	映射的类型
_byte	byte
_long	long
_short	short
_int	int
_integer	int
_double	double
_float	float
_boolean	boolean
string	String
byte	Byte
long	Long
short	Short
int	Integer
integer	Integer
double	Double
float	Float
boolean	Boolean
date	Date
decimal	BigDecimal
bigdecimal	BigDecimal
object	Object
map	Map
hashmap	HashMap
list	List
arraylist	ArrayList
collection	Collection
iterator	Iterator

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提供的强大机制，使用插件是非常简单的，只需实现Interceptor接口，并指定想要拦截的方法签名即可。接着在plugins元素声明实现的插件即可。比如想要监控某条查询语句的消耗的时间,可以监控Executor接口的query方法

 List query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler) throws SQLException;

首先,创建一个插件TimeCounterPlugin,使用@Intercepts注解声明一个拦截器,然后使用@Signature注解拦截的接口和方法签名信息，包括拦截的接口类型type、方法method、方法的参数args等,TimeCounterPlugin实现类大致如下

package com.fandou.sqlmapper;

import java.lang.reflect.Method;
import java.util.Properties;
import java.util.Set;

import org.apache.ibatis.executor.Executor;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.plugin.Interceptor;
import org.apache.ibatis.plugin.Intercepts;
import org.apache.ibatis.plugin.Invocation;
import org.apache.ibatis.plugin.Signature;
import org.apache.ibatis.session.ResultHandler;
import org.apache.ibatis.session.RowBounds;

@Intercepts({ @Signature(type = Executor.class, method = "query", args = { MappedStatement.class, Object.class,
        RowBounds.class, ResultHandler.class }) })
public class TimeCounterPlugin implements Interceptor {

    // 可以额外配置一些属性
    private Properties properties = new Properties();

    /**
     * 拦截Executor接口的query方法
     */
    public Object intercept(Invocation invocation) throws Throwable {

        System.out.println(" 通过插件元素配置的属性 => ");
        Set propertyNames = properties.stringPropertyNames();
        for (String key : propertyNames) {
            System.out.println("   " + key + " => " + properties.getProperty(key));
        }

        //配置一些属性控制插件开关和打印结果
        boolean startup = Boolean.valueOf(properties.getProperty("startup"));
        boolean printResult = Boolean.valueOf(properties.getProperty("printResult"));

        long start = 0L;
        long end = 0L;

        //如果开启了插件
        if (startup) {
            Object executor = invocation.getTarget();
            Method method = invocation.getMethod();
            Object[] args = invocation.getArgs();

            System.out.println(" 拦截的接口类型 => " + executor.getClass().getTypeName());
            System.out.println(" 拦截的方法名 => " + method.getName());
            System.out.println(" 拦截的方法参数信息 => ");
            for (Object object : args) {
                //参数可能为null
                if(null == object) {
                    System.out.println("   => null");
                }
                else {
                    System.out.println("   => " + object.getClass().getTypeName());
                }
            }

            // query方法执行前
            start = System.currentTimeMillis();
        }

        // 执行方法
        Object returnObject = invocation.proceed();

        //如果开启了插件
        if (startup) {
            // query方法执行后
            end = System.currentTimeMillis();

            System.out.println(" 执行查询消耗的时间 => " + ((end - start)) + " 毫秒...");

            //如果配置了打印结果属性
            if(printResult) {
                System.out.println(" returnObject => " + returnObject);
            }
        }

        // 返回执行结果
        return returnObject;
    }

    public void setProperties(Properties properties) {
        this.properties = properties;
    }
}

接着在全局配置文件plugins元素中声明插件plugin

plugin元素的interceptor属性值为插件的完全限定名,可以按照需求自定添加一些属性,如例子定义了开关以及是否打印查询结果的控制。编写测试,正常将会输出如下内容

通过插件元素配置的属性 =>
  printResult => true
  startup => true
拦截的接口类型 => org.apache.ibatis.executor.CachingExecutor
拦截的方法名 => query
拦截的方法参数信息 =>
  => org.apache.ibatis.mapping.MappedStatement
  => com.fandou.sqlmapper.mapper.User
  => org.apache.ibatis.session.RowBounds
  => null
执行查询消耗的时间 => 32 毫秒...
returnObject => [User [id=3, username=sqcheng, password=$2a$10$.SyCzQodO1Qy0kQh31UfOOeF4Z.YEAHEq/dJtoOWpneq.wDLimET2, address=广东连州, identityCard=null, books=null], User [id=4, username=chengshangqian, password=$2a$10$VCk3NUj3cZZPtxOk2tODcesbtY33GPRijCQMEyYSzSnLiYOdX8jGa, address=连州市西江镇, identityCard=null, books=null]]

objectFactory、objectWrapperFactory、reflectorFactory三个工厂元素

MyBatis每次创建结果对象的新实例时，它都会使用一个对象工厂（ObjectFactory）实例来完成。 默认的对象工厂需要做的仅仅是实例化目标类，要么通过默认构造方法，要么在参数映射存在的时候通过参数构造方法来实例化。如果想覆盖对象工厂的默认行为，开发人员可以通过创建自己的对象工厂,然后在objectFactory元素中配置指定使用新建的工厂对象类型来实现。比如：

public class MyObjectFactory extends DefaultObjectFactory {
  public Object create(Class type) {
    return super.create(type);
  }

  public Object create(Class type, List constructorArgTypes, List