MyBatis-Plus与MyBatis版本兼容性问题解析

MyBatis-Plus与MyBatis版本兼容性问题解析

【免费下载链接】mybatis-plus mybatis 增强工具包，简化 CRUD 操作。 文档 http://baomidou.com 低代码组件库 http://aizuda.com 项目地址: https://gitcode.com/baomidou/mybatis-plus

在使用Spring Boot 3构建项目时，许多开发者会遇到MyBatis-Plus与MyBatis框架之间的版本兼容性问题。本文将从技术角度深入分析这一常见问题的成因及解决方案。

问题现象

当开发者在Spring Boot 3项目中同时引入MyBatis和MyBatis-Plus依赖时，可能会遇到如下错误：

An attempt was made to call a method that does not exist. The attempt was made from the following location:
    com.baomidou.mybatisplus.core.MybatisMapperAnnotationBuilder.parse(MybatisMapperAnnotationBuilder.java:122)
The following method did not exist:
    'void org.apache.ibatis.session.Configuration.parsePendingMethods(boolean)'

这个错误表明MyBatis-Plus尝试调用MyBatis中不存在的方法，本质上是版本不兼容导致的API调用失败。

问题根源

1. 版本依赖冲突：MyBatis-Plus内部依赖特定版本的MyBatis，而项目直接引入的MyBatis版本与之不匹配
2. 方法签名变更：不同MyBatis版本中Configuration类的API发生了变化
3. Spring Boot Starter自动配置：Spring Boot的自动配置机制可能引入不兼容的依赖版本

解决方案

方案一：显式指定兼容版本

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.16</version>
</dependency>
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.7</version>
</dependency>

方案二：使用MyBatis-Plus Starter

MyBatis-Plus Starter已经包含了兼容的MyBatis版本，可以只引入Starter：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.8</version>
</dependency>

方案三：排除冲突依赖

如果必须使用特定MyBatis版本，可以通过排除冲突依赖：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.8</version>
    <exclusions>
        <exclusion>
            <groupId>org.mybatis</groupId>
            <artifactId>mybatis</artifactId>
        </exclusion>
    </exclusions>
</dependency>

最佳实践建议

1. 优先使用MyBatis-Plus Starter：它已经处理好版本兼容性问题
2. 避免混合使用不同来源的依赖：要么使用Spring Boot的MyBatis Starter，要么使用MyBatis-Plus Starter
3. 定期检查版本更新：关注MyBatis和MyBatis-Plus的版本发布说明
4. 使用依赖分析工具：如Maven的dependency:tree命令检查依赖冲突

技术原理深入

MyBatis-Plus在MyBatis基础上进行了扩展，其核心类MybatisMapperAnnotationBuilder需要调用MyBatis的Configuration类方法。当MyBatis版本升级后，如果方法签名发生变化而MyBatis-Plus未及时适配，就会导致此类兼容性问题。

理解这一点有助于开发者在遇到类似问题时快速定位原因：当看到"method does not exist"错误时，首先应考虑版本兼容性问题而非代码逻辑错误。

通过合理管理依赖版本，开发者可以充分利用MyBatis-Plus提供的便利功能，同时避免版本冲突带来的困扰。

【免费下载链接】mybatis-plus mybatis 增强工具包，简化 CRUD 操作。 文档 http://baomidou.com 低代码组件库 http://aizuda.com 项目地址: https://gitcode.com/baomidou/mybatis-plus