筆記：MyBatis XML配置詳解

MyBatis 的配置文件包含了影響 MyBatis 行為甚深的設置（settings）和屬性（properties）信息。文檔的頂層結構如下：

• configuration 配置
  • properties 屬性
  • settings 設置
  • typeAliases 類型命名
  • typeHandlers 類型處理器
  • objectFactory 對象工廠
  • plugins 插件
  • environments 環境
    • environment 環境變量
      • transactionManager 事務管理器
      • dataSource 數據源
  • databaseIdProvider 數據庫廠商標識
  • mappers 映射器

1. properties 屬性

   這些屬性都是可外部配置且可動態替換的，既可以在典型的 Java 屬性文件中配置，亦可通過 properties 元素的子元素來傳遞，配置示例：

   <!-- resource 表示 properties 文件路徑，引用該文件的 property -->

   <properties resource="org/mybatis/example/config.properties">

       <property name="username" value="dev_user"/>

       <property name="password" value="F2Fa3!33TYyg"/>

   </properties>

   配置 properties 后，可以在其他配置中使用 property，示例如下：

   <dataSource type="POOLED">

       <property name="driver" value="${driver}"/>

       <property name="url" value="${url}"/>

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

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

   </dataSource>

   這個例子中的 username 和 password 將會由 properties 元素中設置的相應值來替換。

   如果屬性在不只一個地方進行了配置，那么 MyBatis 將按照下面的順序來加載：

• 在 properties 元素體內指定的屬性首先被讀取。
• 然后根據 properties 元素中的 resource 屬性讀取類路徑下屬性文件或根據 url 屬性指定的路徑讀取屬性文件，並覆蓋已讀取的同名屬性。
• 最后讀取作為方法參數傳遞的屬性，並覆蓋已讀取的同名屬性。

因此，通過方法參數傳遞的屬性具有最高優先級，resource/url 屬性中指定的配置文件次之，最低優先級的是 properties 屬性中指定的屬性

MyBatis 3.4.2 增加了默認值，可以通過 ${username:ut_user} 來設置默認值，可以通過配置 property 來啟用默認值，或者設置默認值的分隔符，如下配置：

<!-- 啟用默認值 -->

<property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/>

<!-- 設置默認值分隔符 -->

<property name="org.apache.ibatis.parsing.PropertyParser.default-value-separator" value=":"/>

1. settings 屬性

   這是 MyBatis 中極為重要的調整設置，它們會改變 MyBatis 的運行時行為，完整屬性及說明表可以參考鏈接。一個配置完整的示例如下：

   <settings>

       <!-- 該配置影響的所有映射器中配置的緩存的全局開關 -->

       <setting name="cacheEnabled" value="true" />

       <!-- 延遲加載的全局開關 -->

       <setting name="lazyLoadingEnabled" value="true" />

       <!-- 是否允許單一語句返回多結果集（需要兼容驅動） -->

       <setting name="multipleResultSetsEnabled" value="true" />

       <!-- 使用列標簽代替列名 -->

       <setting name="useColumnLabel" value="true" />

       <!-- 允許 JDBC 支持自動生成主鍵，需要驅動兼容 -->

       <setting name="useGeneratedKeys" value="false" />

       <!-- 當檢測出未知列（或未知屬性）時，如何處理 -->

       <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" />

       <!-- 是否開啟自動駝峰命名規則（camel case）映射,即從數據庫列名 A_COLUMN 到經典 Java 屬性名 aColumn 的類似映射 -->

       <setting name="mapUnderscoreToCamelCase" value="false" />

       <!-- 利用本地緩存機制 -->

       <setting name="localCacheScope" value="SESSION" />

       <!-- 當沒有為參數提供特定的 JDBC 類型時，為空值指定 JDBC 類型 -->

       <setting name="jdbcTypeForNull" value="OTHER" />

       <!-- 指定哪個對象的方法觸發一次延遲加載 -->

   <setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString" />

   </settings>

