MyBatis 配置文件 - LD's BLOG

MyBatis 需要配置文件，通常使用 mybatis-config.xml 进行配置。

一个最简单的配置文件样例：

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
        PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="数据库驱动类名"/>
                <property name="url" value="url"/>
                <property name="username" value="用户名"/>
                <property name="password" value="密码"/>
            </dataSource>
        </environment>
    </environments>
</configuration>

一、属性（properties）

1. 属性标签

在 xml 文件中，有诸多属性标签，它们用于配置属性信息。

例如：

<dataSource type="POOLED">
    <property name="driver" value="数据库驱动类名"/>
    <property name="url" value="url"/>
    <property name="username" value="用户名"/>
    <property name="password" value="密码"/>
</dataSource>

填写属性标签的值，一共有四种做法：

做法 1：写死

1 2	`<property name="username" value="用户名"/> <property name="password" value="密码"/>`

做法 2：写死，将属性写在 properties 内，通过 ${属性名} 读取属性值

<properties>
	<property name="username" value="用户名"/>
	<property name="password" value="密码"/>
</properties>

···

<property name="username" value="${username}"/>
<property name="password" value="${password}"/>

做法 3：将属性写在 properties 文件，通过 ${属性名} 读取属性值

<properties resource="···/config.properties">
</properties>

···

<property name="username" value="${username}"/>
<property name="password" value="${password}"/>

做法 4：在创建 SqlSessionFactory 实例时传入属性，通过 ${属性名} 读取属性值

1	`SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(resourceInputStream, props);`

2. 使用方式

<!--将属性值写在Java代码中-->

<properties resource="···/config.properties">  <!--将属性值写在文件中-->
	<property name="属性名" value="属性值"/>  <!--将属性值写在子标签中-->
</properties>

···

<property name="username" value="${属性名}"/>  <!--读取属性值-->

3. 优先级

MyBatis 将按照下面的顺序来加载：

首先读取写在 properties 内的属性
然后读取 properties 文件中的属性
最后读取创建 SqlSessionFactory 实例时传入的属性

需要注意的是，在此过程中，后读取的属性会覆盖之前的属性。因此，创建 SqlSessionFactory 实例时传入的属性具有最高优先级，properties 文件中的属性次之，最低优先级的则是写在 properties 内的属性。

4. 默认值

从 MyBatis 3.4.2 开始，可以为属性占位符设置默认值，如果没有配置该属性，则引用默认值。

具体做法如下：

在 properties 中添加特殊属性如下，开启默认值特性
1
<property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/>
默认值特性默认关闭，需要配置特殊属性后才会开启
在读取属性值处，增加 : 和默认值，当属性值未定义时，便会自动赋默认值
1
<property name="password" value="${password:root}"/>

需要注意的是：

如果开启了默认值特性，且属性名中带 : 或 SQL 语句中使用了 : ，便需要再另外增加一个特殊属性，用于修改默认值所使用的字符。
1
2
<property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/>
<property name="org.apache.ibatis.parsing.PropertyParser.default-value-separator" value="符号"/>
使用修改后的符号分隔属性名和默认值
1
<property name="password" value="${password符号root}"/>

二、设置（settings）

1. 使用方式

1
2
3

<settings>
  <setting name="设置名" value="设置值"/>
</settings>

2. 所有设置

