前言
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_name FROM orders o LEFT JOIN order_item oi ON o.id = oi.order_id WHERE 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_names FROM orders o WHERE 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时是更新删除标记，但自己手写的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 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 { @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; 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）。