2. typeAliases 屬性

   類型別名是為 Java 類型設置一個短的名字。它只和 XML 配置有關，存在的意義僅在於用來減少類完全限定名的冗余。指定別名配置如下：

   <typeAliases>

       <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>

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

   <typeAliases>

       <package name="domain.blog"/>

   </typeAliases>

   每一個在包 domain.blog 中的 Java Bean，在沒有注解的情況下，會使用 Bean 的首字母小寫的非限定類名來作為它的別名。 比如 domain.blog.Author 的別名為 author；若有注解，則別名為其注解值。看下面的例子：

   @Alias("author")

   public class Author {

       ...

   }

   已經為許多常見的 Java 類型內建了相應的類型別名。它們都是大小寫不敏感的，需要注意的是由基本類型名稱重復導致的特殊處理，內建相應的類型表參見鏈接 。

3. typeHandlers 屬性

   無論是 MyBatis 在預處理語句（PreparedStatement）中設置一個參數時，還是從結果集中取出一個值時， 都會用類型處理器將獲取的值以合適的方式轉換成 Java 類型，默認的類型處理器參考鏈接。可以重寫類型處理器或創建自己的類型處理器來處理不支持的或非標准的類型。 具體做法為：實現 org.apache.ibatis.type.TypeHandler 接口， 或繼承一個很便利的類 org.apache.ibatis.type.BaseTypeHandler， 然后可以選擇性地將它映射到一個 JDBC 類型，示例代碼：

• 自定義TypeHandler 代碼

  package org.mybatisExamples.simple;

     

  import java.sql.*;

     

  import org.apache.ibatis.type.BaseTypeHandler;

  import org.apache.ibatis.type.JdbcType;

  // 繼承基類重寫方法，通過類型處理器的泛型，MyBatis 可以得知該類型處理器處理的 Java 類型

  public class StringTypeHandler extends BaseTypeHandler<String> {

     

      @Override

      public String getNullableResult(ResultSet arg0, String arg1) throws SQLException {

          System.out.printf("getNullableResult arg1=%s%n", arg1);

          return arg0.getString(arg1);

      }

     

      @Override

      public String getNullableResult(ResultSet arg0, int arg1) throws SQLException {

          System.out.printf("getNullableResult arg1=%d%n", arg1);

          return arg0.getString(arg1);

      }

     

      @Override

      public String getNullableResult(CallableStatement arg0, int arg1) throws SQLException {

          System.out.printf("getNullableResult arg1=%d%n", arg1);

          return arg0.getString(arg1);

      }

     

      @Override

      public void setNonNullParameter(PreparedStatement arg0, int arg1, String arg2, JdbcType arg3) throws SQLException {

          System.out.printf("Index=%d Value=%s JdbcType=%s%n", arg1, arg2, arg3);

          arg0.setString(arg1, arg2);

      }

  }

• 配置文件代碼：

  <typeHandlers>

      <typeHandler handler="org.mybatisExamples.simple.StringTypeHandler"/>

  </typeHandlers>

通過類型處理器的泛型，MyBatis 可以得知該類型處理器處理的 Java 類型，不過這種行為可以通過兩種方法改變：

• 在類型處理器的配置元素（typeHandler element）上增加一個 javaType 屬性（比如：javaType="String"）；
• 在類型處理器的類上（TypeHandler class）增加一個 @MappedTypes 注解來指定與其關聯的 Java 類型列表。 如果在 javaType 屬性中也同時指定，則注解方式將被忽略。

可以通過兩種方式來指定被關聯的 JDBC 類型：

• 在類型處理器的配置元素上增加一個 jdbcType 屬性（比如：jdbcType="VARCHAR"）；
• 在類型處理器的類上（TypeHandler class）增加一個 @MappedJdbcTypes 注解來指定與其關聯的 JDBC 類型列表。 如果在 jdbcType 屬性中也同時指定，則注解方式將被忽略。

