mybatis-plus-boot-starter版本不兼容如何解决？

Question

在使用 MyBatis-Plus 时，若项目中引入的 `mybatis-plus-boot-starter` 与当前 Spring Boot 版本不兼容（如 Spring Boot 3.x 引入了 Jakarta EE，而低版本 MyBatis-Plus 仍依赖 javax 包），会导致应用启动失败，抛出 `ClassNotFoundException` 或 `NoClassDefFoundError`。典型表现为无法加载 `Configuration` 类或自动配置类失效。此问题多源于 starter 依赖版本不匹配，需根据 Spring Boot 版本选择适配的 MyBatis-Plus 版本，例如 Spring Boot 3.x 应使用 `3.5.0` 及以上版本的 `mybatis-plus-boot-starter`，并确保模块间版本协同，避免依赖冲突。

Answer 1

1. 问题背景与典型现象

在使用 MyBatis-Plus 的过程中，尤其是在升级 Spring Boot 至 3.x 版本后，开发者常遇到应用无法启动的问题。其根本原因在于 Spring Boot 3.x 正式迁移到了 Jakarta EE 9+ 命名空间，即所有原 javax.* 包被替换为 jakarta.*。而早期版本的 mybatis-plus-boot-starter（如 3.4.x 及以下）仍依赖于 javax.annotation、javax.persistence 等类库，导致 JVM 在加载自动配置类时抛出 ClassNotFoundException 或 NoClassDefFoundError。

典型错误日志如下：

java.lang.NoClassDefFoundError: javax/persistence/Entity
    at com.baomidou.mybatisplus.core.MybatisConfiguration.<clinit>(MybatisConfiguration.java:67)
    at com.baomidou.mybatisplus.autoconfigure.MybatisPlusAutoConfiguration.mybatisPlusConfigurable(MybatisPlusAutoConfiguration.java:115)

• 错误触发点通常位于 MybatisPlusAutoConfiguration 类初始化阶段
• 表现为 Spring 容器无法完成 Bean 的装配流程
• 即使手动排除某些依赖也难以根治，因核心模块仍绑定旧版 javax API

2. 核心机制分析：Spring Boot 3 与 Jakarta EE 迁移

维度	Spring Boot 2.x	Spring Boot 3.x
Servlet API	javax.servlet.*	jakarta.servlet.*
Persistence API	javax.persistence.*	jakarta.persistence.*
最低 Java 版本	Java 8	Java 17
MyBatis-Plus 兼容版本	<= 3.5.0	>= 3.5.0（Jakarta 支持）

从上表可见，Spring Boot 3 不仅是功能升级，更是生态体系的一次重大重构。MyBatis-Plus 若未适配 Jakarta 规范，则其内部引用的 @TableId、@TableName 所依赖的注解处理器将无法正常工作。

3. 版本匹配原则与推荐组合

为确保项目稳定运行，必须遵循以下版本协同策略：

1. Spring Boot 2.7.x → MyBatis-Plus ≤ 3.5.0：仍使用 javax 生态，无需迁移
2. Spring Boot 3.0 ~ 3.2 → MyBatis-Plus ≥ 3.5.0：官方开始支持 Jakarta EE
3. Spring Boot 3.1+ 推荐使用 MyBatis-Plus 3.5.3.1 或更高：修复部分反射兼容性问题
4. 若使用 mybatis-spring-boot-starter，需同步升级至 3.0+ 版本
5. 避免混合引入 mybatis-plus-boot-starter 与 mybatis-spring 低版本 jar 包
6. 建议通过 BOM（Bill of Materials）统一管理版本，如添加 mybatis-plus-dependencies

Maven 配置示例：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.baomidou</groupId>
      <artifactId>mybatis-plus-dependencies</artifactId>
      <version>3.5.3.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

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

4. 诊断流程图：快速定位兼容性问题

graph TD
    A[应用启动失败] --> B{是否报 ClassNotFoundException?}
    B -- 是 --> C[检查异常堆栈中是否含 'javax/' 类]
    B -- 否 --> D[排查其他配置问题]
    C --> E{是否使用 Spring Boot 3.x?}
    E -- 是 --> F[确认 MyBatis-Plus 是否 >= 3.5.0]
    E -- 否 --> G[检查是否意外引入 Jakarta 依赖]
    F --> H[升级 mybatis-plus-boot-starter 至 3.5.3.1+]
    G --> I[排除冲突依赖或降级 spring-boot]
    H --> J[清理 Maven 缓存并重新构建]
    I --> J
    J --> K[验证启动是否成功]

5. 深层解决方案与最佳实践

除了版本对齐外，还需关注以下几个高阶实践：

• 依赖树分析：使用 mvn dependency:tree 查看是否存在 javax.annotation:jsr250-api 与 jakarta.annotation:jakarta.annotation-api 冲突
• 自动配置排除：临时禁用 MyBatis Plus 自动配置以隔离问题：

  @SpringBootApplication(exclude = MybatisPlusAutoConfiguration.class)

• 条件化引入 Starter：在多模块项目中，通过 profile 控制不同环境下的依赖版本
• 自定义 ClassLoader 监控：利用字节码增强工具（如 ByteBuddy）监控类加载过程，捕获缺失类的精确调用链
• CI/CD 中集成版本合规检查：通过 Revapi 或 jApiCmp 检测 API 兼容性断裂

此外，社区已出现基于 SPI 机制实现的“兼容层桥接器”，可在不修改源码的前提下将部分 javax.* 调用转发至 jakarta.*，但该方案仅作为过渡手段，不宜长期使用。