前言
MyBatis-Plus已经成为了 Java 后端开发的“标配”。
在阿里云开发者社区的调研报告中，已有超过85%的 Java 项目在使用 MyBatis-Plus。
它基于“约定优于配置”的设计哲学，将简单的单表 CRUD 从 6 行代码缩减到 3 行左右，让无数开发者摆脱了枯燥的 SQL 编写。
然而在日常开发中，我发现很多小伙伴对这个框架过于“迷信”了——似乎加了依赖、写了 Mapper 就能安全起飞。
但框架从来都不是银弹，隐藏的陷阱可能比单纯的 MyBatis 还要多。
今天这篇文章跟大家一起聊聊MyBatis-Plus中最常见的 10 个“坑”，希望对你会有所帮助。
更多项目实战在Java突击队网：susan.net.cn
坑1：分页总数与实际结果对不上
小心一对多关联把总数放大了。
问题现象：使用 Page 分页查询时，明明列表只有 5 条数据，分页的总数却显示有 300 条。
错误代码示例：
// Mapper 接口
public interface OrderMapper extends BaseMapper<Order> {// 直接关联 OrderItem 子表Page<Order> selectOrderPage(Page<Order> page, @Param("userId") Long userId);
}
<!-- XML 中定义 SQL -->
<select id="selectOrderPage" resultType="com.example.Order">SELECT o.*, oi.item_nameFROM orders oLEFT JOIN order_item oi ON o.id = oi.order_idWHERE o.user_id = #{userId}
</select>
// 调用分页
Page<Order> page = new Page<>(1, 10);
orderMapper.selectOrderPage(page, userId);
// 预期总数假设是 3 条订单，实际总数变成了 9（因为每个订单有 3 个商品，笛卡尔积导致重复计数）
原因分析：由于一对多的关系，主表的一条订单因关联子表而被扩展成了多条数据。
分页插件在执行 COUNT 查询时，统计的是关联后的总数，因此分页的总条数被放大了。
解决方案：先分页查出主表数据，再用子查询的方式补全子表字段。
<!-- 正确写法：先分页主表，再关联子表 -->
<select id="selectOrderPage" resultMap="OrderWithItemMap">SELECT o.*, (SELECT JSON_ARRAYAGG(item_name) FROM order_item WHERE order_id = o.id) AS item_namesFROM orders oWHERE o.user_id = #{userId}ORDER BY o.create_time DESC
</select>
或者采用两步法：先分页查主表 ID，再根据 ID 集合批量查子表数据并组装。
// 第一步：查主表 ID 分页
Page<Long> idPage = new Page<>(1, 10);
baseMapper.selectPageIds(idPage, userId);
// 第二步：根据 ID 集合查详情
List<Order> orders = orderService.listByIds(idPage.getRecords());
坑2：分页插件不起作用
手写联表 SQL 时，Page 参数没传对。
问题现象：自己手写的联表查询 SQL，明明传入了 Page 对象，但没有被分页拦截，返回了全部数据。
错误代码示例：
// Mapper 中错误写法：Page 被包裹在 @Param 里
@Select("select * from user where age > #{age}")
Page<User> selectByAge(@Param("age") Integer age, @Param("page") Page<User> page);
<!-- 或者 XML 中参数名不对 -->
<select id="selectByAge" resultType="com.example.User">select * from user where age > #{age}
</select>
原因分析：MyBatis-Plus 的 PaginationInnerInterceptor 拦截器需要根据参数位置来识别 Page 对象。
如果你把 Page 塞进了 @Param 注解或者放在非第一个参数位置且未遵守命名规范，拦截器可能无法正确提取。
解决方案：直接将 Page 对象作为第一个参数，且不要使用 @Param 注解包装。
// 正确写法：Page 作为第一个参数，无 @Param
@Select("select * from user where age > #{age}")
Page<User> selectByAge(Page<User> page, @Param("age") Integer age);
<!-- XML 中直接使用 #{page.current} 和 #{page.size} 获取分页参数，不需要额外定义 -->
<select id="selectByAge" resultType="com.example.User">select * from user where age > #{age}<!-- 分页插件会自动追加 limit 语句 -->
</select>
调用方：
Page<User> page = new Page<>(1, 10);
userMapper.selectByAge(page, 18);
// 分页生效，只返回 10 条数据
坑3：逻辑删除异常
在自定义方法上可能完全失效。
问题现象：配置了 @TableLogic 逻辑删除字段，执行 deleteById 时是更新删除标记，但自己手写的 delete SQL 却真正删除了物理数据。
错误代码示例：
// 实体类
@TableName("user")
public class User {@TableIdprivate Long id;private String name;@TableLogicprivate Integer deleted; // 0-未删除，1-已删除
}// 自定义 Mapper 方法
@Mapper
public interface UserMapper extends BaseMapper<User> {// 手写的物理删除 SQL@Delete("delete from user where age > #{age}")int deleteByAge(@Param("age") Integer age);
}
原因分析：@TableLogic 拦截器只对 BaseMapper 中内置的方法（deleteById、deleteBatchIds、updateById 等）以及 IService 层的 remove 方法生效。
对于在 XML 或注解中手写的 DELETE 语句，MP 不会自动注入逻辑删除条件。
解决方案：手写删除时，必须手动加上逻辑删除字段的判断。
// 正确写法：手动添加删除标记条件
@Delete("update user set deleted = 1 where age > #{age} and deleted = 0")
int logicDeleteByAge(@Param("age") Integer age);
或者在查询时，同样需要手动添加 deleted = 0 条件，否则会查出已删除的数据。
@Select("select * from user where age > #{age} and deleted = 0")
List<User> selectActiveByAge(@Param("age") Integer age);
坑4：自动填充失效
update 时没传 fill 字段策略。
问题现象：明明在实体类上配置了 @TableField(fill = FieldFill.INSERT_UPDATE)，但是执行 updateById 时，update_time 字段并没有自动更新。
错误代码示例：
@Entity
public class Order {@TableField(fill = FieldFill.INSERT_UPDATE)private LocalDateTime updateTime;
}
// 调用更新
Order order = new Order();
order.setId(1L);
order.setStatus("PAID");
orderMapper.updateById(order); // update_time 没有变化
原因分析：自动填充需要配合 MetaObjectHandler 实现类，并且需要在 update 方法执行时，实体对象中对应字段没有被显式赋值，才会触发填充。
但是，如果实体中该字段为 null 且 update 语句的字段策略是 NOT_NULL 或 NOT_EMPTY，则可能不会生成该字段的更新。
解决方案：
- 实现
MetaObjectHandler：
@Component
public class MyMetaObjectHandler implements MetaObjectHandler {@Overridepublic void insertFill(MetaObject metaObject) {this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());}@Overridepublic void updateFill(MetaObject metaObject) {this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());}
}
- 确保实体字段的
update策略允许填充：
@TableField(fill = FieldFill.INSERT_UPDATE, update = "NOW()")
private LocalDateTime updateTime;
- 调用
updateById时，实体中不要设置updateTime字段，MP 会自动填充。
坑5：乐观锁失效
版本号字段类型必须匹配。
问题现象：使用 @Version 注解实现乐观锁，但更新时版本号并没有自动加 1，也没有做版本比对。
错误代码示例：
@TableName("product")
public class Product {@TableIdprivate Long id;private Integer stock;@Versionprivate Long version; // 版本号使用 Long 类型
}
// 配置乐观锁插件
@Configuration
public class MybatisPlusConfig {@Beanpublic MybatisPlusInterceptor mybatisPlusInterceptor() {MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());return interceptor;}
}
// 更新
Product product = productMapper.selectById(1L);
product.setStock(product.getStock() - 1);
productMapper.updateById(product); // 没有检查版本号变化
原因分析：乐观锁插件要求版本号字段的类型必须是 Integer、Long、Date 或 Timestamp，并且每次更新时必须从数据库先查出带有版本号的对象，再更新时 MP 会自动拼接 version = old_version 条件。
如果版本号字段类型不匹配（例如使用 String），或者没有先查询再更新，乐观锁将失效。
解决方案：确保使用兼容的类型，并遵循“先查后改”的模式。
// 正确做法：先查询，再更新
Product product = productMapper.selectById(1L);
product.setStock(product.getStock() - 1);
int rows = productMapper.updateById(product);
if (rows == 0) {throw new OptimisticLockException("操作冲突，请重试");
}
坑6：条件构造器里的 null 值会被忽略
小心查询漏数据。
问题现象：使用 QueryWrapper 动态拼接查询条件时，某个字段值为 null，本意是查询该字段为 null 的数据，但结果却没有查出任何记录。
错误代码示例：
String name = null;
QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.eq("name", name); // name 为 null
List<User> users = userMapper.selectList(wrapper); // 生成的 SQL 是 where name = null
原因分析：MyBatis-Plus 默认的字段策略是 NOT_NULL，即如果传入的参数为 null，自动忽略该条件（不拼接）。
上面代码中 eq("name", null) 实际上没有生成任何条件，而不是 where name is null。
解决方案：
- 如果需要查询
null值，使用isNull方法：
if (name == null) {wrapper.isNull("name");
} else {wrapper.eq("name", name);
}
- 或者修改全局字段策略为非
NOT_NULL（不推荐，容易导致 SQL 错误）。
坑7：批量插入性能极差
别再循环 save 了。
问题现象：循环调用 save 或 insert 插入 1 万条数据，耗时 30 秒以上，速度极慢。
错误代码示例：
for (User user : userList) {userMapper.insert(user); // 逐条插入
}
原因分析：每条 insert 都会发起一次数据库连接交互，产生大量的网络 IO 和事务开销。MyBatis-Plus 的 saveBatch 方法虽然会分批提交，但默认的 insert 语句仍然是单条执行的。
解决方案：使用自定义的批量插入 SQL，利用 MyBatis 的 <foreach> 生成一条多值 insert 语句。
<insert id="insertBatch">insert into user (name, age) values<foreach collection="list" item="item" separator=",">(#{item.name}, #{item.age})</foreach>
</insert>
// Mapper 接口
int insertBatch(List<User> userList);
或者使用 MP 的 saveBatch 并调整 rewriteBatchedStatements=true 的 JDBC 连接参数（MySQL）。
坑8：枚举类型自动映射出错
没有配置枚举处理器。
问题现象：实体类中使用 Java 枚举类型，数据库存储的是 int 或 string，但是查询出来时枚举映射错误或直接报类型转换异常。
错误代码示例：
public enum StatusEnum {NORMAL(0, "正常"),DISABLED(1, "禁用");// ...
}@Entity
public class User {private StatusEnum status; // 枚举类型
}
// 插入
User user = new User();
user.setStatus(StatusEnum.NORMAL);
userMapper.insert(user); // 插入失败或变成 ordinal 值
原因分析：MyBatis 默认使用 EnumTypeHandler 处理枚举，它只能存储枚举的名称或序号。
如果不进行额外配置，MP 无法自动与数据库中的自定义代码（如 0/1）映射。
解决方案：使用 @EnumValue 注解标记枚举中要存储的字段。
public enum StatusEnum {NORMAL(0, "正常"),DISABLED(1, "禁用");@EnumValue // 标记此字段存入数据库private final int code;private final String desc;
}
并配置枚举包扫描路径：
mybatis-plus:type-enums-package: com.example.enums
坑9：wrapper 条件被覆盖
注意 and 和 or 的括号问题。
问题现象：使用 QueryWrapper 拼接多个 or 条件时，实际生成的 SQL 逻辑与预期不符。
错误代码示例：
wrapper.eq("type", 1).or().eq("type", 2).or().eq("type", 3);
// 预期 (type=1 OR type=2 OR type=3)
// 实际可能变成 type=1 OR (type=2 OR type=3) 因为 MP 默认括号策略
原因分析：MP 的条件构造器在拼接 or 时，不会自动加括号，导致 and 与 or 的优先级混乱。
解决方案：使用 and 嵌套函数或 or 嵌套函数来显式指定括号。
wrapper.and(w -> w.eq("type", 1).or().eq("type", 2).or().eq("type", 3));
// 生成 (type = 1 OR type = 2 OR type = 3)
坑10：字段类型处理器不生效
注意泛型与注册。
问题现象：使用 JSON 字段存储复杂对象，配置了 @TableField(typeHandler = JacksonTypeHandler.class)，但插入和查询时对象转换失败。
错误代码示例：
@TableName(value = "user", autoResultMap = true)
public class User {@TableField(typeHandler = JacksonTypeHandler.class)private Address address; // 复杂对象
}
原因分析：JacksonTypeHandler 需要知道泛型类型，且要求表字段为 JSON 格式。
如果数据库字段类型不是 JSON 或未开启 autoResultMap，则无法自动映射。
解决方案：
- 数据库字段类型改为
json（MySQL 5.7+）或jsonb（PostgreSQL）。 - 在实体类上增加
@TableName(autoResultMap = true)。 - 如果使用 MyBatis-Plus 3.5.0+，可以直接使用
JacksonTypeHandler，但需要确保注册。
@TableName(value = "user", autoResultMap = true)
public class User {@TableField(typeHandler = JacksonTypeHandler.class)private Address address;
}
- 或者使用
FastjsonTypeHandler并添加相应的依赖。
MyBatis-Plus 优缺点与适用场景
优点：
- 开发效率极高，单表 CRUD 零 SQL。
- 强大的条件构造器，动态查询方便。
- 分页插件、乐观锁、逻辑删除等开箱即用。
- 社区活跃，文档齐全。
缺点：
- 多表关联复杂查询支持弱。
- 自定义 SQL 与 MP 内置方法混用容易踩坑。
- 批量插入性能需手动优化。
- 过于依赖框架可能会掩盖 SQL 优化本质。
适用场景：
- 新项目快速开发，表结构相对简单。
- 中小型微服务，单表操作占主导。
- 需要减少重复 SQL 编写的团队。
不适用场景：
- 复杂的多表关联查询、报表系统。
- 对 SQL 执行计划极度优化的高性能场景。
- 已有大量手写 SQL 的遗留系统改造（迁移成本高）。
更多项目实战在Java突击队网：susan.net.cn/project
总结
MyBatis-Plus 是一个优秀的增强工具，但它绝非“无脑”框架。
在实际项目中，建议遵循以下原则：
- 简单单表用 MP，复杂查询用 MyBatis 原生 XML。
- 分页查询避免联表扩展总数。
- 手写 SQL 时要自己处理逻辑删除和分页参数。
- 批量操作必须使用批量 SQL。
- 版本号、枚举、JSON 字段要正确配置。
- 条件构造器注意 null 值和括号问题。
希望通过这篇文章，你能在使用 MyBatis-Plus 时少踩坑，写出更健壮、更高效的代码。
如果还有其他“坑”欢迎评论区补充，我们一起避坑！