大二学完 MyBatis 再学 MyBatis-Plus，我踩过的 10 个坑

作者逆境不可逃技术永无止境希望我的内容可以帮助到你本节目属于专栏《后端新手谈》https://blog.csdn.net/2401_87662859/category_13141790.html大家吼 ! 我是 逆境不可逃 今天给大家带来文章《后端新手谈第十五期》《大二学完 MyBatis 再学 MyBatis-Plus我踩过的 10 个坑》.前言大二上学期我在课程设计里第一次用了 MyBatis。当时的感觉是写个用户管理模块增删改查四个功能Mapper 接口加 XML 写了一百多行。更崩溃的是后来老师说要加一个字段我从 Entity 改到 XML 再到 Service链式改动搞了十分钟。后来在 GitHub 上逛的时候看到了 MyBatis-Plus试着把它引入到自己的课设项目里发现明明能少写很多代码但班上同学用它的不多 —— 大部分人都觉得 反正 MyBatis 也能用干嘛多学一个。于是我把自己的课设从 MyBatis 迁到了 MyBatis-Plus过程踩了一堆坑但也实实在在少写了很多重复代码。这篇文章就是我的踩坑记录从一个正在学后端的普通大学生视角来写。读完你能收获什么每个改造点都知道原来怎么写、现在怎么写、坑在哪里拿到一套可以直接照着改的迁移顺序避开我踩过的那些让人调试到凌晨的坑不讲源码原理不讲官方文档里已有的内容只讲我自己亲历的东西。1. 依赖不是 加一个是 换一个我刚接触 MyBatis-Plus 的时候以为它是在 MyBatis 基础上再加一个依赖于是pom.xml里两个 starter 并存项目启动直接报 Bean 冲突看了半天日志才搞明白。原来 ——MyBatisdependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.0/version /dependency迁移后 ——MyBatis-Plusdependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.5/version /dependencyMyBatis-Plus 的 starter 已经内置了 MyBatis 和 MyBatis-Spring不需要也不应该再单独引入 MyBatis 依赖。如果你之前用了mybatis-spring-boot-starter直接删掉换上面这个。踩坑记录我第一次引入的时候只把 starter 换了但之前单独引的mybatis这个 artifact 忘了删。结果启动时报NoSuchMethodError查了半天 StackOverflow 才定位到是版本冲突。建议换完之后直接跑一下依赖树mvn dependency:tree | grep mybatis看到两个版本的 mybatis 相关包同时出现就说明还有没清干净的。2. Mapper 继承 BaseMapper—— 单表 CRUD 全消失了这是我感受到 MP 最有用的一步。原来在课设里 ——Mapper 接口 XML 双份维护Mapper public interface UserMapper { User selectById(Long id); int insert(User user); int updateById(User user); int deleteById(Long id); ListUser selectByCondition(String name, Integer age); }insert idinsert parameterTypecom.example.entity.User INSERT INTO user(name, age, email) VALUES(#{name}, #{age}, #{email}) /insert update idupdateById parameterTypecom.example.entity.User UPDATE user SET name#{name}, age#{age}, email#{email} WHERE id#{id} /update delete iddeleteById parameterTypelong DELETE FROM user WHERE id#{id} /delete select idselectById resultTypecom.example.entity.User SELECT * FROM user WHERE id#{id} /select课设里一个模块四五个这样的方法XML 轻轻松松上百行。这还是字段少的如果字段三十个光一个 insert 就几十行。迁移后 —— 继承 BaseMapperMapper public interface UserMapper extends BaseMapperUser { // 单表 CRUD 一个方法都不用写 }BaseMapper自带的方法包括方法说明insert(T entity)插入一条记录deleteById(Serializable id)根据 ID 删除updateById(T entity)根据 ID 更新selectById(Serializable id)根据 ID 查询selectList(WrapperT wrapper)条件查询列表selectPage(PageT page, WrapperT wrapper)分页查询selectCount(WrapperT wrapper)条件统计基本上原来单表的增删改查方法这些全包了。踩坑记录我第一次改的时候UserMapper继承了BaseMapper但忘了删 XML 里同名的方法。结果 BaseMapper 自带的insert方法调用时一直跳进我旧的 XML 里执行找了半天才发现 MyBatis 解析时 XML 会覆盖 BaseMapper 的同名 statement。迁移时记得把那些纯单表操作的 XML 片段删掉只保留多表联查。迁移前后对比迁移前 迁移后 ├── UserMapper.java (30行) ├── UserMapper.java (3行) ├── UserMapper.xml (200行) ├── UserMapper.xml (40行只剩联查) ├── OrderMapper.java (30行) ├── OrderMapper.java (3行) ├── OrderMapper.xml (180行) ├── OrderMapper.xml (35行只剩联查) └── ... └── ...3. XML 不用全删 —— 复杂查询原样保留迁移时我犯的第一个错误就是想把所有 XML 全删了全换 MP 的写法。后来发现根本没必要也做不到。MyBatis-Plus 对自定义 XML 完全兼容。Mapper 接口继承BaseMapper之后照样可以在同一个接口里定义自己的方法去调 XML。Mapper public interface UserMapper extends BaseMapperUser { // 多表联查——XML 写法和原来一模一样 ListUserOrderVO selectUserOrders(Param(userId) Long userId); // 复杂统计 BigDecimal selectTotalAmount(Param(startDate) Date startDate, Param(endDate) Date endDate); }对应的 XMLselect idselectUserOrders resultTypecom.example.vo.UserOrderVO SELECT u.name, o.order_no, o.amount FROM user u LEFT JOIN orders o ON u.id o.user_id WHERE u.id #{userId} /select一句话总结单表 CRUD 交给 BaseMapper多表联查和复杂 SQL 继续用 XML互不干扰。踩坑记录我当时自作聪明把 XML 里的resultMap映射全改成了实体类上的TableField注解结果 XML 引用不到映射直接报错。实际上你只需要在实体类上标注表名和主键XML 里的 resultMap 该怎么写还怎么写不用动。4. 条件构造器 ——WHERE 条件的写法完全不一样了这应该是我写代码时变化最大的一个点。原来课设里拼查询条件要么在 XML 里用if标签写动态 SQL要么在 Mapper 接口加一堆重载方法。MP 用条件构造器来替代。4.1 最基础QueryWrapper// 需求按姓名模糊搜索 年龄大于最小值 状态过滤按创建时间倒序 QueryWrapperUser wrapper new QueryWrapper(); wrapper.like(name, keyword) .gt(age, 18) .eq(status, 1) .orderByDesc(create_time); ListUser users userMapper.selectList(wrapper);等价于原来在 XML 里写的select idselectByCondition resultTypeUser SELECT * FROM user WHERE name LIKE CONCAT(%, #{keyword}, %) AND age 18 AND status 1 ORDER BY create_time DESC /select区别在于用 QueryWrapper 你不需要每多一个筛选条件就去改 XML 或 Mapper 接口Controller 里直接链式调用拼条件就行。4.2 推荐写法LambdaQueryWrapperQueryWrapper 有个问题name是手写字符串字段名写错了编译不报错运行才炸。// 不推荐字段名是字符串重构时 IDE 改不了这里 wrapper.eq(naem, value); // 拼错了编译器不会告诉你 // 推荐用 Lambda 引用编译期就能检查 LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.like(User::getName, keyword) .gt(User::getAge, 18) .eq(User::getStatus, 1) .orderByDesc(User::getCreateTime);以后实体类字段重命名IDE 一键重构这里自动跟着改再也不怕手滑打错字了。4.3 常用条件方法速查方法SQL 等价说明eq(name, val)name val等于ne(name, val)name val不等于gt(age, 18)age 18大于ge(age, 18)age 18大于等于lt(age, 18)age 18小于le(age, 18)age 18小于等于like(name, val)name LIKE %val%全模糊性能差慎用likeLeft(name, val)name LIKE %val左模糊likeRight(name, val)name LIKE val%右模糊走索引in(id, list)id IN (1,2,3)集合查询between(age, 18, 60)age BETWEEN 18 AND 60区间isNull(email)email IS NULL判空orderByAsc(age)ORDER BY age ASC升序orderByDesc(age)ORDER BY age DESC降序last(LIMIT 1)拼在最后慎用有 SQL 注入风险4.4 动态条件 —— 不用写if标签了原来在 XML 里拼动态条件select idselectByCondition resultTypeUser SELECT * FROM user WHERE 11 if testname ! null and name ! AND name LIKE CONCAT(%, #{name}, %) /if if testage ! null AND age #{age} /if /select用 Wrapper 的eq、like等方法传null时自动忽略该条件LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.hasText(name), User::getName, name) .gt(age ! null, User::getAge, age) .eq(status ! null, User::getStatus, status);第一个参数是boolean condition为false时不拼接该条件。这个设计让动态条件一行一个比 XML 的if堆叠清爽太多了。踩坑 1likevslikeRight。全模糊LIKE %keyword%不走索引能用likeRight前缀匹配LIKE keyword%就别用like。虽说课设数据量小感觉不出来但养成习惯很重要。踩坑 2别在last()里拼用户输入的内容。last()是直接字符串拼接不做参数化处理有 SQL 注入风险。只用来写硬编码的片段比如last(LIMIT 1)。5. 分页 —— 从手写两条 SQL 到一行 page ()课设里写列表接口套路基本是先写一条SELECT COUNT(*)查总数再写一条SELECT ... LIMIT offset, size查数据然后手动算offset (pageNum - 1) * pageSize。每张表都要重复一遍写得手酸。5.1 先配分页插件MP 的分页需要注册一个拦截器这一步我第一次漏掉了后面踩了个大坑Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); PaginationInnerInterceptor paginationInterceptor new PaginationInnerInterceptor(); paginationInterceptor.setDbType(DbType.MYSQL); // 按你的数据库类型来 interceptor.addInnerInterceptor(paginationInterceptor); return interceptor; } }MySQL 用DbType.MYSQLPostgreSQL 是DbType.POSTGRE_SQL。5.2 使用分页// 构建分页对象 PageUser page new Page(pageNum, pageSize); // 查询——自动查总数自动加 LIMIT PageUser result userMapper.selectPage(page, wrapper); // 取结果 ListUser records result.getRecords(); // 当前页数据 long total result.getTotal(); // 总记录数 long pages result.getPages(); // 总页数原来二三十行代码加两段 XML现在三行搞定。自定义 SQL 也能分页在 Mapper 方法里传入Page参数Mapper public interface UserMapper extends BaseMapperUser { PageUserOrderVO selectUserOrders(PageUserOrderVO page, Param(userId) Long userId); }select idselectUserOrders resultTypecom.example.vo.UserOrderVO SELECT u.name, o.order_no, o.amount FROM user u LEFT JOIN orders o ON u.id o.user_id WHERE u.id #{userId} /selectXML 里不用写 LIMIT 和 COUNTMP 自动帮你加。踩坑记录我第一次配的时候忘了写MybatisPlusInterceptor这个 Bean然后分页死活不生效查出来的数据永远是全表。课设里数据才几十条没发现后来往数据库里导了 5 万条测试数据接口直接卡了十几秒才反应过来。加上分页插件后一定验证一下执行的 SQL 有没有带 LIMIT。6. 主键策略 —— 不用每次都手动 set ID 了原来// 方式一依赖数据库自增 userMapper.insert(user); Long id user.getId(); // 依赖 MyBatis 的 useGeneratedKeys // 方式二自己生成雪花 ID user.setId(IdWorker.getId()); userMapper.insert(user);迁移后 —— 一个注解搞定Data TableName(user) public class User { TableId(type IdType.ASSIGN_ID) private Long id; private String name; }insert时不用手动 set IDMP 自动填充。几种主键策略策略说明适用场景ASSIGN_ID默认雪花算法Long 型分布式系统数据量大ASSIGN_UUIDUUIDString 型不需要有序 IDAUTO数据库自增单库MySQL 自增主键INPUT手动赋值使用外部生成的 ID全局改默认策略mybatis-plus: global-config: db-config: id-type: auto踩坑记录雪花算法生成的 ID 是 19 位的 Long超过了 JavaScript 的Number.MAX_SAFE_INTEGER2^53。我课设后端返回的 JSON 里 ID 是1234567890123456789前端拿到的变成了1234567890123456700精度丢了。前端同学调了半天说 接口返回的 ID 和数据库对不上查了俩小时才发现是 JSON 序列化的问题。解决方案—— 全局配置 Jackson 把 Long 转成 StringConfiguration public class JacksonConfig { Bean public Jackson2ObjectMapperBuilderCustomizer jackson2ObjectMapperBuilderCustomizer() { return builder - { builder.serializerByType(Long.class, ToStringSerializer.instance); builder.serializerByType(Long.TYPE, ToStringSerializer.instance); }; } }或者直接在字段上加TableId(type IdType.ASSIGN_ID) JsonSerialize(using ToStringSerializer.class) private Long id;7. 自动填充 ——createTime/updateTime 不用到处写了课设里每次 insert 和 update 都要手动 set 时间// 插入时 user.setCreateTime(new Date()); user.setUpdateTime(new Date()); userMapper.insert(user); // 更新时 user.setUpdateTime(new Date()); userMapper.updateById(user);代码写多了经常忘掉某一处然后数据库里的时间字段就是 null。查 Bug 的时候不知道这条记录是什么时候创建的很头疼。迁移后 —— 写一次全局生效Component public class MyMetaObjectHandler implements MetaObjectHandler { Override public void insertFill(MetaObject metaObject) { this.strictInsertFill(metaObject, createTime, Date.class, new Date()); this.strictInsertFill(metaObject, updateTime, Date.class, new Date()); } Override public void updateFill(MetaObject metaObject) { this.strictUpdateFill(metaObject, updateTime, Date.class, new Date()); } }实体类字段上标注Data public class User { TableField(fill FieldFill.INSERT) private Date createTime; TableField(fill FieldFill.INSERT_UPDATE) private Date updateTime; }FieldFill有四种值触发时机INSERT插入时填充UPDATE更新时填充INSERT_UPDATE插入和更新都填充DEFAULT不自动处理踩坑记录strictInsertFill是严格模式 —— 字段已经有值的时候不会覆盖。反过来setFieldValByName是无脑覆盖不管你手动设没设。我一开始两个混用排查了很久的 为什么我设的时间没有生效。建议统一用strict系列方法。8. 乐观锁 —— 一个 Version 注解不用手写版本号判断了乐观锁的原理每次更新时检查版本号对上了才更新同时版本号 1对不上说明别人先改了更新失败。原来手写步骤多还容易漏// 1. 查出当前版本 User user userMapper.selectById(id); Integer currentVersion user.getVersion(); // 2. 更新时带上版本号 user.setBalance(user.getBalance().subtract(amount)); user.setVersion(currentVersion 1); // 3. XML 里写UPDATE user SET balance#{balance}, versionversion1 // WHERE id#{id} AND version#{version} // 4. 检查影响行数——漏了这一步就白搭 int rows userMapper.updateByIdWithVersion(user); if (rows 0) { throw new RuntimeException(数据已被修改请重试); }四个步骤环环相扣漏一个乐观锁就形同虚设了。我在课设的秒杀模块里漏了第 4 步测试时超卖了一单还好只是模拟数据。迁移后—— 实体类上加个注解就行Data public class Product { private Long id; private String name; private BigDecimal price; private Integer stock; Version private Integer version; }配置拦截器Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); // 别忘了分页拦截器 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; }使用时就正常更新Product product productMapper.selectById(1L); product.setStock(product.getStock() - 10); int rows productMapper.updateById(product); // 自动执行UPDATE product SET stock?, versionversion1 // WHERE id? AND version? // rows0 说明版本冲突 if (rows 0) { throw new BusinessException(库存已变化请刷新后重试); }踩坑 1别忘了配OptimisticLockerInnerInterceptor否则Version不会生效SQL 里不会带 version 条件也不会自增。踩坑 2updateById如果传进来一个只设了 id 和要改字段的新对象version 是 nullMP 就不会带 version 条件。想用乐观锁保护更新必须先查出完整对象修改后再调 updateById。9. 逻辑删除 —— 不用每张表都手写软删除了原来做软删除每个删除接口写UPDATE user SET is_deleted 1 WHERE id ?每个查询的 SQL 都要带AND is_deleted 0。忘了带这个条件用户就能在列表里看到 已删除 的记录。迁移后——yaml 配一下加个注解就搞定mybatis-plus: global-config: db-config: logic-delete-field: deleted # 逻辑删除字段名 logic-delete-value: 1 # 已删除的值 logic-not-delete-value: 0 # 未删除的值实体类Data public class User { private Long id; TableLogic private Integer deleted; }效果// 你写的是 userMapper.deleteById(1L); // 实际执行UPDATE user SET deleted 1 WHERE id 1 AND deleted 0 // 你写的是 ListUser users userMapper.selectList(null); // 实际执行SELECT * FROM user WHERE deleted 0所有 SELECT 自动带deleted 0所有 DELETE 自动变 UPDATE非常省心。踩坑 1逻辑删除 唯一索引。比如手机号有唯一索引一个用户注销逻辑删除后另一个用户想用同一个手机号注册会因唯一索引冲突失败。解决方案要么把 deleted 字段加入联合唯一索引要么注销时把原值改成deleted_时间戳_原值。踩坑 2手写 XML 里的查询不会自动加deleted 0。如果自定义 SQL 也要过滤逻辑删除的数据得自己加AND deleted 0。10. 别急着用代码生成器先手改两个 MapperMP 的代码生成器AutoGenerator确实很爽 —— 连上数据库一键生成 Entity、Mapper、Service、Controller 全套代码分分钟搞定一个模块。但我的建议是初学的时候先别用它。原因很朴素生成出来的代码你不知道 BaseMapper 到底替你干了什么ServiceImpl 替你干了什么。跑起来没问题还好一旦有问题三个层面生成器代码、MP 框架、自己的业务逻辑搅在一起根本定位不到根因。我自己后来摸索出的顺序第一步改依赖把 mybatis-spring-boot-starter 换成 mybatis-plus-boot-starter 第二步挑 2 张最简单的表手改 Mapper 继承 BaseMapper删对应的 XML 单表操作 第三步在这 2 张表上把分页、自动填充、乐观锁、逻辑删除全配好确认跑通 第四步搞明白每个特性到底帮你干了什么之后再上代码生成器迁移剩下的表我第一次就是一脸懵直接上生成器结果分页、乐观锁、逻辑删除全是生成出来的默认配置好多都没真正启用但自己不知道。后来花了两天一行一行对比代码还不如一开始手写。总结这篇文章没讲 MyBatis-Plus 的全部功能挑了我在课设迁移过程中收益最高、自己也踩过坑的 10 个点。从一个普通大学生的角度来说MyBatis-Plus 最大的好处不是它功能多强而是它帮你省掉了大量 重复但不写不行 的代码。课设里几个模块改完之后XML 少了一大半终于不用在 加字段 → 改 XML → 改 Mapper → 改 Service 的链式操作上折腾了。如果让我用一句话总结MyBatis-Plus 不是要替代 MyBatis是让你把精力从写单表 CRUD 转移到搞定业务逻辑上。你也在用 MyBatis-Plus 吗踩过什么不一样的坑或者你还在犹豫要不要学顾虑是什么评论区聊聊吧。