當決定在 <ResultMap…/> 中使用某一TypeHandler時，此時java類型是已知的（從結果類型中獲得），但是JDBC類型是未知的。 因此Mybatis使用javaType=[TheJavaType], jdbcType=null的組合來選擇一個TypeHandler。 這意味着使用@MappedJdbcTypes注解可以限制TypeHandler的范圍，同時除非顯示的設置，否則TypeHandler在ResultMap中將是無效的。 如果希望在ResultMap中使用TypeHandler，那么設置@MappedJdbcTypes注解的includeNullJdbcType=true即可。 然而從Mybatis 3.4.0開始，如果只有一個注冊的TypeHandler來處理Java類型，那么它將是ResultMap使用Java類型時的默認值（即使沒有includeNullJdbcType=true）。

1. typeHandlers 屬性處理枚舉類型

   若想映射枚舉類型 Enum，則需要從 org.apache.ibatis.type.EnumTypeHandler 或者 org.apache.ibatis.type.EnumOrdinalTypeHandler 中選一個來使用。比如說我們想存儲取近似值時用到的舍入模式。默認情況下，MyBatis 會利用 EnumTypeHandler 來把 Enum 值轉換成對應的名字。

   注意 EnumTypeHandler 在某種意義上來說是比較特別的，其他的處理器只針對某個特定的類，而它不同，它會處理任意繼承了 Enum 的類。

   不過，我們可能不想存儲名字，相反我們的 DBA 會堅持使用整形值代碼。那也一樣輕而易舉： 在配置文件中把 EnumOrdinalTypeHandler 加到 typeHandlers 中即可， 這樣每個 RoundingMode 將通過他們的序數值來映射成對應的整形，配置示例：

   <typeHandlers>

       <typeHandler handler="org.apache.ibatis.type.EnumOrdinalTypeHandler" javaType="java.math.RoundingMode"/>

   </typeHandlers>

   自動映射器（auto-mapper）會自動地選用 EnumOrdinalTypeHandler 來處理， 所以如果我們想用普通的 EnumTypeHandler，就非要為那些 SQL 語句顯式地設置要用到的類型處理器不可。

2. objectFactory（對象工廠）

   MyBatis 每次創建結果對象的新實例時，它都會使用一個對象工廠（ObjectFactory）實例來完成。 默認的對象工廠需要做的僅僅是實例化目標類，要么通過默認構造方法，要么在參數映射存在的時候通過參數構造方法來實例化。 如果想覆蓋對象工廠的默認行為，則可以通過創建自己的對象工廠來實現，示例代碼：

   package org.mybatisExamples.simple;

      

   import java.util.List;

   import java.util.Properties;

      

   import org.apache.ibatis.reflection.factory.DefaultObjectFactory;

      

   @SuppressWarnings("serial")

   public class ExampleObjectFactory extends DefaultObjectFactory {

       @Override

       public <T> T create(Class<T> type) {

           System.out.println("create is type=" + type.getName());

           return super.create(type);

       }

      

       @Override

       public <T> T create(Class<T> type, List<Class<?>> constructorArgTypes, List<Object> constructorArgs) {

           System.out.println("create is type=" + type.getName());

           return super.create(type, constructorArgTypes, constructorArgs);

       }

      

       @Override

       public void setProperties(Properties properties) {

           System.out.println("setProperties is properties=" + properties.toString());

           super.setProperties(properties);

       }

   }

   配置文件：

   <objectFactory type=" org.mybatisExamples.simple.ExampleObjectFactory ">

       <property name="someProperty" value="100"/>

   </objectFactory>

3. 插件（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 接口，並指定了想要攔截的方法簽名即可，示例代碼：

@Intercepts({@Signature(

// type：表示需要攔截的上面列出的接口

    type= Executor.class,

// method：表示攔截接口的方法

    method = "update",

// args：表示攔截方法的參數

    args = {MappedStatement.class,Object.class})})

public class ExamplePlugin implements Interceptor {

// 執行攔截對象的方法 invocation.proceed 表示執行原始方法

    public Object intercept(Invocation invocation) throws Throwable {

        return invocation.proceed();

    }

// 將目標對象增加攔截器

    public Object plugin(Object target) {

        return Plugin.wrap(target, this);

    }

// 設置攔截器的屬性

