SpringBoot 3.X 与 MyBatis-Plus 兼容性问题排查与解决方案

原创已于 2025-09-24 17:37:35 修改 · 1.2k 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#java #spring cloud #spring boot #mybatis

于 2025-09-24 17:29:30 首次发布

1. 背景与环境信息

1.1 技术背景

SpringBoot 3.X 是基于 Spring Framework 6+ 的重大版本更新，底层依赖存在多处不兼容变更（如 JDK 最低要求提升至 17、Spring 核心 API 调整、自动配置机制优化等）。而 MyBatis-Plus 早期的 mybatis-plus-boot-starter 是为 SpringBoot 2.X（依赖 Spring Framework 5+）设计的，直接在 SpringBoot 3.X 中使用会因 API 不兼容触发异常。

本次场景为搭建微服务架构时遇到的依赖兼容问题，核心技术栈围绕 SpringBoot 3.X 生态展开。

1.2 环境版本清单

依赖类型	具体版本	备注
JDK	17	SpringBoot 3.X 最低要求
SpringBoot	3.2.4	微服务核心框架
SpringCloud	2023.0.1	微服务治理框架，与 SpringBoot 3.2.x 兼容
SpringCloud Alibaba	2023.0.1.0	微服务组件集，适配 SpringCloud 2023.0.1
MyBatis-Plus（问题版本）	3.5.5	初始引入的普通 Starter，适配 SpringBoot 2.X
MyBatis-Plus（解决方案版本）	3.5.5	适配 SpringBoot 3.X 的 Boot3 Starter

2. 问题现象

在 SpringBoot 3.2.4 项目中引入 MyBatis-Plus 3.5.5 的普通 Starter 依赖后，服务启动直接抛出 类型不匹配异常，无法完成初始化。

2.1 问题依赖配置（错误示例）

xml

<!-- 错误依赖：适配 SpringBoot 2.X 的 Starter -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.5</version>
</dependency>

2.2 核心错误日志

plaintext

java.lang.IllegalArgumentException: Invalid value type for attribute 'factoryBeanObjectType': java.lang.String
    at org.springframework.beans.factory.support.FactoryBeanRegistrySupport.getTypeForFactoryBeanFromAttributes(FactoryBeanRegistrySupport.java:86)
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.getTypeForFactoryBean(AbstractAutowireCapableBeanFactory.java:814)
    at org.springframework.beans.factory.support.AbstractBeanFactory.isTypeMatch(AbstractBeanFactory.java:621)
    ...
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:343)

3. 根因分析

该异常的本质是 SpringBoot 3.X 与 MyBatis-Plus 旧 Starter 的依赖不兼容，具体原因如下：

Spring Framework 版本差异：SpringBoot 3.X 依赖 Spring Framework 6+，其 FactoryBean 相关 API 发生变更 ——factoryBeanObjectType 属性的类型要求从 Class 调整为 String（或需通过特定方式注入 Class 类型）。
MyBatis-Plus Starter 设计适配性：普通的 mybatis-plus-boot-starter（如 3.5.5 版本）是为 SpringBoot 2.X（依赖 Spring Framework 5+）设计的，其自动配置类（如 MybatisPlusAutoConfiguration）在初始化 SqlSessionFactoryBean 等 FactoryBean 时，仍按旧版 Spring API 注入 factoryBeanObjectType（Class 类型），导致 SpringBoot 3.X 解析时因类型不匹配抛出 IllegalArgumentException。
官方适配方案：MyBatis-Plus 团队为兼容 SpringBoot 3.X，单独提供了 mybatis-plus-boot3-starter，该 Starter 内部已适配 Spring Framework 6+ 的 API 规范，修复了 factoryBeanObjectType 等属性的类型注入问题。

4. 解决方案

核心操作：替换 MyBatis-Plus Starter 为 SpringBoot 3.X 专属版本，具体步骤如下：

4.1 调整 Maven 依赖

删除原有的 mybatis-plus-boot-starter，引入 mybatis-plus-spring-boot3-starter（版本保持 3.5.5 即可，该版本已支持 Boot3）：

xml

<!-- 正确依赖：适配 SpringBoot 3.X 的 MyBatis-Plus Starter -->
<!-- https://mvnrepository.com/artifact/com.baomidou/mybatis-plus-spring-boot3-starter -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.5</version>
</dependency>

4.2 验证结果

修改依赖后，重新启动 SpringBoot 服务：

服务可正常初始化，无 IllegalArgumentException 异常；
MyBatis-Plus 的核心功能（如 CRUD 接口、分页插件等）可正常使用。

5. 关键注意事项

5.1 版本匹配原则

SpringBoot 3.X ↔ MyBatis-Plus Spring Boot3 Starter：必须使用 mybatis-plus-spring-boot3-starter，而非普通 Starter；
版本兼容性：建议参考 MyBatis-Plus 官方文档的版本对应表，确保 Starter 版本与 SpringBoot 版本兼容（如 3.5.5 及以上 Boot3 Starter 适配 SpringBoot 3.0+）。

5.2 依赖冲突排查

若修改后仍有异常，可通过 Maven 命令查看依赖树，排查是否存在旧 Starter 残留：

bash

# 查看依赖树，搜索 mybatis-plus-spring-boot3-starter
mvn dependency:tree | grep mybatis-plus-spring-boot3-starter

若存在残留，需在 pom.xml 中排除旧依赖，例如：

xml

<dependency>
    <groupId>某第三方依赖</groupId>
    <artifactId>xxx</artifactId>
    <exclusions>
        <exclusion>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
        </exclusion>
    </exclusions>
</dependency>