MyBatis-Plus与SpringBoot3版本不兼容如何解决？

Question

在升级Spring Boot 3.0后，MyBatis-Plus因依赖Spring Data Commons导致启动报错“java.lang.NoClassDefFoundError: org/springframework/data/repository/CrudRepository”。这是由于MyBatis-Plus早期版本未适配Spring Boot 3移除的类路径结构。该问题常见于使用mybatis-plus-boot-starter 3.5.3及以下版本的项目中，表现为应用无法正常启动，提示找不到Spring Data相关类。

Answer 1

1. 问题背景与现象描述

在将项目从 Spring Boot 2.x 升级至 Spring Boot 3.0 后，部分开发者发现应用启动失败，抛出如下异常：

java.lang.NoClassDefFoundError: org/springframework/data/repository/CrudRepository

该错误提示表明 JVM 在运行时无法找到 CrudRepository 类。尽管项目中并未显式引入 Spring Data JPA，但由于 mybatis-plus-boot-starter ≤ 3.5.3 版本内部依赖了 spring-data-commons，而该模块在 Spring Boot 3 中因 Jakarta EE 迁移和包路径变更（javax.* → jakarta.*）被重构或移除，导致类加载失败。

此问题是典型的“间接依赖冲突”案例，常见于微服务架构、多模块聚合构建的大型系统中。

2. 根本原因分析

• Spring Boot 3 的重大变更：Spring Boot 3 基于 Spring Framework 6，全面迁移到 Jakarta EE 9+，所有 javax.* 包名替换为 jakarta.*，同时清理了部分废弃模块。
• MyBatis-Plus 兼容性滞后：3.5.3 及以下版本编译时依赖的 spring-data-commons 使用的是旧版 Spring 框架类型，其内部引用了 CrudRepository 接口，但该接口在新环境中已被重定位或删除。
• 传递依赖未隔离：即使未使用 Spring Data 功能，只要 mybatis-plus-extension 或其他子模块存在对 spring-data-commons 的 compile 依赖，就会触发类加载尝试。

可通过执行以下命令查看依赖树：

mvn dependency:tree | grep "spring-data"

3. 解决方案层级递进

1. 升级 MyBatis-Plus 至兼容版本：推荐使用 3.5.4+ 或 3.5.5，这些版本已针对 Spring Boot 3 进行适配，移除了对 spring-data-commons 的强依赖。
2. Maven 配置示例：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.5</version>
</dependency>

MyBatis-Plus 版本	Spring Boot 兼容性	是否支持 Jakarta EE	建议状态
3.5.3 及以下	≤ 2.7.x	否	不推荐
3.5.4	3.0.x ~ 3.1.x	部分支持	可用
3.5.5	3.1+	完全支持	推荐
3.5.6+	3.2+	完全支持	生产首选

4. 替代处理策略（适用于无法立即升级场景）

若因历史原因无法升级 MyBatis-Plus，可采用以下临时方案：

• 排除冲突依赖：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.3</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.data</groupId>
            <artifactId>spring-data-commons</artifactId>
        </exclusion>
    </exclusions>
</dependency>

• 手动添加兼容桥接依赖（慎用）：引入特定版本的 spring-data-commons 以满足类存在性需求，但可能引发后续行为异常。

5. 架构设计启示与最佳实践

graph TD
    A[Spring Boot 2.x] -->|升级| B(Spring Boot 3.0)
    B --> C{检查第三方库兼容性}
    C --> D[MyBatis-Plus < 3.5.4?]
    D -->|是| E[升级至 3.5.5+]
    D -->|否| F[验证启动正常]
    E --> G[更新依赖并测试]
    G --> H[通过]
    F --> H
    H --> I[完成迁移]

该流程图展示了从版本升级到兼容性验证的完整决策路径。值得注意的是，此类问题不仅限于 MyBatis-Plus，还包括 PageHelper、Spring Security Oauth2 等早期生态组件。

建议建立技术债务看板，定期扫描 mvn versions:display-dependency-updates 输出，提前识别潜在升级风险。