    public void setProperties(Properties properties) {

    }

}

配置文件：

<plugins>

    <plugin interceptor="org.mybatis.example.ExamplePlugin">

        <property name="someProperty" value="100"/>

    </plugin>

</plugins>

1. 配置環境（environments）

   MyBatis 可以配置成適應多種環境，這種機制有助於將 SQL 映射應用於多種數據庫之中， 現實情況下有多種理由需要這么做。例如，開發、測試和生產環境需要有不同的配置；或者共享相同 Schema 的多個生產數據庫， 想使用相同的 SQL 映射。許多類似的用例。

   不過要記住：盡管可以配置多個環境，每個 SqlSessionFactory 實例只能選擇其一。

   所以，如果你想連接兩個數據庫，就需要創建兩個 SqlSessionFactory 實例，每個數據庫對應一個。而如果是三個數據庫，就需要三個實例，依此類推，記起來很簡單：

• 每個數據庫對應一個 SqlSessionFactory 實例

為了指定創建哪種環境，只要將它作為可選的參數傳遞給 SqlSessionFactoryBuilder 即可。可以接受環境配置的兩個方法簽名是：

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

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

如果忽略了環境參數，那么默認環境將會被加載，如下所示：

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

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

環境元素定義了如何配置環境，配置示例如下：

<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

1. 事務管理器（transactionManager）

   在 MyBatis 中有兩種類型的事務管理器（也就是 type="[JDBC|MANAGED]"）：

• JDBC – 這個配置就是直接使用了 JDBC 的提交和回滾設置，它依賴於從數據源得到的連接來管理事務作用域。
• MANAGED – 這個配置幾乎沒做什么。它從來不提交或回滾一個連接，而是讓容器來管理事務的整個生命周期（比如 JEE 應用服務器的上下文）。 默認情況下它會關閉連接，然而一些容器並不希望這樣，因此需要將 closeConnection 屬性設置為 false 來阻止它默認的關閉行為。例如:

  <transactionManager type="MANAGED">

      <property name="closeConnection" value="false"/>

  </transactionManager>

     

這兩種事務管理器類型都不需要任何屬性。它們不過是類型別名，換句話說，你可以使用 TransactionFactory 接口的實現類的完全限定名或類型別名代替它們。

public interface TransactionFactory {

    void setProperties(Properties props);

    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 對事務的處理。

1. 數據源（dataSource）

   dataSource 元素使用標准的 JDBC 數據源接口來配置 JDBC 連接對象的資源。

   許多 MyBatis 的應用程序將會按示例中的例子來配置數據源。然而它並不是必須的。要知道為了方便使用延遲加載，數據源才是必須的。

   有三種內建的數據源類型（也就是 type="[UNPOOLED|POOLED|JNDI]"）：

• UNPOOLED– 這個數據源的實現只是每次被請求時打開和關閉連接。雖然一點慢，它對在及時可用連接方面沒有性能要求的簡單應用程序是一個很好的選擇。 不同的數據庫在這方面表現也是不一樣的，所以對某些數據庫來說使用連接池並不重要，這個配置也是理想的。UNPOOLED 類型的數據源僅僅需要配置以下 5 種屬性：
  • driver – 這是 JDBC 驅動的 Java 類的完全限定名（並不是JDBC驅動中可能包含的數據源類）。
  • url – 這是數據庫的 JDBC URL 地址。
  • username – 登錄數據庫的用戶名。
  • password – 登錄數據庫的密碼。
  • defaultTransactionIsolationLevel – 默認的連接事務隔離級別。

  作為可選項，你也可以傳遞屬性給數據庫驅動。要這樣做，屬性的前綴為"driver."，例如：

