Mybatis配置说明

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

• properties(属性)
• settings(设置)
• typeAliases(类型别名)
• typeHandlers(类型处理器)
• objectFactory(对象工厂)
• plugins(插件)

• environments(环境配置)

  environment（环境变量）
  - transactionManager（事务管理器）
  - dataSource（数据源）

• databaseIdProvider(数据厂商标识)
• mappers(映射器)

  1.properties(属性)

  mybatis支持从外部获取文件读取属性并可以动态的替换。你即可以在典型的 Java 属性文件中配置这些属性,也可以在properties标签的子元素中设置。

1.1 properties标签定义属性

<?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>
      <!-- 在properties中定义一组属性 -->
    <properties>
      <!-- property标签用于定义一个属性,name表示定义属性的名称,value则是定义属性的属性值 -->
      <property name="driver" value="com.mysql.cj.jdbc.Driver"/>
      <property name="url" value="jdbc:mysql://localhost:3306/test?useUnicode=true&amp;characterEncoding=utf8&amp;serverTimezone=UTC&amp;allowMultiQueries=true"/>
      <property name="username" value="root"/>
      <property name="password" value="123456"/>
      </properties>
      <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <!-- 使用在properties配置好的属性替换动态属性值 -->
                <property name="driver" value="${driver}"/>
                <property name="url" value="${url}"/>
                <property name="username" value="${username}"/>
                <property name="password" value="${password}"/>
            </dataSource>
        </environment>
    </environments>
    <mappers>
        <!-- 指定xml Mapper -->
        <mapper resource="mapper/studentMapper.xml"/>
    </mappers>
</configuration>

获取SqlSessionFactory的方式还是跟第一节一样。

InputStream stream = Resources.getResourceAsStream("mybatis.xml");
SqlSessionFactory factory=new SqlSessionFactoryBuilder().build(stream);

1.2 properties标签引入外部资源

properties标签可以通过resource属性引入外部资源,获取SqlSessionFactory的方式跟上面是一样的。

<?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>
      <!-- 使用resource属性引入src/main/resources目录下的config.properties文件 -->
    <properties resource="config.properties"/>
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <!-- 使用在properties配置好的属性替换动态属性值 -->
                <property name="driver" value="${driver}"/>
                <property name="url" value="${url}"/>
                <property name="username" value="${username}"/>
                <property name="password" value="${password}"/>
            </dataSource>
        </environment>
    </environments>
    <mappers>
        <!-- 指定xml Mapper -->
        <mapper resource="mapper/studentMapper.xml"/>
    </mappers>
</configuration>

src/main/resources/config.properties内容如下:

username=root
password=123456
driver=com.mysql.cj.jdbc.Driver
url=jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=utf8&serverTimezone=UTC&allowMultiQueries=true

1.3 定义单独的配置文件,不使用properties标签

我们可以单独提取一个配置文件,并且可以不使用properties标签配置属性,而是在构建SqlSessionFactory的时候传入我们定义好的配置。下面的mybatis.xml就没有使用properties标签配置属性,而是在构建SqlSessionFactory的时候传入我们定义好的配置。

<?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">
                <!-- 使用在properties配置好的属性替换动态属性值 -->
                <property name="driver" value="${driver}"/>
                <property name="url" value="${url}"/>
                <property name="username" value="${username}"/>
                <property name="password" value="${password}"/>
            </dataSource>
        </environment>
    </environments>
    <mappers>
        <!-- 指定xml Mapper -->
        <mapper resource="mapper/studentMapper.xml"/>
    </mappers>
</configuration>

构建SqlSessionFactory的时候传入我们定义好的配置,SqlSessionFactory是依靠实例化一个SqlSessionFactoryBuilder对象然后调用build()得到一个SqlSessionFactory对象,build()有好个重载方法可以传入Properties对象:

