SpringBoot3对接MyBatis-Plus实用技巧

Spring Boot 3 上的项目可以正常跑通 MyBatis-Plus，控制台没有异常，CRUD 测试都通过。

接下来把我是怎么把整个流程从“报错一堆看不懂”变成“开箱即用”的，按步骤说清楚，尽量把那些容易踩的坑跟你掰开了说。先讲个最直观的验收方式：写个单元测试，启动 Spring 上下文，直接用 Mapper 的
insert/select/update/delete，控制台能看到 SQL（像 “==> Preparing: INSERT INTO …” 这种），返回的数据和断言都对了，那就说明依赖、配置、Mapper 扫描、XML 映射这些关键环节基本没问题。这一步像给车做个短途试驾，发动机、刹车、灯光都正常，才能往下拆细节。

配置层面几条必须确认的事儿。application.yml 的数据源信息要对：URL 带上时区和字符集参数，用户名、密码、driver-class-name 要和你用的驱动一致。常见写法大致是：

spring:

datasource:

url: jdbc:mysql://localhost:3306/testdb?useSSL=false&serverTimezone=UTC

username: test

password: test

driver-class-name: com.mysql.cj.jdbc.Driver

还有一点别忽视，Jackson 的日期配置之类有时候会影响测试输出格式，按需设置就行。数据库连不上，第一批要查的就是这几个字段和 pom 里有没有把驱动依赖加上。

依赖选型上，有两个红线要记清楚：Spring Boot 3.x 要用 Java 17+，MyBatis-Plus 选兼容 jakarta 命名空间的版本（3.5.x 开始有向 jakarta 迁移的版本），数据库驱动用 8.x 系列。pom 至少要有 spring-boot-starter-jdbc（或 data-jdbc），mybatis-plus-boot-starter，和 MySQL 驱动。版本不对就是那种深夜最爱报的 ClassNotFoundException，一般是由于项目里还有旧的 javax 包依赖或者某个中间库没换到 jakarta。

代码层面的检查和规范也很关键，照着下面走一遍就少犯错：

– 实体类需要无参构造和 getter/setter，必要时用 @TableName 指定表名，主键用 @TableId，字段用 @TableField 标注。

– Mapper 接口继承
com.baomidou.mybatisplus.core.mapper.BaseMapper，一般不用写方法就能用增删改查。想写自定义 SQL 就在 resources/mapper 下放 XML，namespace 必须写成 Mapper 接口的全限定名。

– XML 里每个 id 要和你在 Mapper 接口里要对应的方法名一致，如果全部用注解就能省掉 XML。

– ServiceImpl 里注入 Mapper 做业务逻辑，遇到需要事务的地方加 @Transactional。

– 主启动类放在主包路径下，别忘了在合适的包上加 @MapperScan(“com.example.mapper”)，包路径写错很容易导致 Mapper Bean 没被扫描到，从而在运行时抛空指针。

排查问题时的套路很像修房子遇到漏水：先看明显的地方，再一点点往里查。常用的手段和命令包括开 DEBUG 日志看 MyBatis-Plus 的自动配置细节，运行 mvn dependency:tree 查依赖冲突，启用 spring-boot-actuator 的 /beans 看容器里到底有哪些 Bean，确认 Mapper Bean 有没有被注册。如果日志里报找不到 jakarta 或 javax 某个类，往依赖里翻旧包；如果 SQL 一条没打印出来，优先核对数据源 URL、驱动和 Hikari 或其他连接池配置。

碰到几类常见错误和排查重点：

– 报 ClassNotFoundException：检查是不是还依赖着老的 javax 包，或者 MyBatis-Plus 版本太老、没兼容 jakarta。把版本链条对齐一般能解决。

– 数据源连接失败：核对 URL、用户名、密码、driver 是否正确，确认驱动的确在依赖树里（dependency:tree）。

– Mapper 返回 null 或 CRUD 报空指针：检查 @MapperScan 的包路径是不是覆盖到 Mapper 接口，Mapper XML 的 namespace 是否和接口全名一模一样，resources/mapper 是否被打包进 jar（有时 resource filtering 或打包插件会忽略）。

– 自动配置不生效：看日志里 MyBatis-Plus 或 DataSource 的自动装配是否被条件注入挡住了，或者某个 starter 被排除了。

我自己遇到过一种闹心情况：所有依赖看着都到位，但运行时 Mapper Bean 就没出来。排了半天才发现是 @MapperScan 写在了子包，根包没覆盖到。还有一次 SQL 打不出来，后来发现是本地测试用的 URL 写了 localhost 映射问题，换成 127.0.0.1 或修 hosts 就好了。再有就是依赖链里某个老包在暗中作怪，临时回退版本能跑，但根本缘由是没有把整体依赖升级到兼容 jakarta 的版本。总之，别一上来就大改逻辑，先把依赖和扫描路径核对齐，许多麻烦就能避免。

把整个调试过程当成排队片段处理：看日志，确认配置，检查依赖，再试不同版本。每一步都记录下来，出问题时贴出启动日志和 mvn dependency:tree，这两样东西对定位很管用。需要的话，把异常栈和依赖树发出来，我可以帮你分析哪里最可能出问题。