  • driver.encoding=UTF8

這將通過DriverManager.getConnection(url,driverProperties)方法傳遞值為 UTF8 的 encoding 屬性給數據庫驅動。

• POOLED– 這種數據源的實現利用"池"的概念將 JDBC 連接對象組織起來，避免了創建新的連接實例時所必需的初始化和認證時間。 這是一種使得並發 Web 應用快速響應請求的流行處理方式。 除了上述提到 UNPOOLED 下的屬性外，會有更多屬性用來配置 POOLED 的數據源：
  • poolMaximumActiveConnections – 在任意時間可以存在的活動（也就是正在使用）連接數量，默認值：10
  • poolMaximumIdleConnections – 任意時間可能存在的空閑連接數。
  • poolMaximumCheckoutTime – 在被強制返回之前，池中連接被檢出（checked out）時間，默認值：20000 毫秒（即 20 秒）
  • poolTimeToWait – 這是一個底層設置，如果獲取連接花費的相當長的時間，它會給連接池打印狀態日志並重新嘗試獲取一個連接（避免在誤配置的情況下一直安靜的失敗），默認值：20000 毫秒（即 20 秒）。
  • poolPingQuery – 發送到數據庫的偵測查詢，用來檢驗連接是否處在正常工作秩序中並准備接受請求。默認是"NO PING QUERY SET"，這會導致多數數據庫驅動失敗時帶有一個恰當的錯誤消息。
  • poolPingEnabled – 是否啟用偵測查詢。若開啟，也必須使用一個可執行的 SQL 語句設置 poolPingQuery 屬性（最好是一個非常快的 SQL），默認值：false。
  • poolPingConnectionsNotUsedFor – 配置 poolPingQuery 的使用頻度。這可以被設置成匹配具體的數據庫連接超時時間，來避免不必要的偵測，默認值：0（即所有連接每一時刻都被偵測 — 當然僅當 poolPingEnabled 為 true 時適用）。

通過需要實現接口 org.apache.ibatis.datasource.DataSourceFactory ， 也可使用任何第三方數據源：

public interface DataSourceFactory {

    void setProperties(Properties props);

    DataSource getDataSource();

}

org.apache.ibatis.datasource.unpooled.UnpooledDataSourceFactory 可被用作父類來構建新的數據源適配器，比如下面這段插入 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();

    }

}

為了令其工作，為每個需要 MyBatis 調用的 setter 方法中增加一個屬性。下面是一個可以連接至 MySQL數據庫的例子：

<dataSource type="org.myproject.C3P0DataSourceFactory">

    <property name="driverClass" value="com.mysql.jdbc.driver"/>

    <property name="jdbcUrl" value="jdbc:mysql//localhost:3306/mydb"/>

    <property name="user" value="dev"/>

    <property name="password" value="liyong"/>

</dataSource>

1. 映射器（mappers）

   既然 MyBatis 的行為已經由上述元素配置完了，我們現在就要定義 SQL 映射語句了。但是首先我們需要告訴 MyBatis 到哪里去找到這些語句。 Java 在自動查找這方面沒有提供一個很好的方法，所以最佳的方式是告訴 MyBatis 到哪里去找映射文件。你可以使用相對於類路徑的資源引用， 或完全限定資源定位符（包括 file:/// 的 URL），或類名和包名等。例如：

   <!-- Using classpath relative resources -->

   <mappers>

       <mapper resource="org/mybatis/builder/AuthorMapper.xml"/>

       <mapper resource="org/mybatis/builder/BlogMapper.xml"/>

       <mapper resource="org/mybatis/builder/PostMapper.xml"/>

   </mappers>

   <!-- Using url fully qualified paths -->

   <mappers>

       <mapper url="file:///var/mappers/AuthorMapper.xml"/>

       <mapper url="file:///var/mappers/BlogMapper.xml"/>

       <mapper url="file:///var/mappers/PostMapper.xml"/>

   </mappers>

   <!-- Using mapper interface classes -->

   <mappers>

       <mapper class="org.mybatis.builder.AuthorMapper"/>

       <mapper class="org.mybatis.builder.BlogMapper"/>

       <mapper class="org.mybatis.builder.PostMapper"/>

   </mappers>

   <!-- Register all interfaces in a package as mappers -->

   <mappers>

       <package name="org.mybatis.builder"/>

   </mappers>