• build(Reader reader, Properties properties)
• build(Reader reader, String environment, Properties properties)
• build(InputStream inputStream, Properties properties)
• build(Reader reader, String environment, Properties properties)

方式1:通过读取外部配置文件一个InputStream,通过properties.load()加载一个输入流。这种方式一般是获取外部配置文件。

InputStream inputStream = Resources.getResourceAsStream("config.properties");
Properties properties=new Properties();
//properties加载一个输入流
properties.load(inputStream);
SqlSessionFactory factory=new SqlSessionFactoryBuilder().build(stream,properties);

方式2:创建Properties并设置对应的属性和属性值

Properties properties=new Properties();
properties.setProperty("driver","com.mysql.cj.jdbc.Driver");
properties.setProperty("url","jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=utf8&serverTimezone=UTC&allowMultiQueries=true");
properties.setProperty("username","root");
properties.setProperty("password","123456");
SqlSessionFactory factory=new SqlSessionFactoryBuilder().build(stream,properties);

1.4 多个地方配置了属性

配置属性的方式有很多种,例如使用properties标签中的property标签配置属性、通过resouce属性引入外部配置,
通过构建SqlSessionFactory时往build()传入参数。MyBatis 将按照下面的顺序来加载:
(1).首先读取在 properties 元素体内指定的属性。
(2).然后根据 properties 元素中的 resource 属性读取类路径下属性文件，或根据 url 属性指定的路径读取属性文件，并覆盖之前读取过的同名属性。
(3).最后读取作为方法参数传递的属性，并覆盖之前读取过的同名属性。

它们的优先级为:通过构建SqlSessionFactory时往build()传入参数 > 通过resouce属性引入外部配置 > 使用properties标签中的property标签配置属性。

1.5 属性默认值
从 MyBatis 3.4.2 开始,你可以为占位符指定一个默认值,例如:

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

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

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

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

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

使用:

<dataSource type="POOLED">
  <property name="username" value="${db:username?:root}"/>
</dataSource>

2.settings(设置)

settings是MyBatis 中极为重要的调整设置,它们会改变 MyBatis 的运行时行为。

一个配置完整的 settings 元素的示例如下:

<settings>
  <setting name="cacheEnabled" value="true"/>
  <setting name="lazyLoadingEnabled" value="true"/>
  <setting name="multipleResultSetsEnabled" value="true"/>
  <setting name="useColumnLabel" value="true"/>
  <setting name="useGeneratedKeys" value="false"/>
  <setting name="autoMappingBehavior" value="PARTIAL"/>
  <setting name="autoMappingUnknownColumnBehavior" value="WARNING"/>
  <setting name="defaultExecutorType" value="SIMPLE"/>
  <setting name="defaultStatementTimeout" value="25"/>
  <setting name="defaultFetchSize" value="100"/>
  <setting name="safeRowBoundsEnabled" value="false"/>
  <setting name="mapUnderscoreToCamelCase" value="false"/>
  <setting name="localCacheScope" value="SESSION"/>
  <setting name="jdbcTypeForNull" value="OTHER"/>
  <setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString"/>
</settings>

3.typeAliases(类型别名)

在上一节的例子中,select、insert、delete、update传入pojo对象或返回类型为pojo对象,我们都需要指定
resultType或parameterType属性的类型,例如:resultType=”com.fly.entity.Student”、parameterType=”com.fly.entity.Student”。这样的写法太冗余了,mybatis提供了typeAliases意在降低冗余的全限定类名书写,例如:

<typeAliases>
  <typeAlias alias="Student" type="com.fly.entity.Student"/>
  <typeAlias alias="Author" type="domain.blog.Author"/>
  <typeAlias alias="Blog" type="domain.blog.Blog"/>
  <typeAlias alias="Comment" type="domain.blog.Comment"/>
  <typeAlias alias="Post" type="domain.blog.Post"/>
  <typeAlias alias="Section" type="domain.blog.Section"/>
  <typeAlias alias="Tag" type="domain.blog.Tag"/>
