前言

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 时是更新删除标记，但自己手写的 delete SQL 却真正删除了物理数据。

错误代码示例：

// 实体类
@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，则可能不会生成该字段的更新。

解决方案：

1. 实现 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());
    }
}

2. 确保实体字段的 update 策略允许填充：

@TableField(fill = FieldFill.INSERT_UPDATE, update = "NOW()")
private LocalDateTime updateTime;

3. 调用 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）。

坑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 是一个优秀的增强工具，但它绝非“无脑”框架。

在实际项目中，建议遵循以下原则：

1. 简单单表用 MP，复杂查询用 MyBatis 原生 XML。
2. 分页查询避免联表扩展总数。
3. 手写 SQL 时要自己处理逻辑删除和分页参数。
4. 批量操作必须使用批量 SQL。
5. 版本号、枚举、JSON 字段要正确配置。
6. 条件构造器注意 null 值和括号问题。

希望通过这篇文章，你能在使用 MyBatis-Plus 时少踩坑，写出更健壮、更高效的代码。

如果还有其他“坑”欢迎评论区补充，我们一起避坑！