MyBatis 自定義 TypeHandler 三步曲完整指南

MyBatis TypeHandler 自定義三步驟詳解

步驟一：實作 TypeHandler 介面

@MappedJdbcTypes(JdbcType.TIMESTAMP) // 指定對應 JDBC 類型
@MappedTypes(DateTime.class)         // 指定對應 Java 類型
public class DateTimeHandler implements TypeHandler<DateTime> {

    @Override
    public void setParameter(PreparedStatement ps, int i, DateTime parameter, JdbcType jdbcType) {
        // 寫入資料庫前的轉換邏輯
    }

    @Override
    public DateTime getResult(ResultSet rs, String columnName) throws SQLException {
        // 從結果集讀取並轉換
    }

    @Override
    public DateTime getResult(ResultSet rs, int columnIndex) throws SQLException {
        // 從結果集按索引讀取
    }

    @Override
    public DateTime getResult(CallableStatement cs, int columnIndex) throws SQLException {
        // 從存儲過程調用結果讀取
    }
}

使用註解 @MappedJdbcTypes、@MappedTypes 可省去 XML 配置中的屬性聲明。

步驟二：註冊 TypeHandler

方式 1：單個註冊

<typeHandlers>
    <typeHandler handler="com.yourpkg.DateTimeHandler" 
                 javaType="com.yourpkg.DateTime" 
                 jdbcType="TIMESTAMP"/>
</typeHandlers>

方式 2：包掃描批量註冊

<mappers>
    <package name="com.yourpkg.handlers"/>
</mappers>

採用包掃描時，必須在 TypeHandler 類上使用註解聲明 javaType 和 jdbcType，否則 MyBatis 無法識別。

步驟三：在映射中使用

1. 結果映射中指定

<resultMap id="UserResult" type="User">
    <result column="create_time" property="createTime" 
            typeHandler="com.yourpkg.DateTimeHandler"/>
    <!-- 或指定 javaType/jdbcType -->
    <result column="interests" property="interests" 
            javaType="[Ljava.lang.String;" jdbcType="VARCHAR"/>
</resultMap>

2. 參數傳遞中指定

<insert id="insertUser">
    INSERT INTO user (create_time) 
    VALUES (#{createTime, typeHandler=com.yourpkg.DateTimeHandler})
</insert>

<select id="selectByTime">
    SELECT * FROM user 
    WHERE create_time > #{time, typeHandler=com.yourpkg.DateTimeHandler}
</select>

關鍵注意事項

• 註冊與使用保持一致：註冊時聲明的屬性與使用時指定的屬性需匹配，否則 MyBatis 找不到對應 Handler 報錯。
• 優先級：具體映射中指定的 typeHandler > 參數中指定的 typeHandler > 全局註冊的匹配。
• 避免衝突：同一 javaType+jdbcType 組合只能註冊一個 Handler。

總結

掌握「實作介面 → 註冊配置 → 映射使用」三步驟，即可靈活擴展 MyBatis 類型轉換能力，處理特殊資料類型（如 JSON、加密字段、自定義枚舉等）。