MyBatis-Plus实现优雅处理JSON字段映射

公孙古韵

在使用 MyBatis-Plus 进行业务开发时，我们时常需要把数据库中的 JSON 字段（比如字符串形式的数组）自动映射成 Java 中的 JSONArray 或 List 类型。

默认情况下，MyBatis-Plus 是不支持直接映射 JSON 类型的，这时候就需要借助：

• @TableField(typeHandler = ...)
• 自定义或已有的 TypeHandler
• 配合 @TableName(autoResultMap = true) 才能正确生效！

真实场景举例

假设我们现在有一个旅游美食表 travel_cuisine，里面的字段 tag_list 是一个 JSON Array，用来存储标签 ID 列表，示例数据如下：

1. ["tag-101", "tag-202", "tag-333"]

复制代码

我们希望在 Java 实体中使用如下形式自动映射：

1. @TableField(typeHandler = JsonArrayTypeHandler.class)
2. private JSONArray tagList;

复制代码

接下来，教你一步步实现它。

一、@TableField + typeHandler 是什么？

@TableField 简介

@TableField 是 MyBatis-Plus 提供的字段级注解，用于说明字段与数据库的映射关系。

核心参数如下：

参数	说明
value 复制代码	对应数据库字段名
exist 复制代码	字段是否存在于数据库表结构中
typeHandler 复制代码	字段转换处理器，用于复杂类型映射

typeHandler 作用

TypeHandler 是 MyBatis 中的一个重要机制，它负责Java 类型 和 JDBC 类型之间的转换。

你可以用它来处理：

• JSON ↔ Java 对象（如 JSONArray、Map、List）
• 逗号分隔字符串 ↔ List
• 枚举 ↔ 数据库存储值

简单来说，typeHandler 就是数据格式的桥梁！

二、@TableName(autoResultMap = true) 必须开启

默认情况下，MyBatis-Plus 的字段映射并不会使用 typeHandler，除非你在实体类加上：

1. @TableName(value = "travel_cuisine", autoResultMap = true)

复制代码

autoResultMap 是什么？

这是告诉 MP：“请生成自定义的 ResultMap，否则我不支持 typeHandler 和复杂类型的转换！”

如果你忘记加这一项，typeHandler 是不会生效的！

三、实战代码：映射 JSON 字段为 JSONArray

1.数据库建表语句（简化版）

1. CREATE TABLE travel_cuisine (
2. id BIGINT PRIMARY KEY AUTO_INCREMENT,
3. name VARCHAR(100),
4. tag_list TEXT -- JSON Array 字符串
5. );

复制代码

2.实体类配置

1. @Data
2. @TableName(value = "travel_cuisine", autoResultMap = true)public class TravelCuisineDO {
4. private Long id;
6. private String name;
8. @TableField(typeHandler = JsonArrayTypeHandler.class)
9. private JSONArray tagList;
10. }

复制代码

3.自定义 TypeHandler（基于 FastJSON）

1. public class JsonArrayTypeHandler extends BaseTypeHandler<JSONArray> {
3. @Override
4. public void setNonNullParameter(PreparedStatement ps, int i, JSONArray parameter, JdbcType jdbcType) throws SQLException {
5. ps.setString(i, parameter.toJSONString());
6. }
8. @Override
9. public JSONArray getNullableResult(ResultSet rs, String columnName) throws SQLException {
10. String result = rs.getString(columnName);
11. return JSON.parseArray(result);
12. }
14. @Override
15. public JSONArray getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
16. String result = rs.getString(columnIndex);
17. return JSON.parseArray(result);
18. }
20. @Override
21. public JSONArray getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
22. String result = cs.getString(columnIndex);
23. return JSON.parseArray(result);
24. }
25. }

复制代码

提醒：这个 JsonArrayTypeHandler 使用的是 FastJSON，如需 Jackson，请更换转换逻辑。

四、常见问题排查指南

问题现象	解决方法或建议
typeHandler 没有生效	检查实体类是否开启 autoResultMap = true
报 JSON parse error	确保数据库字段是真正的 JSON 格式
存储时字段为 null	确认字段不是 transient，且未被忽略
想用 List 代替 JSONArray	写一个 ListStringTypeHandler 即可

总结：三件事必须配套使用

配置项	说明
@TableField(typeHandler = …)	标记字段转换器
@TableName(autoResultMap = true)	告诉 MP 启用复杂映射
自定义 TypeHandler	将 JSON 字段与 Java 类型进行互转

到此这篇关于MyBatis-Plus实现优雅处理JSON字段映射的文章就介绍到这了,更多相关MyBatis-Plus处理JSON字段映射内容请搜索晓枫资讯以前的文章或继续浏览下面的相关文章希望大家以后多多支持晓枫资讯！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！