MyBatis-Plus 实战：优雅处理 JSON 字段映射（以 JSONArray 为例）

---

🎯MyBatis-Plus 实战：优雅处理 JSON 字段映射（以 JSONArray 为例）

👨‍💻 作者：William Dawson ｜📅 更新日期：2025-04-21
🚀 标签：MyBatis-Plus、JSON、TypeHandler、@TableField、@TableName、FastJSON

---

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

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

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

---

🧪 真实场景举例

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

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

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

@TableField(typeHandler = JsonArrayTypeHandler.class)
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，除非你在实体类加上：

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

🔍 autoResultMap 是什么？

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

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

---

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

☁️ 1️⃣ 数据库建表语句（简化版）

CREATE TABLE travel_cuisine (id BIGINT PRIMARY KEY AUTO_INCREMENT,name VARCHAR(100),tag_list TEXT -- JSON Array 字符串
);

---

💡 2️⃣ 实体类配置

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

---

🔧 3️⃣ 自定义 TypeHandler（基于 FastJSON）

public class JsonArrayTypeHandler extends BaseTypeHandler<JSONArray> {@Overridepublic void setNonNullParameter(PreparedStatement ps, int i, JSONArray parameter, JdbcType jdbcType) throws SQLException {ps.setString(i, parameter.toJSONString());}@Overridepublic JSONArray getNullableResult(ResultSet rs, String columnName) throws SQLException {String result = rs.getString(columnName);return JSON.parseArray(result);}@Overridepublic JSONArray getNullableResult(ResultSet rs, int columnIndex) throws SQLException {String result = rs.getString(columnIndex);return JSON.parseArray(result);}@Overridepublic JSONArray getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {String result = cs.getString(columnIndex);return JSON.parseArray(result);}
}

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

---

🧠 四、常见问题排查指南

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

---

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

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

---

📘 延伸阅读推荐

• 📙 MyBatis-Plus 中文文档（字段注解）
• 📕 MyBatis 官方文档：TypeHandler
• 📗 FastJSON 官方文档

---

✨ 最后

希望这篇文章能帮你彻底理解 MyBatis-Plus 处理 JSON 字段的正确姿势 ✅
如果你觉得这篇文章对你有帮助，欢迎点赞、收藏、关注，一起交流更多 Java 技术经验！

---

📩 关注我｜获取更多干货：
Java 全栈｜项目实战｜面试题整理｜源码精讲 🚀