MyBatis XML 映射核心配置參數深度解析

MyBatis 配置文件層級結構

configuration (根節點)
├── properties          # 屬性佔位符
├── settings            # 全局行為開關
├── typeAliases         # 類型別名
├── typeHandlers        # 類型處理器
├── objectFactory       # 對象工廠
├── plugins             # 插件攔截器
├── environments        # 多環境配置
│   └── environment
│       ├── transactionManager
│       └── dataSource
└── mappers             # 映射器註冊

核心配置節點詳細解析

1. properties —— 外部化配置

<properties resource="jdbc.properties">
    <property name="username" value="dev_user"/>
    <property name="password" value="secret"/>
</properties>

<dataSource type="POOLED">
    <property name="driver" value="${driver}"/>
    <property name="url" value="${url}"/>
    <property name="username" value="${username}"/>
    <property name="password" value="${password}"/>
</dataSource>

• resource：類路徑下屬性文件
• url：文件系統路徑 file:///opt/config/jdbc.properties
• 優先級：外部傳入 > 內部 <property> > resource/url 文件

2. settings —— 關鍵行為開關 (20+ 項)

3. typeAliases —— 簡化類型引用

<!-- 單個定義 -->
<typeAlias alias="User" type="com.example.entity.User"/>

<!-- 批量掃描包 (推薦) -->
<typeAliases>
    <package name="com.example.entity"/>
</typeAliases>

<!-- 內置別名 (不區分大小寫) -->
_string, _int, _long, _double, _boolean, _byte, _short, _float
_integer, _long, _double, _bigdecimal, _date, _map, _list

4. typeHandlers —— 類型轉換器

<!-- 全局註冊 -->
<typeHandlers>
    <typeHandler handler="com.example.handler.JsonTypeHandler"/>
    <typeHandler handler="com.example.handler.EnumOrdinalTypeHandler" 
                 javaType="com.example.enums.Status" jdbcType="INTEGER"/>
</typeHandlers>

<!-- 內置處理器 (部分) -->
BooleanTypeHandler, ByteArrayTypeHandler, DateTypeHandler, 
EnumTypeHandler (name), EnumOrdinalTypeHandler (ordinal),
JsonTypeHandler (需 Jackson), InstantTypeHandler...

• 自定義實現 org.apache.ibatis.type.TypeHandler<T>
• 覆蓋順序：XML 顯式 jdbcType > 全局註冊 > 內置推斷

5. environments & dataSource —— 多環境數據源

<environments default="development">
    <environment id="development">
        <transactionManager type="JDBC">
            <property name="autoCommit" value="false"/>
        </transactionManager>
        <dataSource type="POOLED">
            <property name="driver" value="${jdbc.driver}"/>
            <property name="url" value="${jdbc.url}"/>
            <property name="username" value="${jdbc.username}"/>
            <property name="password" value="${jdbc.password}"/>
            <property name="poolMaximumActiveConnections" value="20"/>
            <property name="poolMaximumIdleConnections" value="5"/>
            <property name="poolMaximumCheckoutTime" value="20000"/>
        </dataSource>
    </environment>
    
    <environment id="production">
        <transactionManager type="MANAGED"/>  -- 容器管理事務
        <dataSource type="JNDI">
            <property name="data_source" value="java:comp/env/jdbc/prodDS"/>
        </dataSource>
    </environment>
</environments>

6. transactionManager —— 事務管理器

<!-- JDBC 事務 (默認) -->
<transactionManager type="JDBC">
    <property name="autoCommit" value="false"/>
</transactionManager>

<!-- 容器管理事務 -->
<transactionManager type="MANAGED">
    <property name="closeConnection" value="false"/>  -- 容器負責關閉
</transactionManager>

7. mappers —— 映射器註冊 (四種方式)

<mappers>
    <!-- 1. 資源路徑 (相對類路徑) -->
    <mapper resource="mapper/UserMapper.xml"/>
    
    <!-- 2. 類全限定名 (註解模式) -->
    <mapper class="com.example.mapper.UserMapper"/>
    
    <!-- 3. 包掃描 (推薦，需命名一致) -->
    <package name="com.example.mapper"/>
    
    <!-- 4. URL 絕對路徑 -->
    <mapper url="file:///opt/mappers/UserMapper.xml"/>
</mappers>

映射器 XML 核心元素 (Mapper 級配置)

resultMap 進階映射 (關鍵技能)

<resultMap id="userDetailMap" type="User">
    <id property="id" column="user_id"/>
    <result property="username" column="user_name"/>
    <result property="email" column="email"/>
    
    <!-- 一對一關聯 -->
    <association property="profile" javaType="Profile">
        <id property="id" column="profile_id"/>
        <result property="avatar" column="avatar_url"/>
        <result property="bio" column="bio"/>
    </association>
    
    <!-- 一對多集合 -->
    <collection property="orders" ofType="Order">
        <id property="id" column="order_id"/>
        <result property="amount" column="order_amount"/>
        <result property="status" column="order_status"/>
    </collection>
    
    <!-- 嵌套 resultMap 復用 -->
    <association property="department" resultMap="deptMap"/>
</resultMap>

動態 SQL 核心標籤 (OGNL 表達式)

最佳實踐清單

1. 啟用駝峰映射：mapUnderscoreToCamelCase=true 消除 80% resultMap
2. 統一使用 resultMap：複雜查詢、關聯對象、列名不同時，不依賴 resultType
3. SQL 片段復用：<sql id="cols">...</sql> + <include refid="cols"/>
4. 參數傳遞：單參數直接用，多參數必加 @Param 或封裝 POJO/Map
5. 超時設置：defaultStatementTimeout=30 + 關鍵語句 timeout="10"
6. 緩存策略：只讀參考表開啟 <cache readOnly="true"/>，寫多讀少表關閉
7. 批量操作：ExecutorType.BATCH + <foreach> 批量插入/更新
8. 類型處理器：Enum 統一用 EnumOrdinalTypeHandler (存數值) 或自定義 JSON 處理器