MyBatis TypeHandler从入门到实战：搞定JSON、枚举与自定义类型映射

1. TypeHandler到底解决了什么麻烦先说个我踩过的真实场景。有一年做电商项目订单表里有个ext_info字段存的是商品快照的JSON字符串。Java实体类里想直接用一个MapString, Object去接结果查询出来一直是String还得手动用Jackson解析一遍插入的时候又得先把Map转成JSON字符串。一来一回写了十几个工具方法每个Mapper里都在调烦得要命。后来在代码评审里被一个老哥点了一句“你为啥不写个TypeHandler”当时我还一脸懵查了几天文档才彻底搞明白。这玩意确实是MyBatis里被低估的一个扩展点它解决的就是Java类型和数据库类型之间的映射问题。本质上说Java世界和数据库世界是两套类型体系。String、Integer、LocalDate这些Java类型到了JDBC层得用PreparedStatement.setString()、setInt()、setDate()才能写进数据库查出来的时候又得通过ResultSet.getString()、getInt()才能读出来。MyBatis在中间做了一层适配而TypeHandler就是这层适配的插件接口——你想怎么转就怎么转。它的应用场景其实比大多数人想象的广泛得多自定义对象与JSON字段互转最常见枚举类型与数据库int/varchar互转LocalDateTime与时间戳、字符串的兼容数组、List集合与逗号分隔字符串互转敏感字段加解密加密后存库查询时自动解密地理位置坐标等结构化数据转换而且这东西不只是给MyBatis用MyBatis-Plus同样支持只是注册方式略有差异。理解了底层原理后你在哪个MyBatis生态的框架里都能把控得住。2. TypeHandler的设计思路与核心原理拆解2.1 为什么要设计一套“转换器”而不是直接改实体类可能有朋友会问既然类型对不上直接在实体类里存String不就行了查询到业务层再转换干嘛非要在持久层搞这么一套机制答案是为了复用和统一。如果每个Service里都写JSON解析逻辑十个地方用了这个字段就得写十遍差不多的代码。万一哪天数据结构里要加个字段或者换一个JSON库你得到处找着改。而TypeHandler把这个转换逻辑收敛到了一处实体类保持干净的Java类型Mapper层拿到直接就是能用的对象。另外从架构角度看一个接口实现类用MappedTypes和MappedJdbcTypes声明好适用范围后MyBatis在启动时就能自动注册所有用到该Java类型的地方自动生效。这有点像一个全局翻译器数据库那边说的是SQL方言Java这边说的是对象语言TypeHandler就是那个同声传译。2.2 TypeHandler接口的四个核心方法MyBatis的TypeHandlerT接口很精简一共就四个方法但每个都有明确的调用时机。public interface TypeHandlerT { void setParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException; T getResult(ResultSet rs, String columnName) throws SQLException; T getResult(ResultSet rs, int columnIndex) throws SQLException; T getResult(CallableStatement cs, int columnIndex) throws SQLException; }setParameter往SQL中绑定参数时调用。比如你用#{extInfo}传了一个Map进来MyBatis拿到这个参数后就会调用对应的TypeHandler把Map转成String再调用ps.setString()写入PreparedStatement。getResult的三个重载从结果集取数据时调用。查询出的JSON字符串在这里被解析回Map对象赋值给实体类属性。MyBatis里有个内置的BaseTypeHandler抽象类已经把setParameter的空值判断逻辑写好了如果参数为null直接调用ps.setNull(i, jdbcType)非null时走子类实现的setNonNullParameter。所以自定义TypeHandler时推荐继承BaseTypeHandler省掉判空的活儿。2.3 常见的内置TypeHandler和默认映射关系MyBatis默认注册了一批常用的处理器比如StringTypeHandler、IntegerTypeHandler、LongTypeHandler、DateTypeHandler、BooleanTypeHandler等等。它们的映射规则是Java的String映射到数据库的VARCHARInteger映射到INTEGERLong映射到BIGINT以此类推。但有个问题——默认映射只覆盖了基础类型。像LocalDateTime这种Java 8时间类型MyBatis早期甚至不直接支持很多项目还在用Date。包括枚举、Map、复杂对象默认处理器根本不知道该怎么处理。你只要发现某个字段查询出来类型不对、或者插入时报“No typehandler found”大概率就是缺一个对应的TypeHandler。2.4 自定义TypeHandler的两个关键决策点写自定义TypeHandler时一般要考虑两个问题第一继承BaseTypeHandlerT还是直接实现TypeHandlerT接口。绝大多数场景继承抽象类就够用复杂度低空值逻辑也帮你处理好了。只有在极特殊的类型转换、或者你想完全接管参数处理流程时才需要直接实现接口。第二泛型类型T填什么。这个T决定了这个处理器“处理哪种Java类型”。比如你要处理的是ListString那T就是ListString但需要注意泛型擦除稍后会在常见问题里细说。3. 手写一个通用JSON TypeHandler完整实操3.1 场景设定数据库JSON字段映射为Java对象/List还是拿订单扩展信息举例。表结构里有一列extra_info VARCHAR(2000)存的是JSON{channel: APP, promotionId: 1024, tags: [新人, 618]}我希望Java实体类里直接用一个MapString, Object接收同时还有一个ListString类型的标签集合需要存到另一个字段或同一个字段里。这时候就需要一个能灵活处理JSON的TypeHandler。3.2 基于Jackson实现自定义TypeHandler用Jackson实现兼容性好性能也不错Spring Boot项目里基本都自带了jackson-databind。代码长这样MappedTypes(Object.class) MappedJdbcTypes(JdbcType.VARCHAR) public class JsonTypeHandler extends BaseTypeHandlerObject { private static final ObjectMapper MAPPER new ObjectMapper(); Override public void setNonNullParameter(PreparedStatement ps, int i, Object parameter, JdbcType jdbcType) throws SQLException { try { ps.setString(i, MAPPER.writeValueAsString(parameter)); } catch (JsonProcessingException e) { throw new RuntimeException(JSON序列化失败, e); } } Override public Object getNullableResult(ResultSet rs, String columnName) throws SQLException { return parse(rs.getString(columnName)); } Override public Object getNullableResult(ResultSet rs, int columnIndex) throws SQLException { return parse(rs.getString(columnIndex)); } Override public Object getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { return parse(cs.getString(columnIndex)); } private Object parse(String json) { if (json null || json.isEmpty()) { return null; } try { return MAPPER.readValue(json, Object.class); } catch (JsonProcessingException e) { throw new RuntimeException(JSON反序列化失败, e); } } }这里有几个细节必须说清楚第一MappedTypes(Object.class)表示这个处理器能处理Object及其子类。写Object.class有点“万能处理器”的意味但注册时要小心它可能会覆盖掉MyBatis对内建类型的默认映射。如果你只希望某个特定类型用这个处理器建议把泛型限定到具体类型比如MappedTypes(Map.class)这样影响范围更可控。第二MappedJdbcTypes(JdbcType.VARCHAR)声明了对应的JDBC类型当MyBatis需要VARCHAR类型参数时可以用上它。第三getNullableResult里返回类型是ObjectMyBatis拿到后不会自动帮你转型成Map。真正赋值给实体类属性时会根据属性的实际类型进行强转。你反序列化出来的是LinkedHashMap如果实体类属性是MapString, Object那没问题如果是ListString就会报ClassCastException。这就是为什么更严谨的做法是给每个需要的类型单独定义处理器而不是一个万能打天下。3.3 更稳的方案泛型JSON TypeHandler处理List等集合类型如果你确实想一个处理器搞定多种JSON结构就得在解析时“看菜下饭”。我通常的做法是配合MappedTypes标记的接口或基类或者直接写两个专用处理器一个处理Map一个处理List。MappedTypes(Map.class) public class MapJsonTypeHandler extends BaseTypeHandlerMapString, Object { // 实现逻辑类似解析时转成Map }MappedTypes(List.class) public class ListJsonTypeHandler extends BaseTypeHandlerListObject { // 实现逻辑类似解析时转成List }这个方案最直观的好处是职责单一Map类型的字段自动走MapJsonTypeHandlerList类型的字段走ListJsonTypeHandler不会互相干扰。缺点就是类稍微多一点。但相比排查一个“为什么我取出来是Map却转不了List”的隐形Bug多写一个类太值得了。3.4 注册TypeHandler的三种方式与推荐顺序TypeHandler写好后得让MyBatis知道它存在有三种注册渠道方式一配置文件全局注册在mybatis-config.xml中typeHandlers typeHandler handlercom.example.handler.MapJsonTypeHandler/ typeHandler handlercom.example.handler.ListJsonTypeHandler/ /typeHandlers这种方式是全局生效的适合项目里所有Mapper通用、且冲突风险很低的场景。方式二Spring Boot下通过Bean注册如果是Spring Boot MyBatis Starter可以直接声明一个ConfigurationCustomizerConfiguration public class MybatisConfig { Bean public ConfigurationCustomizer mybatisConfigurationCustomizer() { return configuration - { configuration.getTypeHandlerRegistry().register(Map.class, JdbcType.VARCHAR, new MapJsonTypeHandler()); configuration.getTypeHandlerRegistry().register(List.class, JdbcType.VARCHAR, new ListJsonTypeHandler()); }; } }这里是通过TypeHandlerRegistry手动注册目标更明确指定了Java类型和JDBC类型的组合。这也是我比较推荐的方式因为你是在代码里显式告诉MyBatis“遇到这个Java类型用这个处理器”而不是让框架自动扫描猜测。方式三XML Mapper里局部指定在Mapper XML文件里针对某个查询/插入单独指定resultMap idOrderResultMap typecom.example.Order id propertyid columnid/ result propertyextraInfo columnextra_info typeHandlercom.example.handler.MapJsonTypeHandler/ /resultMap这适合只有某个字段需要特殊转换的场景。如果你有20个Mapper都要用JSON转换那更合适的方式是全局注册而不是每个XML里写一遍typeHandler属性。注意三种方式同时使用也不会冲突它们的优先级是局部指定 代码手动注册 配置文件全局注册。局部指定最灵活但也最容易漏。我的习惯是能用全局注册就用全局注册个别特殊字段才在XML里覆盖。3.5 在实体类和Mapper中配合使用实体类里正常写属性就好public class Order { private Long id; private MapString, Object extraInfo; // getter/setter }Mapper接口里无需任何额外注解public interface OrderMapper { Order selectById(Param(id) Long id); int insert(Order order); }查询和插入时MyBatis看到extraInfo属性的类型是MapString, Object会去TypeHandlerRegistry里查询已注册的对应处理器找到MapJsonTypeHandler后自动完成JSON与Map的互转。如果用的是MyBatis-Plus实体类字段上可以加TableField(typeHandler MapJsonTypeHandler.class)TableField(typeHandler MapJsonTypeHandler.class) private MapString, Object extraInfo;这样在MyBatis-Plus的BaseMapper方法里也能正确转换。4. 踩坑实录TypeHandler使用中的高频问题与排查技巧4.1 问题一插入了Map字段数据库里却是空值这是我最开始碰到的问题。代码逻辑没毛病实体类属性也有值但入库后字段是NULL。排查思路先确认是不是TypeHandler没被选中。MyBatis选择TypeHandler的逻辑是先查Java类型映射再查JDBC类型映射两者都匹配才算命中。如果你的Map字段上没加MappedJdbcTypes而且当前环境里JdbcType解析后是OTHER就可能导致匹配不上走了默认的UnknownTypeHandler。解决方案很简单给处理器标注MappedJdbcTypes(JdbcType.VARCHAR)或者在XML的#{extraInfo, typeHandlerMapJsonTypeHandler}里显式指定。大多数情况下标注好MappedJdbcTypes就能解决。4.2 问题二多个TypeHandler冲击导致查询结果返回异常如果你在全局注册了一个Object.class的JSON处理器同时又存在MyBatis内置的StringTypeHandler那MyBatis在处理String类型的属性时就会犹豫不决——到底该用哪个这就是我之前说的“万能处理器”带来的隐患。MappedTypes(Object.class)覆盖面太广会干扰基础类型的默认映射。遇到这种情况你在XML写where name #{name}时name参数处理都有可能被切到JSON处理器上。规避手段是把MappedTypes写到具体类型如Map.class、List.class或者直接通过TypeHandlerRegistry.register(具体类型.class, ...)进行定向注册。记住一个原则TypeHandler的粒度越细框架越知道该怎么选。4.3 问题三泛型擦除导致List类型匹配失败自定义ListJsonTypeHandler extends BaseTypeHandlerListString时有的同学直接写List.class就完事了。但注意泛型ListString在运行时会被擦除为ListMyBatis的TypeHandlerRegistry注册时如果用List.class作为key那所有List类型的属性都会匹配到这个处理器。假设我还有一个属性是ListInteger它也会被送到ListJsonTypeHandler里反序列化时就会因为元素类型不匹配而出错。遇到这种情况要么给每个ListT写独立的处理器比如StringListTypeHandler、IntegerListTypeHandler要么在处理器解析时用JavaType参数做二次判断说直白点泛型和TypeHandler的组合使用时不能只看外层类型还得考虑内部元素的真实类型。MyBatis的TypeHandlerRegistry还支持带javaType参数的注册方式但复杂程度会上升一般业务场景没必要。4.4 问题四查询结果里LocalDateTime字段转成了TimestampJava 8的LocalDateTime在旧版MyBatis里没有内置支持。现在常见的处理是使用mybatis-typehandlers-jsr310依赖里面提供了LocalDateTimeTypeHandler。如果你用的MyBatis 3.4.0以上版本这个依赖是内置的直接注册就行。如果还是不行自己写一个也很简单MappedTypes(LocalDateTime.class) MappedJdbcTypes(JdbcType.TIMESTAMP) public class LocalDateTimeTypeHandler extends BaseTypeHandlerLocalDateTime { Override public void setNonNullParameter(PreparedStatement ps, int i, LocalDateTime parameter, JdbcType jdbcType) throws SQLException { ps.setTimestamp(i, Timestamp.valueOf(parameter)); } Override public LocalDateTime getNullableResult(ResultSet rs, String columnName) throws SQLException { Timestamp timestamp rs.getTimestamp(columnName); return timestamp null ? null : timestamp.toLocalDateTime(); } // 省略另外两个 getNullableResult }这里踩过最深的坑是时区问题。如果你直接用ps.setTimestamp(i, Timestamp.valueOf(parameter))系统会用到JVM默认时区来转换如果应用服务器和数据库服务器时区不一致查出来的时间就可能差8小时。保险的做法是代码里统一用ZoneId.systemDefault()或明确指定时区再构建Timestamp。4.5 问题五枚举类型转换失败枚举映射是很常见的需求——数据库存INTEGER或VARCHARJava里是枚举对象。MyBatis提供了EnumTypeHandler和EnumOrdinalTypeHandler前者按枚举名字符串存后者按枚举序号存。但实际情况是很多枚举的“展示值”和“存储值”不一致。比如状态枚举public enum OrderStatus { CREATED(1, 已创建), PAID(2, 已支付), CANCELLED(3, 已取消); private final int code; private final String desc; OrderStatus(int code, String desc) { this.code code; this.desc desc; } public int getCode() { return code; } }如果直接存CREATED、PAID这种字符串或者存0、1、2这种序号都不合适。更合理的是存上面的code字段。这时候就得自定义一个TypeHandler让Bean属性上的枚举类型自动映射到数据库的INTEGER列MappedTypes(OrderStatus.class) MappedJdbcTypes(JdbcType.INTEGER) public class OrderStatusTypeHandler extends BaseTypeHandlerOrderStatus { 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 { return resolve(rs.getInt(columnName)); } Override public OrderStatus getNullableResult(ResultSet rs, int columnIndex) throws SQLException { return resolve(rs.getInt(columnIndex)); } Override public OrderStatus getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { return resolve(cs.getInt(columnIndex)); } private OrderStatus resolve(int code) { for (OrderStatus status : OrderStatus.values()) { if (status.getCode() code) { return status; } } throw new IllegalArgumentException(未知订单状态码: code); } }这里有个隐藏问题注册了OrderStatus.class的TypeHandler后如果项目里还有别的枚举类型它们不会受影响因为MyBatis是根据MappedTypes指定的Java类型逐一匹配的。你不需要给所有枚举都写处理器只需要给真正需要“特殊存法”的枚举写。4.6 问题六查询空字符串时返回null与空串的混淆当数据库字段是空字符串而你用TypeHandler解析JSON时parse()里如果判断json.isEmpty()就返回null会丢失“空串”这个语义。这在业务上是两种状态空串可能是未填充也可能是主动填了一个空集合。我的建议是在TypeHandler里区分null和空串。如果数据库返回null返回null返回可返回空Map或空List。具体按业务定但不要一概而论。比如我处理ListJsonTypeHandler时会private Object parse(String json) { if (json null) { return null; } if (json.isEmpty()) { return new ArrayList(); } // 正常解析 }5. 工具选型写TypeHandler用什么JSON库更合适5.1 Jackson、Gson、Fastjson之间怎么选这是实操中绕不开的选型问题。我个人的建议是JacksonSpring Boot默认内置性能稳定功能全面支持Java 8时间类型模块是我默认主力。Gson轻量API简洁但在复杂泛型反序列化上比Jackson稍弱。FastjsonAPI很好用性能曾经很强但前些年爆出过安全漏洞。如果是新项目我不太建议引入额外的Fastjson依赖除非你对它很熟且业务场景不涉及不可信数据的反序列化。在TypeHandler里使用JSON库时注意一点最好把ObjectMapper或Gson实例定义成静态常量不要在每次转换时new一个新的。JSON反序列化是个比较重的操作频繁new实例会浪费不必要的资源。5.2 处理复杂嵌套泛型时的反序列化技巧Jackson反序列化带泛型的集合时得用TypeReference。比如MAPPER.readValue(json, new TypeReferenceListOrderItem() {});如果你的TypeHandler是处理ListSomeDto的千万别直接readValue(json, List.class)——这样反序列化出来的List里每个元素是LinkedHashMap而不是SomeDto对象后面一强转就报错。正确写法MappedTypes(List.class) public class OrderItemListTypeHandler extends BaseTypeHandlerListOrderItem { private static final ObjectMapper MAPPER new ObjectMapper(); Override public void setNonNullParameter(PreparedStatement ps, int i, ListOrderItem parameter, JdbcType jdbcType) throws SQLException { try { ps.setString(i, MAPPER.writeValueAsString(parameter)); } catch (JsonProcessingException e) { throw new RuntimeException(订单明细序列化失败, e); } } Override public ListOrderItem getNullableResult(ResultSet rs, String columnName) throws SQLException { String json rs.getString(columnName); if (json null || json.isEmpty()) { return new ArrayList(); } try { return MAPPER.readValue(json, new TypeReferenceListOrderItem() {}); } catch (JsonProcessingException e) { throw new RuntimeException(订单明细反序列化失败, e); } } // 省略另外两个getNullableResult }这个坑我印象太深了第一次用TypeHandler处理列表时就是从List里取元素ClassCastException开始排查的最后定位到是泛型反序列化的问题。6. 进阶玩法TypeHandler不只处理JSON说到TypeHandler的价值很多人第一反应就是JSON转换。其实它的应用面要广得多我这里再补几个实际项目里验证过的场景。6.1 敏感字段自动加解密假设有个需求手机号、身份证号在数据库里必须密文存储但业务代码里直接使用明文。写一个EncryptTypeHandler extends BaseTypeHandlerString在setNonNullParameter里加密再写入在getNullableResult里解密后返回。这样所有涉及敏感字段的Mapper都自动完成加解密业务层完全无感。这个方法最大的好处是安全逻辑收敛但别忘了你需要在setParameter时判断参数是否已经加密否则加密过的数据再加密一次就麻烦了。另外还要注意搜索场景加了密的字段无法用普通的where phone #{phone}去查询因为数据库里存的是密文这种情况要么用加密函数做SQL端匹配要么走专门的查询入口。6.2 存储位图或BitSet类型数据库里有时候用BIT类型存一组布尔开关。Java里可以用BitSet表达。写一个BitSetTypeHandler在读写时完成BitSet和long[]/byte[]的互转性能好语义也清晰。6.3 自定义枚举多字段映射有些枚举不只是有一个编码还有多个属性需要同时映射到多个数据库字段。这种情况不再是一个TypeHandler能解决的而是要在resultMap中为每个字段指定不同的TypeHandler或者用构造器映射。但单个枚举字段的存储TypeHandler仍是最佳方案。7. 实操总结与接口设计建议写到这里TypeHandler的核心机制、实现方式、常见坑点都说完了。我再把项目中沉淀下来的几个设计建议一并分享出来。建议一TypeHandler的注册范围越具体越好我不建议写一个MappedTypes(Object.class)的“万能JSON处理器”然后全局注册除非是内部工具项目、字段类型完全受控。否则它很容易干扰基础类型的转换。具体类型映射到具体处理器这看起来多写几个类但排查问题时会省下好几个小时。建议二异常处理要够明确在TypeHandler里做序列化/反序列化时不要把Exception吞掉也不建议直接返回null。最好包装成带有上下文信息的运行时异常比如throw new RuntimeException(JSON解析失败, 字段columnName columnName , 值 json, e);这样一旦数据有问题日志里能直接定位到失败字段而不是只看到一串堆栈。建议三不要在设计TypeHandler时做太多隐式转换比如在TypeHandler里偷偷做字符串截断、数组去重、类型强制转换等逻辑看似方便实际上会让数据流变得不可控。TypeHandler的职责就是类型转换不要塞入业务逻辑。加了业务逻辑后面维护的人根本猜不到。建议四写TypeHandler时一定要考虑null情况setNonNullParameter里不用管null但getNullableResult里要处理好数据库返回null的情况。很多同学刚开始写时忽略了这个结果数据库里某个字段为空查询出来就莫名其妙报了NPE。最后分享一个我觉得很实用的调试小技巧如果你不确定MyBatis到底给某个字段用了哪个TypeHandler可以在mybatis-config.xml里把日志级别调到debug或者监控TypeHandlerRegistry的注册日志。MyBatis启动时会有类似Registering typeHandler: XxxTypeHandler for JavaType: class java.util.Map (JDBCType: VARCHAR)的日志一眼就能看到映射关系。排查起问题来比瞎猜快得多。