设置名	描述	有效值	默认值
cacheEnabled	全局性地开启或关闭所有映射器配置文件中已配置的任何缓存。	true \| false	true
lazyLoadingEnabled	延迟加载的全局开关。当开启时，所有关联对象都会延迟加载。特定关联关系中可通过设置 `fetchType` 属性来覆盖该项的开关状态。	true \| false	false
aggressiveLazyLoading	开启时，任一方法的调用都会加载该对象的所有延迟加载属性。否则，每个延迟加载属性会按需加载（参考 `lazyLoadTriggerMethods`)。	true \| false	false （在 3.4.1 及之前的版本中默认为 true）
multipleResultSetsEnabled	是否允许单个语句返回多结果集（需要数据库驱动支持）。	true \| false	true
useColumnLabel	使用列标签代替列名。实际表现依赖于数据库驱动，具体可参考数据库驱动的相关文档，或通过对比测试来观察。	true \| false	true
useGeneratedKeys	允许 JDBC 支持自动生成主键，需要数据库驱动支持。如果设置为 true，将强制使用自动生成主键。尽管一些数据库驱动不支持此特性，但仍可正常工作（如 Derby）。	true \| false	False
autoMappingBehavior	指定 MyBatis 应如何自动映射列到字段或属性。 NONE 表示关闭自动映射；PARTIAL 只会自动映射没有定义嵌套结果映射的字段。 FULL 会自动映射任何复杂的结果集（无论是否嵌套）。	NONE, PARTIAL, FULL	PARTIAL
autoMappingUnknownColumnBehavior	指定发现自动映射目标未知列（或未知属性类型）的行为。`NONE`: 不做任何反应`WARNING`: 输出警告日志（`'org.apache.ibatis.session.AutoMappingUnknownColumnBehavior'` 的日志等级必须设置为 `WARN`）`FAILING`: 映射失败 (抛出 `SqlSessionException`)	NONE, WARNING, FAILING	NONE
defaultExecutorType	配置默认的执行器。SIMPLE 就是普通的执行器；REUSE 执行器会重用预处理语句（PreparedStatement）； BATCH 执行器不仅重用语句还会执行批量更新。	SIMPLE REUSE BATCH	SIMPLE
defaultStatementTimeout	设置超时时间，它决定数据库驱动等待数据库响应的秒数。	任意正整数	未设置 (null)
defaultFetchSize	为驱动的结果集获取数量（fetchSize）设置一个建议值。此参数只可以在查询设置中被覆盖。	任意正整数	未设置 (null)
defaultResultSetType	指定语句默认的滚动策略。（新增于 3.5.2）	FORWARD_ONLY \| SCROLL_SENSITIVE \| SCROLL_INSENSITIVE \| DEFAULT（等同于未设置）	未设置 (null)
safeRowBoundsEnabled	是否允许在嵌套语句中使用分页（RowBounds）。如果允许使用则设置为 false。	true \| false	False
safeResultHandlerEnabled	是否允许在嵌套语句中使用结果处理器（ResultHandler）。如果允许使用则设置为 false。	true \| false	True
mapUnderscoreToCamelCase	是否开启驼峰命名自动映射，即从经典数据库列名 A_COLUMN 映射到经典 Java 属性名 aColumn。	true \| false	False
localCacheScope	MyBatis 利用本地缓存机制（Local Cache）防止循环引用和加速重复的嵌套查询。默认值为 SESSION，会缓存一个会话中执行的所有查询。若设置值为 STATEMENT，本地缓存将仅用于执行语句，对相同 SqlSession 的不同查询将不会进行缓存。	SESSION \| STATEMENT	SESSION
jdbcTypeForNull	当没有为参数指定特定的 JDBC 类型时，空值的默认 JDBC 类型。某些数据库驱动需要指定列的 JDBC 类型，多数情况直接用一般类型即可，比如 NULL、VARCHAR 或 OTHER。	JdbcType 常量，常用值：NULL、VARCHAR 或 OTHER。	OTHER
lazyLoadTriggerMethods	指定对象的哪些方法触发一次延迟加载。	用逗号分隔的方法列表。	equals,clone,hashCode,toString
defaultScriptingLanguage	指定动态 SQL 生成使用的默认脚本语言。	一个类型别名或全限定类名。	org.apache.ibatis.scripting.xmltags.XMLLanguageDriver
defaultEnumTypeHandler	指定 Enum 使用的默认 `TypeHandler` 。（新增于 3.4.5）	一个类型别名或全限定类名。	org.apache.ibatis.type.EnumTypeHandler
callSettersOnNulls	指定当结果集中值为 null 的时候是否调用映射对象的 setter（map 对象时为 put）方法，这在依赖于 Map.keySet() 或 null 值进行初始化时比较有用。注意基本类型（int、boolean 等）是不能设置成 null 的。	true \| false	false
returnInstanceForEmptyRow	当返回行的所有列都是空时，MyBatis默认返回 `null`。当开启这个设置时，MyBatis会返回一个空实例。请注意，它也适用于嵌套的结果集（如集合或关联）。（新增于 3.4.2）	true \| false	false
logPrefix	指定 MyBatis 增加到日志名称的前缀。	任何字符串	未设置
logImpl	指定 MyBatis 所用日志的具体实现，未指定时将自动查找。	SLF4J \| LOG4J \| LOG4J2 \| JDK_LOGGING \| COMMONS_LOGGING \| STDOUT_LOGGING \| NO_LOGGING	未设置
proxyFactory	指定 Mybatis 创建可延迟加载对象所用到的代理工具。	CGLIB \| JavaSSIST	JavaSSIST （MyBatis 3.3 以上）
vfsImpl	指定 VFS 的实现	自定义 VFS 的实现的类全限定名，以逗号分隔。	未设置
useActualParamName	允许使用方法签名中的名称作为语句参数名称。为了使用该特性，你的项目必须采用 Java 8 编译，并且加上 `-parameters` 选项。（新增于 3.4.1）	true \| false	true
configurationFactory	指定一个提供 `Configuration` 实例的类。这个被返回的 Configuration 实例用来加载被反序列化对象的延迟加载属性值。这个类必须包含一个签名为`static Configuration getConfiguration()` 的方法。（新增于 3.2.3）	一个类型别名或完全限定类名。	未设置
shrinkWhitespacesInSql	从SQL中删除多余的空格字符。请注意，这也会影响SQL中的文字字符串。 (新增于 3.5.5)	true \| false	false
defaultSqlProviderType	Specifies an sql provider class that holds provider method (Since 3.5.6). This class apply to the `type`(or `value`) attribute on sql provider annotation(e.g. `@SelectProvider`), when these attribute was omitted.	A type alias or fully qualified class name	Not set