</typeAliases>

这样配置之后,Student可以用在任何使用com.fly.entity.Student的地方,针对第一章xml Mapper如下:

<!--  原来的
<insert id="addStudent" parameterType="com.fly.entity.Student">
        insert into student(stuName,stuNo,age,sex,address,birthday) values(#{stuName},
        #{stuNo},#{age},#{sex},#{address},#{birthday});
</insert> 

<select id="queryStudentById" parameterType="java.lang.Integer" resultType="Student">
        select <include refid="student_sql"/> from student where sid=#{id};
</select>
-->
<insert id="addStudent" parameterType="com.fly.entity.Student">
        insert into student(stuName,stuNo,age,sex,address,birthday) values(#{stuName},
        #{stuNo},#{age},#{sex},#{address},#{birthday});
</insert> 

<select id="queryStudentById" parameterType="java.lang.Integer" resultType="Student">
        select <include refid="student_sql"/> from student where sid=#{id};
</select>

也可以指定一个包名,MyBatis 会在包名下面搜索需要的 Java Bean,在没有注解的情况下，会使用 Bean 的首字母小写的非限定类名来作为它的别名,比如com.fly.entity.Student的别名是student,如果有注解则别名为注解值。

<typeAliases>
  <package name="com.fly.entity"/>
</typeAliases>

也可以使用注解的方式指定类型别名:

@Alias("student")
public class Student{
    //...
}

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

4.environments(环境配置)

MyBatis 可以配置成适应多种环境，这种机制有助于将 SQL 映射应用于多种数据库之中， 现实情况下有多种理由需要这么做。例如，开发、测试和生产环境需要有不同的配置；或者想在具有相同 Schema 的多个生产数据库中使用相同的 SQL 映射。还有许多类似的使用场景。
注意:尽管可以配置多个环境,但每个 SqlSessionFactory 实例只能选择一种环境。
所以，如果你想连接两个数据库，就需要创建两个 SqlSessionFactory 实例，每个数据库对应一个。而如果是三个数据库，就需要三个实例，依此类推。每个数据库对应一个 SqlSessionFactory 实例
为了指定创建哪种环境,只要将它作为可选的参数传递给 SqlSessionFactoryBuilder 即可。可以接受环境配置的两个方法签名是:

SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment);
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment, properties);

如果忽略环境配置,那么Mybatis会加载默认的环境配置:

SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader);
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, properties);

我们可以在Mybatis全局配置文件的environments标签中配置环境信息:

<environments default="development">
  <environment id="development">
    <transactionManager type="JDBC">
      <property name="..." value="..."/>
    </transactionManager>
    <dataSource type="POOLED">
      <property name="driver" value="${driver}"/>
      <property name="url" value="${url}"/>
      <property name="username" value="${username}"/>
      <property name="password" value="${password}"/>
    </dataSource>
  </environment>
</environments>

关键注意点如下:

• 默认使用的环境 ID（比如：default=”development”）。
• 每个 environment 元素定义的环境 ID（比如：id=”development”）。
• 事务管理器的配置（比如：type=”JDBC”）。
• 数据源的配置（比如：type=”POOLED”）。

默认环境和环境 ID 顾名思义。 环境可以随意命名，但务必保证默认的环境 ID 要匹配其中一个环境 ID。

4.1 transactionManager(事务管理器)

在 MyBatis 中有两种类型的事务管理器（也就是 type=”[JDBC|MANAGED]”）：

