我最近在过一套SpringCloud微服务课程第一天没有直接去碰Nacos注册中心也没有急着拆服务模块而是先把数据访问层的地基——MyBatis-Plus从头到尾快速过了一遍。很多刚从单体转微服务的同学会觉得这步有点多余但实际操作下来你会发现微服务拆得再细最终业务还是要落到数据库上持久层框架选不对后面每个服务模块都会跟着返工。这篇就把我第一天梳理出来的MyBatis-Plus常用注解、配置项和实操要点做个总结给准备学微服务、或者项目里想快速引入MyBatis-Plus的同学做个参考。内容不追求大而全只围绕第一天最需要用到的东西展开该给代码的地方给代码该讲坑的地方讲坑。1. 微服务架构下的数据访问层为什么第一步要选MyBatis-Plus先说一个很多人忽略的点微服务架构下数据库访问的复杂程度不是线性上升而是成倍增加的。一个单体项目里你只要维护一套Mapper层就够了微服务拆成十几个模块之后每个服务都要有自己的实体类、Mapper接口、XML文件。如果每个模块都用原生MyBatis去写基础的增删改查光是那些selectById、insert、update的重复代码就能把人写吐。课程第一天先讲MyBatis-Plus本质上是想让你在进入服务拆分之前就把数据访问层的基础工具打磨顺手。选型这个事儿我拿我自己的经验对比过三种方案方案单表CRUD效率复杂SQL可控性团队上手成本Spring Data JPA很高实体注解后基本不用写SQL一般复杂查询走Specification或原生SQL不直观中高很多人栽在对象映射的坑里原生MyBatis低每个方法都要写接口和XML很高SQL完全自己掌控低会SQL就会用MyBatis-Plus很高继承BaseMapper即有基础CRUD高需要复杂SQL时仍可写XML低SQL风格和MyBatis一脉相承这个对比其实挺直观的。课程里选MyBatis-Plus作为默认持久层方案核心逻辑就一句话只做增强不做改变。什么意思呢就是你原来用MyBatis写的那套XML、那些Mapper接口完全不用动MyBatis-Plus只是在上面多给你接了一层外挂帮你把最机械的单表CRUD干掉。这种“增强而非重写”的思路对微服务这种多模块场景特别友好——老模块不用推倒重来新模块可以站在更高效的起点上开发。第一天的学习目标也很明确就三件事把依赖和配置跑通把常用注解搞明白把CRUD和条件构造器用熟。这三个点覆盖了后续微服务开发中90%以上的数据访问场景剩下的复杂SQL、多表关联、分页优化都可以在真正遇到需求时再针对性深入。2. 环境接入依赖坐标、配置项与启动检查的完整记录2.1 引入MyBatis-Plus的正确姿势MyBatis-Plus的依赖引入有个特别容易踩的坑版本不匹配。我最初照着2.x时代的博客去配启动直接报了一堆ClassNotFoundException。这里直接给结论Spring Boot 2.x对应的是mybatis-plus-boot-starterdependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.5/version /dependency如果你的项目用的是Spring Boot 3.x依赖坐标会变成mybatis-plus-spring-boot3-starter这一点网上的老教程基本都没更新到位。选版本的原则是先看Spring Boot版本再去MyBatis-Plus官网上查对应的starter模块和版本号不要想当然下载最新版。另外如果你原来引入了mybatis-spring-boot-starter需要把它去掉MyBatis-Plus本身已经整合了MyBatis的能力两个starter同时存在时启动器优先级和组件扫描会出现意想不到的冲突。2.2 配置项的核心内容与测试环境配置Spring Boot的配置文件里数据源部分和平常一样需要注意的一点是MyBatis-Plus的基础配置。spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/cloud_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: table-prefix: id-type: assign_idmap-underscore-to-camel-case这个配置项MyBatis-Plus默认就是true会把数据库的user_name自动映射到Java实体类的userName字段这个设计极大减少了TableField注解的使用频率。log-impl设置为StdOutImpl后控制台会打印所有执行的SQL语句学习阶段建议一定要打开不然你根本不知道自己写的条件构造器生成了什么SQL。2.3 启动类的Mapper扫描两种方式推荐第一种MyBatis-Plus的Mapper接口扫描有两种方式。我个人推荐在启动类上加MapperScan一步到位SpringBootApplication MapperScan(com.example.cloud.**.mapper) public class CloudApplication { public static void main(String[] args) { SpringApplication.run(CloudApplication.class, args); } }另一种方式是在每个Mapper接口上加Mapper注解这种方式在Mapper数量少的时候还行微服务模块一多一个模块文件夹下塞十几个Mapper接口逐个加注解很烦漏掉一个启动就报错。第一次验证启动是否成功最直接的方法是写一个最简单的Mapper接口继承BaseMapper然后到测试类里跑一次查询。不要只盯着“启动成功”的日志真正的数据库连通性、Mapper映射问题都是在第一次查询调用时暴露的。3. 常用注解逐个拆解从表名映射到逻辑删除的边界问题3.1 TableName表名映射与全局前缀实体类和表名不一致时用TableName来指定TableName(t_user) public class User { ... }但更常见的情况是数据库表统一带了t_前缀如果每个实体都写一遍注解稍显繁琐。MyBatis-Plus提供了全局配置table-prefix配置了之后实体类可以直接省略TableName。比如我一期项目里用的规则就是所有业务表都有t_前缀此时配置table-prefix: t_实体类User默认对应表t_user命名清晰又省代码。这里提一个原则如果项目里表名统一有规则优先用全局配置只有零星几张表和实体名对不上时才用TableName单独标注两者的适用场景不要混。3.2 TableId主键生成策略的选择逻辑TableId用来标记主键字段核心是type属性的选择。MyBatis-Plus默认用的是ASSIGN_ID也就是雪花算法生成分布式ID。为什么不用数据库自增因为微服务环境下分库分表是常态两个库各自维护自增ID很容易撞车。雪花算法是全局唯一的虽然在单体项目里它看起来有点“大材小用”但从一开始就按微服务思路来设计后面做分库分表就不用再回头改主键了。TableId(type IdType.ASSIGN_ID) private Long id;雪花ID有一个衍生问题前端JS的Number类型最大安全整数是2^53-1雪花ID往往超过这个范围后端返回给前端时会出现精度丢失。如果使用过程中发现前端拿到的ID最后几位变成0就要考虑在序列化层把Long转成String返回。这个坑不是MyBatis-Plus本身的问题而是选型后带来的连锁反应课程第一天不用深究但要有这个意识。3.3 TableField字段映射、非表字段与自动填充TableField最常见的三个用途第一实体字段名和表字段名不一致时指定映射关系。虽然默认开启了下划线转驼峰但总有例外比如字段名缩写、特殊命名这时候就要显式声明TableField(nick_name) private String nickname;第二标记实体类中不是数据库字段的属性。比如你给实体加了一个不入库的冗余字段TableField(exist false) private String ageRange;如果没有exist falseMyBatis-Plus生成SQL时会尝试把这个字段拼进SELECT列然后数据库报“字段不存在”。这个坑几乎是初学者必踩的。第三配合自动填充。TableField(fill FieldFill.INSERT)、fill FieldFill.INSERT_UPDATE可以自动维护创建时间、更新时间这类字段。但要记住注解只负责“声明”真正执行填充逻辑的是实现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()); } }我一开始只加了TableField(fill ...)漏写了这个Handler组件结果插入数据时createTime一直是null排查了半天才发现是填充逻辑根本没注册到Spring容器里。这个知识点建议第一天就实践一遍因为后面每个微服务的表几乎都会有创建时间、更新时间字段。3.4 TableLogic逻辑删除的使用边界逻辑删除是指删除时不执行物理DELETE而是把某个标记字段更新为“已删除”MyBatis-Plus通过TableLogic注解支持这一特性TableLogic private Integer deleted;加了注解之后MyBatis-Plus会自动把查询语句拼上WHERE deleted 0把删除语句转换成UPDATE ... SET deleted 1的操作。这个机制本身非常好用但有两点必须提醒。第一逻辑删除和数据库唯一索引经常互相打架。比如用户表里用户名做了唯一索引用户点了注销走的是逻辑删除deleted字段置为1但记录还在表里。下一次新用户用同一个用户名注册唯一索引直接报冲突因为旧记录并没有物理消失。解决办法是在唯一索引的字段设计上把删除标记一起考虑进去或者逻辑删除字段存当前时间戳来区分记录而不是用固定的1。第二逻辑删除会穿透到关联查询里。如果其他表通过自定义SQL物理关联了这张表就会把已删除的数据也查出来。所以自定义SQL里记得手动加上deleted 0条件不能指望所有场景下MyBatis-Plus都帮你自动过滤。3.5 Version乐观锁注解先留个印象MyBatis-Plus还提供了乐观锁注解Version用于防止并发更新时的数据覆盖。配置方式和逻辑删除类似给实体加一个版本号字段注册一个OptimisticLockerInnerInterceptor拦截器执行updateById时MyBatis-Plus会自动生成UPDATE ... SET version version 1 WHERE id ? AND version ?的SQL如果更新时版本号不匹配影响行数为0说明数据被别人改过了。第一天课程一般不会深入到这里但后续做订单类业务、库存扣减时基本都会用到提前知道有这个东西遇到并发问题时能想到解决方案比临时去翻文档从容得多。常用注解汇总方便查阅注解作用关键配置TableName实体类映射表名table-prefix可全局配置TableId主键字段与生成策略默认ASSIGN_ID雪花算法TableField字段映射、非表字段、自动填充标记existfalse、fillINSERT_UPDATETableLogic逻辑删除标记配合logic-delete-value配置Version乐观锁版本字段需要注册拦截器EnumValue枚举字段与数据库值的映射尽量用枚举管理状态字段4. 从BaseMapper到条件构造器单表CRUD尽量不写一行SQL4.1 BaseMapper内置方法速查持久层接口继承BaseMapperT后无需编写任何实现类直接注入Mapper就能用的主要方法如下方法作用insert(entity)插入一条记录deleteById(id)根据主键删除deleteByIds(ids)批量删除3.5.7版本起推荐使用updateById(entity)根据主键更新selectById(id)根据主键查询selectBatchIds(ids)批量查询selectOne(wrapper)按条件查一条记录selectList(wrapper)按条件查列表selectPage(page, wrapper)分页查询初期把这些方法用熟练就够了。等两个实体之间有关系、需要多表关联查询时再自己写Select注解或XML方法。这里我个人的建议是selectOne不要指望它把数据查回来就算了MyBatis-Plus 3.5.x版本如果查到了多条记录会直接抛异常所以用selectOne之前最好先确认查询条件能唯一定位到一行数据比如按主键查询或者按业务唯一键查询。4.2 QueryWrapper与LambdaQueryWrapper选型理由条件构造器有两套。一套是QueryWrapper字段名以字符串形式传入QueryWrapperUser wrapper new QueryWrapper(); wrapper.eq(username, zhangsan).like(email, example.com);另一套是LambdaQueryWrapper用方法引用的形式LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.eq(User::getUsername, zhangsan).like(User::getEmail, example.com);我强烈建议团队统一用LambdaQueryWrapper。原因有两条编译期就能发现字段名拼写错误比如字段改名后字符串写法编译不报错、运行才报错而方法引用在编译时会直接标红重构时IDE能同步更新方法引用QueryWrapper的字符串则很容易被遗漏。至于网上常说的“Lambda性能差一点”在实际业务体量下基本可以忽略。4.3 条件构造器组合查询的一个真实例子课程里第一个比较完整的案例就是用户条件分页查询前端传用户名、状态、时间范围几个参数。用LambdaQueryWrapper组合出来的代码大概是这样public IPageUser queryUserPage(UserQuery query) { LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.hasText(query.getUsername()), User::getUsername, query.getUsername()); wrapper.eq(query.getStatus() ! null, User::getStatus, query.getStatus()); wrapper.between(query.getStartTime() ! null query.getEndTime() ! null, User::getCreateTime, query.getStartTime(), query.getEndTime()); wrapper.orderByDesc(User::getCreateTime); return userMapper.selectPage(new Page(query.getCurrent(), query.getSize()), wrapper); }这段代码值得注意的点是每个条件的前面都带了一个布尔表达式作为“是否拼接该条件”的判断这是MyBatis-Plus条件构造器的一个很实用的设计。like、eq、between这些方法的第一个参数是布尔值只有为true时条件才会拼进SQL。执行效果是前端传了名字就按名字查没传就不带这个条件避免了手动if层层嵌套的丑陋写法。4.4 ServiceImpl业务层的批量操作优化在Mapper之上MyBatis-Plus还有一层IService和ServiceImpl。业务Service接口继承IServiceT实现类继承ServiceImplMapper, T框架会自动注入BaseMapper并提供getById、saveBatch、updateBatchById、lambdaQuery、lambdaUpdate等一批业务层便利方法。public interface UserService extends IServiceUser { } Service public class UserServiceImpl extends ServiceImplUserMapper, User implements UserService { }很多人觉得这层可有可无但它在批量操作上有实际意义。userService.saveBatch(list)默认会分批执行insert内部做了JDBC批量提交的优化比在Mapper层写个foreach插入要优雅得多。微服务开发中经常要初始化导入一批数据用这个接口能省不少事。5. 分页插件与常用配置项文档里容易被略过的参数5.1 分页插件必须显式注册拦截器MyBatis-Plus的分页不是开箱即用的很多新手写了selectPage发现结果没有被物理分页或者总记录数不准原因就是没有注册分页拦截器。正确做法是在配置类里添加一个MybatisPlusInterceptorConfiguration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }DbType.MYSQL必须和实际数据库类型对应。这个配置看起来不起眼但少了它selectPage执行出来的SQL是完全不带LIMIT的等于把全表数据查回来后在内存里“假分页”等到数据量上来直接内存溢出。分页插件还有一个被低估的地方它会自动优化count查询。简单场景下MyBatis-Plus生成的SELECT COUNT(*)往往能去掉多余的表关联这一点对页面列表性能的贡献很多人在初期完全感知不到等项目数据量上来了才会意识到它的价值。5.2 常用配置项逐个排优先级MyBatis-Plus的global-config下有不少配置项第一天不建议全记把这几个用熟就不错了配置项作用我的建议db-config.id-type全局主键策略默认assign_id即可不要贸然改autodb-config.table-prefix表名前缀看项目表命名规范再配db-config.logic-delete-field逻辑删除全局字段名多个实体统一叫deleted时很好用db-config.logic-delete-value逻辑删除的标记值默认1和数据库约定一致即可configuration.log-implSQL日志输出开发环境用StdOutImpl生产环境务必关掉configuration.map-underscore-to-camel-case下划线转驼峰默认true一般不动逻辑删除的全局配置有一个意义配置了logic-delete-field之后实体里不需要在每个删除字段上都加TableLogic注解只要字段名匹配就会自动生效。团队里如果有成员忘记加注解的情况全局配置能兜底。5.3 分页参数的最佳实践Page对象在接口层怎么接收、怎么返回课程里给了一个很推荐的写法PageUser page new Page(query.getCurrent() null ? 1 : query.getCurrent(), query.getSize() null ? 10 : query.getSize()); IPageUser result userMapper.selectPage(page, wrapper); // 返回给前端时 PageResultUser pageResult new PageResult(); pageResult.setTotal(result.getTotal()); pageResult.setRecords(result.getRecords());不要直接返回Page对象给前端因为Page里有不少框架内部属性直接暴露容易泄露分页逻辑也容易埋下安全隐患。自己定义一个PageResult只返回total和records接口结构干净后面调整分页策略不会影响前端协议。6. 实践中的高频坑与解决方案6.1 字段映射失败的第一现场我在配置阶段遇到的最典型问题实体类有个字段叫isDeleted数据库列叫deletedselectById查出来该字段一直是null。原因也很简单isDeleted这种命名在Java里生成的getter是getDeleted()而MyBatis-Plus默认的下划线转驼峰规则把deleted按delete_d去找映射了根本对不上。解决方案是避免字段名以is开头或者显式加TableField(deleted)。这个问题的教训是不要过度依赖自动映射涉及布尔字段、字段别名这些边缘情况时宁可多写一个注解也不要留到线上查数据时才去抓瞎。6.2 主键生成策略不可乱改有同学图省事把TableId的type直接设置为IdType.AUTO期望数据库自增。如果表本身没有设置自增主键或者后续分库分表插入时就会因为主键冲突或主键为空而失败。ASSIGN_ID虽然生成的ID看起来很长但它在分布式环境下是安全的建议保持默认没事别乱换。如果项目里确实用了数据库自增主键需要确认每张表都设置了AUTO_INCREMENT而且要接受它无法平滑扩展的事实。6.3 自动填充不生效的三种可能性自动填充字段不生效按顺序排查三个地方实体字段上是否加了TableField(fill ...)是否写了MetaObjectHandler实现类并加上了Component注解strictInsertFill里填写的字段名是否和实体属性名完全一致。我遇到的几乎都是第三种拼写或大小写差异导致填充静默失败。6.4 逻辑删除、唯一索引与业务冲突之前说过逻辑删除和唯一索引冲突的问题这里再讲一种更隐蔽的变体一个用户多次注册时逻辑删除标记如果固定为1旧记录和新记录会同时存在。比如唯一索引是(username, deleted)删了两条记录后这两条记录都是usernametest, deleted1唯一索引照样冲突。网上有个常见做法是逻辑删除字段存储删除时间戳——删除时把当前毫秒数写入该字段未删除为0。这样每条删除后的记录在索引中的值都不同唯一索引不会冲突但存储空间和索引体积会变大取舍需要结合项目实际。简单说逻辑删除不是银弹用了它就要在唯一索引设计上全盘考虑。6.5 批量操作千万别逐条循环saveBatch虽然好用但默认批处理大小是1000。如果一次性要插入几万条数据建议手动拆批每500条提交一次避免单次提交SQL过大拖垮数据库。另外要注意MyBatis-Plus的批处理走的不是MySQL的INSERT INTO ... VALUES (...), (...)一次性拼接而是foreach循环多条SQL性能上比原生批量插入的rewriteBatchedStatementstrue还是会差一截。数据量达到十万级别以后建议单独写自定义SQL配合MySQL的批量插入语法做优化。7. 写到最后第一天课程的落地体会按照这套配置和方法我第一天就把MyBatis-Plus的基础能力全部跑通了。从实际开发的角度说第一天掌握这些已经足够支撑后续SpringCloud微服务模块的数据访问需求——每个服务模块都有一套自己的实体、Mapper和ServiceMyBatis-Plus把90%的机械重复工作都接住了剩下需要写自定义SQL的场景也能基于原有的MyBatis配置无缝衔接。还有一个小技巧想分享给刚入门的朋友学完第一天内容之后建议自己做一个最小的无业务逻辑Demo工程把实体类、Mapper、Service、配置类完整地搭一遍不要只在课程代码里跑内在。我当时就是因为项目已经跑起来了又花了几分钟单独建了个测试工程把所有注解都过了一遍后面做微服务模块时几乎没再被配置问题绊过脚。框架这种东西看十遍不如亲手搭一遍。