三、类型别名（typeAliases）

1. 作用

为 Java 类设置一个短的名字
减少全限定类名的重复书写
一旦设置后，可以在 MyBatis 中用别名来替代全限定类名

2. 使用方式

(1) 选择类

1
2
3

<typeAliases>
  <typeAlias alias="别名" type="全限定类名"/>
</typeAliases>

MyBatis 会根据全限定类名寻找类，并给它指定别名。

(2) 选择包

1
2
3

<typeAliases>
  <package name="包名"/>
</typeAliases>

MyBatis 会搜索包下的类，并为它们指定别名，别名默认为首字母小写的类名。

例如 UserMapper 类的别名将默认为 userMapper

可以通过注解的方式为类指定别名，注解指定的别名将替代默认值。

@Alias("别名")
public class 类名 {
    ...
}

四、环境配置（environments）

1. 多种环境

Mybatis 可以设置多种环境，并为每个环境单独配置。

例如：设置开发、测试和生产三个环境，在不同的环境中连接不同的数据库、使用不同的 SQL 映射

需要注意的是，尽管可以设置多个环境，但每个 SqlSessionFactory 实例只能选择一个环境。

如果需要同时启用多个环境，或同时连接多个数据库，便需要创建多个实例。

2. environments

<environments default="默认环境">

    <environment id="development">
		···
    </environment>
    
    <environment id="Test">
		···
    </environment>
    
    <environment id="production">
		···
    </environment>
    
</environments>

使用 default 属性指定默认情况下使用的环境。

如果需要指定环境，需要在创建 SqlSessionFactory 实例时传入参数：

1	`sqlSessionFactory = new SqlSessionFactoryBuilder().build(resourceInputStreamStream, 环境名);`

3. environment

<environment id="development">
    <transactionManager type="JDBC"/>
    <dataSource type="POOLED">
        <property name="driver" value="数据库驱动类名"/>
        <property name="url" value="url"/>
        <property name="username" value="用户名"/>
        <property name="password" value="密码"/>
    </dataSource>
</environment>

(1) id

用于唯一标识每一个环境

(2) 事务管理器（transactionManager）

事务管理器，有 JDBC 和 MANAGED 两种

如果使用 Spring + MyBatis，则没有必要配置事务管理器，因为 Spring 模块会使用自带的管理器来覆盖前面的配置

(3) 数据源（dataSource）

使用 type 指定数据源的类型
- UNPOOLED：不使用连接池，每次请求都会打开和关闭连接
- POOLED：默认，使用连接池
- JNDI：用于 EJB 或应用服务器
使用 property 配置数据库的连接信息

五、映射器（mappers）

1. SQL 映射

可以使用 XxxMapper.xml 映射文件来建立接口中抽象方法与 SQL 语句的映射关系，mappers 标签用于注册映射文件。

2. 使用方式

<mappers>
  <!--路径-->
  <mapper resource="···/XxxMapper.xml"/>
  
  <!--url，不推荐使用-->
  <mapper url="file:///···/AuthorMapper.xml"/>
  
  <!--全限定类名-->
  <mapper class="全限定类名"/>
  
  <!--包，包下的映射文件都将被注册-->
  <package name="包"/>
  
</mappers>

六、其它

详见官方文档。

参考

MyBatis 3 | 官方文档

开发 JAVA 持久层 MyBatis

MyBatis 生命周期和作用域上一篇

MyBatis 简单使用下一篇