前两天在一个 Spring Boot 3 项目里集成 MyBatis-Plus应用刚启动就直接抛了一行报错Bean named ddlApplicationRunner is expected to be of type org.springframework.boot.ApplicationRunner。当时第一反应是版本问题但真排查下来发现这个报错背后牵扯到 starter 命名、自动配置机制、Spring Boot 3 的包迁移等多个因素远不是改一行配置就能糊弄过去的。如果你也正在用 Spring Boot 3 MyBatis-Plus或者准备从 Spring Boot 2.x 往上升级这篇文章应该能帮你省下大半天时间。我会从报错现场讲起逐步拆解为什么会出现类型不匹配再给出三种可落地的解决方案最后附上一份常见问题速查表。新手可以直接按第三部分的配置照抄老手可以看看第五部分的排查方法论项目里遇到同类问题不至于抓瞎。1. 报错现场与问题定性1.1 完整报错长什么样先看这个报错的完整形态。应用启动失败Spring Boot 会在控制台输出一段红色错误信息核心内容大致是*************************** APPLICATION FAILED TO START *************************** Description: Bean named dddlApplicationRunner is expected to be of type org.springframework.boot.ApplicationRunner but was actually of type com.baomidou.mybatisplus.extension.ddl.MybatisDDLApplicationRunner Action: Consider injecting the bean as one of its interfaces or forcing the use of a specific type in your configuration.注意Action里那句“考虑以接口方式注入”其实参考价值很低因为你的代码里根本没有主动注入过这个 Bean它是 MyBatis-Plus 自动配置在容器初始化阶段声明的。真正有信息量的是expected和actually这两行Spring 容器在创建名为ddlApplicationRunner的 Bean 时认为它应该是org.springframework.boot.ApplicationRunner类型但实际拿到的却是com.baomidou.mybatisplus.extension.ddl.MybatisDDLApplicationRunner。在这个报错出现之前通常还会有一串BeanCreationException、BeanNotOfRequiredTypeException之类的堆栈。堆栈的定位信息一般指向MybatisPlusAutoConfiguration也就是 MyBatis-Plus 的自动配置类。看到这里基本可以锁一级判断问题出在 MyBatis-Plus 的 starter 与当前 Spring Boot 版本不适配而不是你的业务代码写错了。1.2 为什么这个报错值得单独记录下来这个报错在 Spring Boot 3 项目里非常高频原因主要有两个。第一Spring Boot 3 改了底层的一些基础包名和接口定义MyBatis-Plus 在早期版本里并没有跟上这套改动。很多从 Spring Boot 2.x 平滑升级上来的项目代码几乎没动一启动就在这里炸掉。第二网上关于这个报错的资料鱼龙混杂。搜出来的结果有让你改SpringBootApplication排除项的有让你加spring.main.allow-bean-definition-overridingtrue的还有让你重写配置类的。这些办法有的能临时绕过但往往治标不治本下一次启动环境一变又冒出来。所以我一直认为解决一个报错比“复制一个解法”更重要的是先搞清楚这个 Bean 为什么会出现、为什么类型对不上。下面这部分就是根因拆解。2. 根因分析Spring Boot 3 与 MyBatis-Plus 的适配鸿沟2.1 Spring Boot 3 的自动配置机制变化Spring Boot 3 是一个跨代升级它把 Spring Framework 升到了 6.x同时还做了一件让所有 starter 维护者都必须跟进的事自动配置的加载机制变了。在 Spring Boot 2.x 时代自动配置类放在META-INF/spring.factories文件里通过org.springframework.boot.autoconfigure.EnableAutoConfiguration这个 key 声明。Spring Boot 3 引入了新的机制要求改用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件。表面上看只是路径和文件名变了但实际影响很大。旧式spring.factories的自动配置在 Boot 3 里虽然还能被兼容加载但 Spring Boot 3 在启动时对这类配置的处理逻辑并不一致Bean 定义的类型检查、条件注解的评估顺序都可能出现差异。MyBatis-Plus 早期版本的自动配置是基于 Spring Boot 2 的模型写的放在 Boot 3 里跑自然容易在容器 refresh 阶段出现各种“意想不到”。除了自动配置包迁移也是个关键点。Spring Boot 3 把很多javax.*命名空间的类换成了jakarta.*比如javax.servlet变成了jakarta.servlet。如果你在项目里直接依赖了基于javax编译的旧库轻则启动警告重则直接NoClassDefFoundError或当前这种类型不匹配。用个生活化的类比Spring Boot 2 和 3 的关系不是换个门牌号而是把整栋楼的承重墙都改过了。旧 starter 是按旧图纸盖的房间硬搬到新楼里看着都在但接口对不上。2.2 MyBatis-Plus 的适配路线从 3.5.3 开始的 boot3 分支MyBatis-Plus 官方对 Spring Boot 3 的支持是从 3.5.3 版本开始的。从那个版本起官方把 starter 拆成了两个坐标com.baomidou:mybatis-plus-boot-starter适用于 Spring Boot 2.xcom.baomidou:mybatis-plus-spring-boot3-starter适用于 Spring Boot 3.x这个变化是解决报错的关键线索。如果你在 Spring Boot 3 项目里还依赖的是mybatis-plus-boot-starter官方文档里虽然可能会告诉你“升级到 3.5.3 即可”但实际上更稳妥的做法是直接换成带spring-boot3标识的 starter。再看版本对应的关系。以目前使用比较多的几个版本为例MyBatis-Plus 版本对应 Spring Boot 3 的 starter 坐标兼容性说明3.5.3mybatis-plus-spring-boot3-starter首个支持 Boot 3 的版本基础可用3.5.4mybatis-plus-spring-boot3-starter修复了一些自动配置问题3.5.5mybatis-plus-spring-boot3-starter更多兼容性优化3.5.7mybatis-plus-spring-boot3-starter目前比较推荐的稳定版本这里要多说一句版本不是越新越好但在 Spring Boot 3 这个场景下3.5.5 及以上的版本明显比 3.5.3 稳定。我实测踩过 3.5.3 在某些 Boot 3.2 环境下的边界问题升级到 3.5.7 后没有再犯。2.3 ddlApplicationRunner 到底是什么为什么会挂在启动时ddlApplicationRunner是 MyBatis-Plus 提供的一个内部 Runner它的作用是在 Spring 容器启动完成后执行 DDL 相关脚本主要用于多数据源场景下的表结构初始化。凡是用到 MyBatis-Plus 的IDdl功能、DdlScript之类的时候这个 Runner 就会参与进来。它在自动配置里的定义大致思路是声明一个实现了org.springframework.boot.ApplicationRunner接口的 Bean名字叫ddlApplicationRunner。这个 Bean 本身不在你的业务代码里但你只要依赖了旧版 starterBoot 3 启动时就会尝试创建它。问题就出在类型检查上。Spring 容器内部创建完一个单例 Bean 后会拿当前容器所认可的ApplicationRunner类型和实际实例做匹配。在旧版 starter 编译时它写的很多类名、方法签名还是基于 Spring Boot 2 的org.springframework.boot.ApplicationRunner而 Spring Boot 3 容器在启动阶段对 Bean 的预期类型判断更严格两个类型在类加载器层面和自动配置层面的表现不一致于是直接抛出BeanNotOfRequiredTypeException也就是我们看到的“expected to be of type ... but was actually of type ...”。简单理解旧版 starter 说“我给你一个 ApplicationRunner”Boot 3 容器说“你这东西不是我认识的那个 ApplicationRunner”两边谈不拢启动就挂了。这个机制在社区里被大量验证过虽然不同中间版本细节有差异但核心方向是固定的旧 starter 和 Boot 3 不适配。3. 从零配置一次正确的 Spring Boot 3 MyBatis-Plus 整合3.1 正确的 Maven 依赖清单既然根因是坐标选错那最干净的做法就是从一开始把依赖写对。以一个 Spring Boot 3.2.x 项目为例POM 里的核心依赖这样写parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis-Plus for Spring Boot 3 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-spring-boot3-starter/artifactId version3.5.7/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency /dependencies注意两个点。第一不要去引mybatis-plus-boot-starter哪怕你看到的是最新版本号它在 Boot 3 项目里就是一个坑。第二MySQL 驱动从 Boot 3 开始默认使用com.mysql:mysql-connector-j而不是以前的mysql:mysql-connector-java这个在配置依赖时容易忽略。如果你还用到代码生成器或mybatis-plus-extension里的功能同样要把版本统一到 3.5.7。很多项目报类似错误就是因为核心包升了扩展包还停留在 3.5.1两个包混在一起启动时类加载器找不到对应类。3.2 最小可运行的配置与代码依赖写对之后配置文件可以保持接近 Spring Boot 2 时代的写法但有几处要留意。这是最小可运行的application.ymlspring: datasource: url: jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: banner: false db-config: id-type: auto mapper-locations: classpath*:mapper/**/*.xml启动类保持最简单SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }如果你需要分页功能一定要注册 MyBatis-Plus 拦截器。很多人在 Boot 3 项目里遇到“分页失效查询返回全部数据”的问题就是因为没有加这个配置类Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); PaginationInnerInterceptor pagination new PaginationInnerInterceptor(DbType.MYSQL); // 如果项目没有特殊要求这一行可以不写 // pagination.setMaxLimit(500L); // 如果想在超出限制时只返回前 N 条而不是抛异常可以设置 // pagination.setOverflow(true); interceptor.addInnerInterceptor(pagination); return interceptor; } }这里提一下maxLimit这个参数。MyBatis-Plus 分页插件默认不限制单页数量但有些团队为了避免一次性查全表会手动设置maxLimit500。这个设置本身没问题但它是一个“活动规则”不是默认规则。如果你看到“单页 500 条限制”相关的问题先检查是不是项目里有人主动加了这一行再决定调整参数还是去掉。3.3 启动前用依赖树自检在写代码之前还有一个高性价比的动作用 Maven 依赖树检查当前项目里到底引入了什么版本的 MyBatis-Plus。命令如下mvn dependency:tree -Dincludescom.baomidou输出里你会看到类似这样的内容[INFO] - com.baomidou:mybatis-plus-spring-boot3-starter:jar:3.5.7:compile [INFO] - com.baomidou:mybatis-plus-extension:jar:3.5.7:compile如果列表里同时出现了mybatis-plus-boot-starter和mybatis-plus-spring-boot3-starter那就是传递依赖把旧包带进来了。此时你需要用 IDEA 的 Maven Helper 插件或mvn dependency:tree -Dverbose进一步查看到底是哪个依赖把旧 starter 带了进来然后在对应依赖上声明exclusion。这种自检以后可以固化到 CI 流程里避免别人在协作时又悄悄引入了不兼容的旧包。很多时候启动报错的“元凶”并不是顶层 POM而是某个中间模块偷偷带进来的依赖。4. 报错后的三种解决方案与实操对比4.1 方案A切换到 mybatis-plus-spring-boot3-starter推荐如果你看到这里说明已经清楚问题本质了。最快的落地方案就是把依赖坐标换掉。具体操作分三步在pom.xml里删除或注释掉mybatis-plus-boot-starter的依赖。添加mybatis-plus-spring-boot3-starter依赖版本选 3.5.5 以上推荐 3.5.7。使用 IDE 的 Maven 面板执行reload或者跑一遍mvn clean compile。改完之后不需要改任何 Java 代码。我之前有一个项目同时用了mybatis-plus-extension和dynamic-datasource旧版本在 Boot 3 下总是报一些奇怪 Bean 的ClassCastException单纯把坐标换掉后问题全部消失。这个方案的好处是官方主动维护后续 Boot 3.x 的小版本升级也不会再出现同样的坑。坏处是你需要确认项目里有没有其他插件依赖了旧 starter 的包名有的话需要同步升级。4.2 方案B临时退回 Spring Boot 2.x不推荐但可以用有些项目不是你想升级就升级的。比如内部框架里有一堆老代码依赖了javax.servlet、javax.annotation或者某些二方包只提供了基于 Boot 2 的 starter。这种情况下“降级”反而成了一种快速恢复的手段。操作也不复杂。在pom.xml的parent里把 Spring Boot 版本改回 2.7.18同时把 MyBatis-Plus 依赖改回mybatis-plus-boot-starter版本可以选 3.5.2。如果需要代码里用到jakarta.*的地方也需要临时改回javax.*。但我必须强调这个方案只能作为“止血”不要作为长期方案。Spring Boot 2 已经进入维护末期社区和新功能的支持会越来越少。如果公司有明确升级计划建议把这个“降级”操作记在技术债务清单里说明原因和恢复条件。4.3 方案C排除自动配置手动兜底应急网上有帖子教你用exclude把MybatisPlusAutoConfiguration排除掉让 Spring 不创建ddlApplicationRunner比如这样SpringBootApplication(exclude { com.baomidou.mybatisplus.autoconfigure.MybatisPlusAutoConfiguration.class })这个做法能不能让启动不报错能。但代价非常大。排除自动配置后MyBatis-Plus 的 Mapper 扫描、SqlSessionFactory 创建、拦截器自动注册等一大堆默认逻辑都不会生效。你需要手动声明这些 Bean配置量不小还容易漏掉。这个方案我建议只在两种场景下用一是线上紧急恢复先让服务起来再说二是你明确不需要 MyBatis-Plus 的 DDL 功能并且愿意自己兜底。但凡项目还要正常使用 Mapper 和分页就不要长期开这个口子。4.4 三种方案对比什么时候选哪个方案操作成本维护成本风险适用场景切换 boot3 starter低换依赖即可低官方持续维护低Spring Boot 3 项目强烈推荐退回 Spring Boot 2.x低改版本号即可高后续升级困难中其他二方包不兼容 Boot 3 的临时场景排除自动配置手动兜底高大量手动配置高容易漏配置高紧急恢复或明确不用默认功能从项目长期健康度看方案 A 是唯一值得常驻的解法。方案 B 和 C 都该有明确“出口”不要让它变成常态化配置。5. 同类报错的排查方法论与避坑速查表5.1 排查流程见招拆招的五步法遇到这个报错我建议按下面的顺序排查而不是先去搜搜索引擎。第一步看异常顶部。确认报错 Bean 名和类型描述把Bean named xxx里的xxx记下来。第二步查依赖树。执行mvn dependency:tree -Dincludescom.baomidou看 mybatis-plus 系列依赖是否存在多个版本是否有旧 starter 混入。第三步定位自动配置来源。打开 jar 包里的META-INF/spring.factories或者META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports看MybatisPlusAutoConfiguration是通过哪种方式注册的。如果在 Boot 3 里还走的是旧方式大概率就是罪魁祸首。第四步反编译确认类型。用 IDEA 的依赖查看功能直接看MybatisPlusAutoConfiguration里ddlApplicationRunner的Bean方法签名。如果它返回的是ApplicationRunner但引入的包明显是旧版 Boot 的包路径基本可以定论。第五步选择解法。按第四部分的方案 A、B、C 的顺序择优处理。这套流程不只适用于ddlApplicationRunner。任何“Bean 类型不匹配”的报错都可以套用核心是先把依赖关系和自动配置来源理清楚。5.2 避坑速查表Spring Boot 3 MyBatis-Plus 常见问题对照我在实际项目里遇到过不少类似问题整理成一张速查表方便你在一线排查时快速对照报错或现象常见原因快速解决Bean named ddlApplicationRunner类型不匹配使用了mybatis-plus-boot-starter或版本混用换mybatis-plus-spring-boot3-starter3.5.7分页查询失效返回全部数据缺少MybatisPlusInterceptor和PaginationInnerInterceptor配置注册分页拦截器MySQL 报 1064 语法错误SQL 拼写错误、字段名包含关键字、增删改语句少条件开启 SQL 日志定位具体语句检查字段转义单页最大 500 条限制PaginationInnerInterceptor.maxLimit被设置为 500调整maxLimit-1或setOverflow(true)两个日志实现冲突启动警示 log4j2/logback引入了spring-boot-starter-log4j2同时保留 logback排除spring-boot-starter-logging统一日志框架ClassNotFoundException: jakarta.*或javax.*部分依赖还是基于javax编译升级依赖或退回 Boot 2.x 兼容对应版本这张表解决的是“一看到现象就能想到原因”的问题。真正想减少线上事故最好在项目初始阶段就把依赖坐标和常见配置固化好不要在代码里东改西改。5.3 我的实战心得最后分享几个踩过坑之后的体会希望能帮你少走弯路。第一在 Spring Boot 3 时代依赖坐标本身就是兼容性的第一道防线。看到mybatis-plus-boot-starter和mybatis-plus-spring-boot3-starter两个坐标时不要只盯着版本号先确认当前项目 Boot 大版本再选坐标。第二遇到类型不匹配的 Bean 报错别急着打开SpringBootApplication去 exclude。先想想这个 Bean 是哪儿来的是不是某个 starter 自动配置里的内部逻辑。很多时候随便 exclude 一个自动配置类表面解决了眼前问题却把更多默认行为一起关掉了。第三分页插件的maxLimit和overflow参数是双刃剑。不加限制高风险 SQL 可能把数据库拖垮加了限制业务侧又可能报“当前页数超出限制”的怪问题。建议结合团队规范和数据库性能基线定一个合理阈值比如单页最大 200 或 500并在项目文档里写明原因。我在实际工作中见过太多人在这个坑里反复跳了尤其是从 Spring Boot 2 升级到 3 的项目一启动就报ddlApplicationRunner。其实解法就那么一行坐标但搞清楚为什么比抄这一行更重要。希望这篇记录能帮你少碰几次壁把更多时间留给真正的业务逻辑。