Spring Boot 3.x 启动报错 factoryBeanObjectType 解决方案

🔍 关键信息提取

• 出问题的不是业务代码
• 出问题的是 Spring 在解析 FactoryBean 类型
• 类型不合法：String

四、问题本质：不是你代码的问题，而是「版本不兼容」

1️⃣ Spring Boot 3.x 变'严格'了

Spring Boot 3.x 底层升级到 Spring Framework 6.x 后，对 FactoryBean 做了更严格的类型校验：

• ❌ 不再允许 factoryBeanObjectType 是字符串
• ✅ 必须是：
  • Class
  • 或 ResolvableType

2️⃣ MyBatis / MyBatis-Plus 旧版本还在用老实现

旧版本的 mybatis-spring 或 mybatis-plus-starter 在注册 Mapper Bean 时：

factoryBeanObjectType = "com.xxx.UserMapper"; 

这是一个 String 类型，在 Spring Boot 2.x 没问题，
但在 Spring Boot 3.x 会直接抛 IllegalArgumentException。

参考 mybatis-spring-issues 855 得知：

📌 一句话总结根因：

Spring Boot 3 规则升级了，但 MyBatis 生态没同步升级

五、哪些情况下必踩这个坑？

你可以对照看看是不是下面的情况：

• ✅ Spring Boot 升级到了 3.x
• ✅ 项目中使用了 MyBatis 或 MyBatis-Plus
• ✅ 没有刻意升级 mybatis-spring 版本
• ✅ 启动 / 测试时报 FactoryBean 相关异常

👉 满足 2 条以上，基本就是这个问题。

六、实战解决方案（亲测有效）

⭐ 方案一：升级 MyBatis-Plus + 显式指定 mybatis-spring（推荐）

这是最稳妥、最推荐的解决方式。

Maven 配置示例

<!-- MyBatis-Plus Starter -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.5</version>
    <exclusions>
        <!-- 排除旧版本 mybatis-spring -->
        <exclusion>
            <groupId>org.mybatis</groupId>
            <artifactId>mybatis-spring</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- 引入 Spring Boot 3 兼容版本 -->
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis-spring</artifactId>
    <version>3.0.3</version>
</dependency>

📌 重点说明

• mybatis-spring 3.0.x 是官方适配 Spring Boot 3 的版本
• 不显式指定，很容易被 Starter 间接引入旧版本

⭐ 方案二：统一依赖版本（多模块项目推荐）

如果是企业项目或多模块工程，建议用 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.mybatis</groupId>
            <artifactId>mybatis-spring</artifactId>
            <version>3.0.3</version>
        </dependency>
    </dependencies>
</dependencyManagement>

这样可以避免不同模块依赖冲突。

七、辅助排查项（避免误判）

虽然不是根因，但也建议顺手检查：

@MapperScan("com.xxx.project.mapper")
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

• ✅ Mapper 包路径是否正确
• ✅ 没有重复扫描
• ✅ Mapper 接口不要用原始泛型

八、修复后验证（成功标志）

✅ 项目启动成功

Started Application in 3.1 seconds 

✅ 单元测试正常执行

Tests run: 5, Failures: 0, Errors: 0 

到这里，说明问题彻底解决。

九、总结（踩坑经验）

❗ 很多人第一反应是改配置、改代码，其实方向就错了

这个错误：

• ❌ 不是 Mapper 写错
• ❌ 不是配置文件问题
• ❌ 不是 Spring Boot Bug

✅ 本质是 Spring Boot 3 与旧版 MyBatis 生态不兼容

✅ 记住这条经验

Spring Boot 大版本升级，ORM 框架一定要同步升级