MyBatis基础入门《十一》TypeHandler 详解：自定义类型处理器，打通数据库与 Java 的“任督二脉”

前情回顾：
在 《MyBatis基础入门《十》Spring Boot 整合 MyBatis》 中，我们完成了企业级项目的基础搭建。
但现实业务中，数据库字段和 Java 对象往往不是简单的一一对应：

• MySQL 的JSON字段要映射为Map<String, Object>或自定义对象；
• 枚举值（如OrderStatus.PAID）需存为数字或字符串；
• 敏感字段（手机号、身份证）入库前加密，查询后解密。

如何统一、安全、高效地处理这些转换？

答案：使用MyBatis TypeHandler！
本文将从原理到实战，手把手教你编写自定义类型处理器。

一、什么是 TypeHandler？

TypeHandler 是 MyBatis 提供的类型转换器，负责：

• Java Type → JDBC Type（设置参数时，如PreparedStatement.setXXX()）
• JDBC Type → Java Type（获取结果时，如ResultSet.getXXX()）

MyBatis 内置了大量 TypeHandler（如StringTypeHandler,IntegerTypeHandler），但面对复杂类型时，我们需要自定义。

二、实战场景一：MySQL JSON 字段 ↔ Java 对象

场景说明

用户表中有一个profile JSON字段，存储用户扩展信息：

CREATE TABLE tbl_user ( id INT PRIMARY KEY, username VARCHAR(50), profile JSON );

Java 实体：

public class User { private Integer id; private String username; private UserProfile profile; // 自定义对象 } public class UserProfile { private String avatar; private String city; // getter / setter }

目标：查询时自动将 JSON 字符串转为UserProfile；插入时反向转换。

步骤 1：引入 JSON 工具（如 Jackson）

<dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> </dependency>

步骤 2：编写自定义 TypeHandler

// JsonTypeHandler.java package com.charles.typehandler; import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.ibatis.type.BaseTypeHandler; import org.apache.ibatis.type.JdbcType; import java.sql.*; public class JsonTypeHandler<T> extends BaseTypeHandler<T> { private static final ObjectMapper objectMapper = new ObjectMapper(); private Class<T> type; public JsonTypeHandler(Class<T> type) { if (type == null) throw new IllegalArgumentException("Type argument cannot be null"); this.type = type; } @Override public void setNonNullParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException { try { String json = objectMapper.writeValueAsString(parameter); ps.setString(i, json); // 存为 VARCHAR/TEXT } catch (Exception e) { throw new SQLException("Error converting " + type.getSimpleName() + " to JSON", e); } } @Override public T getNullableResult(ResultSet rs, String columnName) throws SQLException { return parseJson(rs.getString(columnName)); } @Override public T getNullableResult(ResultSet rs, int columnIndex) throws SQLException { return parseJson(rs.getString(columnIndex)); } @Override public T getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { return parseJson(cs.getString(columnIndex)); } private T parseJson(String json) throws SQLException { if (json == null || json.isEmpty()) return null; try { return objectMapper.readValue(json, type); } catch (Exception e) { throw new SQLException("Error parsing JSON to " + type.getSimpleName(), e); } } }

✅ 继承BaseTypeHandler<T>，实现四个核心方法； ✅ 使用泛型支持任意 Java 对象； ✅ 异常统一包装为SQLException。

步骤 3：在实体类中注册 TypeHandler

public class User { private Integer id; private String username; @Results({ @Result(property = "profile", column = "profile", typeHandler = JsonTypeHandler.class) }) private UserProfile profile; }

或更简洁地，在字段上使用@TypeHandler（MyBatis 3.4+）：

public class User { // ... @TypeHandler(JsonTypeHandler.class) private UserProfile profile; }

🔔 注意：若使用 XML 映射，可在<result>标签中指定typeHandler。

步骤 4：测试效果

@Test public void testJsonTypeHandler() { User user = new User(); user.setUsername("张三"); UserProfile profile = new UserProfile(); profile.setAvatar("avatar.jpg"); profile.setCity("深圳"); user.setProfile(profile); userMapper.insert(user); // 自动转为 JSON 字符串存入数据库 User saved = userMapper.selectById(user.getId()); System.out.println(saved.getProfile().getCity()); // 输出：深圳 }

✅ 成功！无需手动序列化/反序列化！

三、实战场景二：枚举存储（Enum ↔ Integer/String）

需求

订单状态：CREATED=0,PAID=1,SHIPPED=2

public enum OrderStatus { CREATED(0), PAID(1), SHIPPED(2); private final int code; OrderStatus(int code) { this.code = code; } public int getCode() { return code; } public static OrderStatus fromCode(int code) { for (OrderStatus s : values()) { if (s.code == code) return s; } throw new IllegalArgumentException("Invalid code: " + code); } }

自定义 EnumTypeHandler

public class OrderStatusTypeHandler extends BaseTypeHandler<OrderStatus> { @Override public void setNonNullParameter(PreparedStatement ps, int i, OrderStatus parameter, JdbcType jdbcType) throws SQLException { ps.setInt(i, parameter.getCode()); } @Override public OrderStatus getNullableResult(ResultSet rs, String columnName) throws SQLException { int code = rs.getInt(columnName); return rs.wasNull() ? null : OrderStatus.fromCode(code); } // ... 其他 getNullableResult 方法类似 }

在Order实体中使用：

@TypeHandler(OrderStatusTypeHandler.class) private OrderStatus status;

💡 优势：数据库存整数，Java 用枚举，安全又语义清晰！

四、全局注册 TypeHandler（可选）

避免每个字段重复声明，可在mybatis-config.xml中全局注册：

<typeHandlers> <typeHandler handler="com.charles.typehandler.JsonTypeHandler" javaType="com.charles.entity.UserProfile" jdbcType="VARCHAR" /> </typeHandlers>

或在 Spring Boot 中通过配置类：

@Configuration public class MyBatisConfig { @Bean public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { SqlSessionFactoryBean factory = new SqlSessionFactoryBean(); factory.setDataSource(dataSource); // 注册全局 TypeHandler TypeHandlerRegistry registry = factory.getObject().getConfiguration().getTypeHandlerRegistry(); registry.register(UserProfile.class, new JsonTypeHandler<>(UserProfile.class)); return factory.getObject(); } }

五、注意事项 & 最佳实践

⚠️ 1. 线程安全

• ObjectMapper是线程安全的（Jackson 2.8+），可共享；
• 避免在 TypeHandler 中使用非线程安全的成员变量。

⚠️ 2. 异常处理

• 必须捕获内部异常并转为SQLException，否则 MyBatis 无法正确回滚。

✅ 3. 性能

• TypeHandler 在每次 SQL 执行时调用，避免做耗时操作；
• 可缓存反射结果（如枚举 code 映射）。

🔄 4. 与 JSON 数据库类型兼容

• MySQL 5.7+ 支持JSON类型，但 JDBC 驱动仍将其视为VARCHAR；
• 因此setString/getString完全适用。

六、总结：TypeHandler 应用场景速查

✨核心价值：
“让数据库字段与 Java 对象自由对话，代码更干净，逻辑更内聚！”