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

问题背景

在使用Spring Boot 3.3.4脚手架创建项目时，当同时引入MyBatis和MyBatis-Plus依赖时，系统会抛出异常。这个问题的核心在于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)

错误明确指出MyBatis-Plus尝试调用MyBatis Configuration类中不存在的方法parsePendingMethods(boolean)，这表明两个框架的版本不匹配。

技术分析

版本依赖关系

MyBatis-Plus作为MyBatis的增强工具，其内部依赖于MyBatis核心库。当项目中同时显式声明MyBatis和MyBatis-Plus依赖时，可能会出现以下情况：

1. 脚手架默认引入的MyBatis版本(3.0.3)与MyBatis-Plus要求的MyBatis核心版本不兼容
2. 依赖传递导致MyBatis核心库版本冲突
3. MyBatis-Plus内部调用的API在项目中的MyBatis版本中不存在

解决方案

经过验证，以下依赖配置可以解决该兼容性问题：

<!-- MyBatis核心库 -->
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.16</version>
</dependency>

<!-- MyBatis-Plus Starter -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.7</version>
</dependency>

最佳实践建议

1. 避免使用脚手架默认的MyBatis依赖：脚手架可能引入的MyBatis版本可能与MyBatis-Plus不兼容
2. 显式声明MyBatis核心版本：建议明确指定MyBatis核心库版本，确保与MyBatis-Plus兼容
3. 检查版本兼容性：在引入新版本时，应查阅官方文档确认版本兼容性矩阵
4. 使用dependencyManagement：在大型项目中，建议使用dependencyManagement统一管理依赖版本

技术原理

MyBatis-Plus通过扩展MyBatis的核心功能实现增强特性。在启动过程中，MyBatis-Plus会：

1. 解析Mapper接口上的注解
2. 注册自定义的SQL注入器
3. 添加分页、性能分析等插件
4. 增强原有的Configuration功能

当MyBatis核心版本不匹配时，这些扩展功能可能无法正常工作，因为MyBatis-Plus依赖的某些内部API可能在新/旧版本中发生了变化。

总结

MyBatis生态系统的版本管理需要特别注意，特别是当同时使用MyBatis核心和MyBatis-Plus时。开发者应当：

1. 了解MyBatis-Plus与MyBatis核心的版本对应关系
2. 在项目中显式声明兼容的版本
3. 避免依赖传递带来的版本冲突
4. 定期检查并更新到稳定兼容的版本组合

通过合理的依赖管理，可以充分发挥MyBatis-Plus的强大功能，同时避免版本兼容性带来的问题。