• JDBC – 这个配置直接使用了 JDBC 的提交和回滚设施，它依赖从数据源获得的连接来管理事务作用域。
• MANAGED – 这个配置几乎没做什么。它从不提交或回滚一个连接，而是让容器来管理事务的整个生命周期（比如 JEE 应用服务器的上下文）。 默认情况下它会关闭连接。然而一些容器并不希望连接被关闭，因此需要将 closeConnection 属性设置为 false 来阻止默认的关闭行为。例如:

  <transactionManager type="MANAGED">
  <property name="closeConnection" value="false"/>
  </transactionManager>
  

  注意:如果你正在使用 Spring + MyBatis,则没有必要配置事务管理器,因为 Spring 模块会使用自带的管理器来覆盖前面的配置。
  这两种事务管理器类型都不需要设置任何属性。它们其实是类型别名，换句话说，你可以用 TransactionFactory 接口实现类的全限定名或类型别名代替它们。

  public interface TransactionFactory {
  default void setProperties(Properties props) { // 从 3.5.2 开始，该方法为默认方法
    // 空实现
  }
  Transaction newTransaction(Connection conn);
  Transaction newTransaction(DataSource dataSource, TransactionIsolationLevel level, boolean autoCommit);
  }
  

  在事务管理器实例化后，所有在 XML 中配置的属性将会被传递给 setProperties() 方法。你的实现还需要创建一个 Transaction 接口的实现类，这个接口也很简单:

  public interface Transaction {
  Connection getConnection() throws SQLException;
  void commit() throws SQLException;
  void rollback() throws SQLException;
  void close() throws SQLException;
  Integer getTimeout() throws SQLException;
  }
  

  使用这两个接口，你可以完全自定义 MyBatis 对事务的处理。

4.2 dataSource(数据源)

dataSource 标签使用标准的 JDBC 数据源接口来配置 JDBC 连接对象的资源。虽然数据源配置是可选的，但如果要启用延迟加载特性，就必须配置数据源。
Mybatis提供了有三种内建的数据源类型(也就是 type=”[UNPOOLED | POOLED | JNDI]”):

UNPOOLED:这个数据源的实现会每次请求时打开和关闭连接。虽然有点慢，但对那些数据库连接可用性要求不高的简单应用程序来说，是一个很好的选择。 性能表现则依赖于使用的数据库，对某些数据库来说，使用连接池并不重要，这个配置就很适合这种情形。UNPOOLED 类型的数据源仅仅需要配置以下 5 种属性：

• driver – 这是 JDBC 驱动的 Java 类全限定名（并不是 JDBC 驱动中可能包含的数据源类）。
• url – 这是数据库的 JDBC URL 地址。
• username – 登录数据库的用户名。
• password – 登录数据库的密码。
• defaultTransactionIsolationLevel – 默认的连接事务隔离级别。
• defaultNetworkTimeout – 等待数据库操作完成的默认网络超时时间（单位：毫秒）。查看 java.sql.Connection#setNetworkTimeout() 的 API 文档以获取更多信息。

作为可选项，你也可以传递属性给数据库驱动。只需在属性名加上“driver.”前缀即可，例如：

• driver.encoding=UTF8

这将通过 DriverManager.getConnection(url, driverProperties) 方法传递值为 UTF8 的 encoding 属性给数据库驱动。
JNDI:这个数据源实现是为了能在如 EJB 或应用服务器这类容器中使用，容器可以集中或在外部配置数据源，然后放置一个 JNDI 上下文的数据源引用。这种数据源配置只需要两个属性：

• initial_context – 这个属性用来在 InitialContext 中寻找上下文（即，initialContext.lookup(initial_context)）。这是个可选属性，如果忽略，那么将会直接从 InitialContext 中寻找 data_source 属性。
• data_source – 这是引用数据源实例位置的上下文路径。提供了 initial_context 配置时会在其返回的上下文中进行查找，没有提供时则直接在 InitialContext 中查找。

和其他数据源配置类似，可以通过添加前缀“env.”直接把属性传递给 InitialContext。比如：

• env.encoding=UTF8

这就会在 InitialContext 实例化时往它的构造方法传递值为 UTF8 的 encoding 属性。
你可以通过实现接口 org.apache.ibatis.datasource.DataSourceFactory 来使用第三方数据源实现

