聊聊Mybatis-Plus中的10个坑！

前言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 BaseMapperOrder { // 直接关联 OrderItem 子表 PageOrder selectOrderPage(PageOrder page, Param(userId) Long userId); }!-- XML 中定义 SQL -- select idselectOrderPage resultTypecom.example.Order SELECT o.*, oi.item_name FROM orders o LEFT JOIN order_item oi ON o.id oi.order_id WHERE o.user_id #{userId} /select// 调用分页 PageOrder page new Page(1, 10); orderMapper.selectOrderPage(page, userId); // 预期总数假设是 3 条订单实际总数变成了 9因为每个订单有 3 个商品笛卡尔积导致重复计数原因分析由于一对多的关系主表的一条订单因关联子表而被扩展成了多条数据。分页插件在执行COUNT查询时统计的是关联后的总数因此分页的总条数被放大了。解决方案先分页查出主表数据再用子查询的方式补全子表字段。!-- 正确写法先分页主表再关联子表 -- select idselectOrderPage resultMapOrderWithItemMap SELECT o.*, (SELECT JSON_ARRAYAGG(item_name) FROM order_item WHERE order_id o.id) AS item_names FROM orders o WHERE o.user_id #{userId} ORDER BY o.create_time DESC /select或者采用两步法先分页查主表 ID再根据 ID 集合批量查子表数据并组装。// 第一步查主表 ID 分页 PageLong idPage new Page(1, 10); baseMapper.selectPageIds(idPage, userId); // 第二步根据 ID 集合查详情 ListOrder orders orderService.listByIds(idPage.getRecords());坑2分页插件不起作用手写联表 SQL 时Page参数没传对。问题现象自己手写的联表查询 SQL明明传入了Page对象但没有被分页拦截返回了全部数据。错误代码示例// Mapper 中错误写法Page 被包裹在 Param 里 Select(select * from user where age #{age}) PageUser selectByAge(Param(age) Integer age, Param(page) PageUser page);!-- 或者 XML 中参数名不对 -- select idselectByAge resultTypecom.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}) PageUser selectByAge(PageUser page, Param(age) Integer age);!-- XML 中直接使用 #{page.current} 和 #{page.size} 获取分页参数不需要额外定义 -- select idselectByAge resultTypecom.example.User select * from user where age #{age} !-- 分页插件会自动追加 limit 语句 -- /select调用方PageUser page new Page(1, 10); userMapper.selectByAge(page, 18); // 分页生效只返回 10 条数据坑3逻辑删除异常在自定义方法上可能完全失效。问题现象配置了TableLogic逻辑删除字段执行deleteById时是更新删除标记但自己手写的deleteSQL 却真正删除了物理数据。错误代码示例// 实体类 TableName(user) public class User { TableId private Long id; private String name; TableLogic private Integer deleted; // 0-未删除1-已删除 } // 自定义 Mapper 方法 Mapper public interface UserMapper extends BaseMapperUser { // 手写的物理删除 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) ListUser 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则可能不会生成该字段的更新。解决方案实现MetaObjectHandlerComponent public class MyMetaObjectHandler implements MetaObjectHandler { Override public void insertFill(MetaObject metaObject) { this.strictInsertFill(metaObject, createTime, LocalDateTime.class, LocalDateTime.now()); this.strictInsertFill(metaObject, updateTime, LocalDateTime.class, LocalDateTime.now()); } Override public 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 { TableId private Long id; private Integer stock; Version private Long version; // 版本号使用 Long 类型 }// 配置乐观锁插件 Configuration public class MybatisPlusConfig { Bean public 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; QueryWrapperUser wrapper new QueryWrapper(); wrapper.eq(name, name); // name 为 null ListUser 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 idinsertBatch insert into user (name, age) values foreach collectionlist itemitem separator, (#{item.name}, #{item.age}) /foreach /insert// Mapper 接口 int insertBatch(ListUser userList);或者使用 MP 的saveBatch并调整rewriteBatchedStatementstrue的 JDBC 连接参数MySQL。坑8枚举类型自动映射出错