public interface DataSourceFactory {
  void setProperties(Properties props);
  DataSource getDataSource();
}

org.apache.ibatis.datasource.unpooled.UnpooledDataSourceFactory 可被用作父类来构建新的数据源适配器，比如下面这段插入 C3P0(C3P0是个数据库连接池)数据源所必需的代码:

import org.apache.ibatis.datasource.unpooled.UnpooledDataSourceFactory;
import com.mchange.v2.c3p0.ComboPooledDataSource;

public class C3P0DataSourceFactory extends UnpooledDataSourceFactory {

  public C3P0DataSourceFactory() {
    this.dataSource = new ComboPooledDataSource();
  }
}

5.databaseIdProvider(数据库厂商)

MyBatis 可以根据不同的数据库厂商执行不同的语句，这种多厂商的支持是基于映射语句中的 databaseId 属性。 MyBatis 会加载带有匹配当前数据库 databaseId 属性和所有不带 databaseId 属性的语句。 如果同时找到带有 databaseId 和不带 databaseId 的相同语句，则后者会被舍弃。 为支持多厂商特性，只要像下面这样在 mybatis-config.xml 文件中加入 databaseIdProvider 即可:

<databaseIdProvider type="DB_VENDOR" />

databaseIdProvider 对应的 DB_VENDOR 实现会将 databaseId 设置为 DatabaseMetaData#getDatabaseProductName() 返回的字符串。 由于通常情况下这些字符串都非常长，而且相同产品的不同版本会返回不同的值，你可能想通过设置属性别名来使其变短：

<databaseIdProvider type="DB_VENDOR">
  <property name="SQL Server" value="sqlserver"/>
  <property name="DB2" value="db2"/>
  <property name="Oracle" value="oracle" />
</databaseIdProvider>

在提供了属性别名时，databaseIdProvider 的 DB_VENDOR 实现会将 databaseId 设置为数据库产品名与属性中的名称第一个相匹配的值，如果没有匹配的属性，将会设置为 “null”。 在这个例子中，如果 getDatabaseProductName() 返回“Oracle (DataDirect)”，databaseId 将被设置为“oracle”。
你可以通过实现接口 org.apache.ibatis.mapping.DatabaseIdProvider 并在 mybatis-config.xml 中注册来构建自己的 DatabaseIdProvider:

public interface DatabaseIdProvider {
  default void setProperties(Properties p) { // 从 3.5.2 开始，该方法为默认方法
    // 空实现
  }
  String getDatabaseId(DataSource dataSource) throws SQLException;
}

6.Mappers(映射器)

mybatis最重要的就是SQL 映射语句,Mappers的作用就是告诉Mybatis 去哪里找映射文件,你可以使用相对于类路径的资源引用，或完全限定资源定位符(包括 file:/// 形式的 URL),或类名和包名等,例如:

<!-- 使用相对于类路径的资源引用 -->
<mappers>
  <mapper resource="org/mybatis/builder/AuthorMapper.xml"/>
  <mapper resource="org/mybatis/builder/BlogMapper.xml"/>
  <mapper resource="org/mybatis/builder/PostMapper.xml"/>
</mappers>

<!-- 使用完全限定资源定位符（URL） -->
<mappers>
  <mapper url="file:///var/mappers/AuthorMapper.xml"/>
  <mapper url="file:///var/mappers/BlogMapper.xml"/>
  <mapper url="file:///var/mappers/PostMapper.xml"/>
</mappers>

<!-- 使用映射器接口实现类的完全限定类名 -->
<mappers>
  <mapper class="org.mybatis.builder.AuthorMapper"/>
  <mapper class="org.mybatis.builder.BlogMapper"/>
  <mapper class="org.mybatis.builder.PostMapper"/>
</mappers>

<!-- 将包内的映射器接口实现全部注册为映射器 -->
<mappers>
  <package name="org.mybatis.builder"/>
</mappers>