1. 项目背景当MyBatis遇上MyBatis Plus在Java后端开发领域数据持久层框架的选择几乎绕不开MyBatis。它凭借灵活的SQL映射和强大的动态SQL能力成为了众多项目的标配。然而随着项目迭代和团队更替一个有趣且棘手的情况时常发生一个老项目其核心数据访问层基于经典的MyBatis构建积累了大量的XML映射文件和手写的复杂SQL与此同时为了提升新功能模块的开发效率团队又引入了MyBatis Plus简称MP——这个在MyBatis基础上进行增强的“瑞士军刀”。于是一个项目中MyBatis和MyBatis Plus并存的“混合架构”就诞生了。这种并存并非设计之初的本意更多是历史包袱与技术演进妥协的产物。你可能接手了一个老系统里面是密密麻麻的SqlSessionTemplate和Mapper.xml而新接手的同事或你自己又想用MP的LambdaQueryWrapper和ServiceImpl来快速搞定CRUD。两者在Spring的IoC容器里和平共处了吗表面上看项目能启动但当你真正开始编码各种诡异的问题便接踵而至自定义的MyBatis插件如分页插件对MP生成的SQL失效了事务管理突然变得不可预测更严重的是在同一个事务方法里混用两者操作同一张表可能引发意想不到的运行时异常。这不仅仅是“能不能用”的问题而是“如何用得稳、不出错”的实战挑战。本文将深入剖析MyBatis与MyBatis Plus并存的底层原理、常见冲突场景并提供一套从配置隔离到编码规范的全方位解决方案。无论你是正在面临此困境的开发者还是希望提前规避此类架构问题的技术决策者这些从实际踩坑中总结的经验都值得你仔细阅读。2. 理解并存架构的底层冲突根源要让两者和平共处首先得明白它们为什么会“打架”。MyBatis Plus并非一个完全独立的ORM框架它是对MyBatis的增强其核心是通过继承MyBatis原有的SqlSessionFactory、Mapper等组件并注入自己的实现逻辑如SqlInjector来工作的。当两者共存时冲突主要发生在Spring容器的Bean管理、MyBatis的核心组件初始化以及SQL执行链路这三个层面。2.1 Spring Bean的注册与覆盖之争在典型的Spring Boot项目中我们通常通过MapperScan注解来扫描并注册MyBatis的Mapper接口。而MyBatis Plus则提供了自己的MapperScan来自com.baomidou.mybatisplus.core.mapper包它内部集成了MP的特殊处理逻辑。如果你在代码中同时出现了两个MapperScan或者错误地混用了它们就会导致Mapper接口被重复注册或注册到错误的SqlSessionFactory上。更隐蔽的问题是SqlSessionFactoryBean。MyBatis的SqlSessionFactory是通过SqlSessionFactoryBean这个FactoryBean在Spring中创建的。MP通过自动配置类MybatisPlusAutoConfiguration会向容器中注册一个经过MP增强的SqlSessionFactory。这个增强的Factory会加载MP的内置插件如分页插件、性能分析插件等和全局配置。如果你的项目里同时存在一个你自己手动配置的、纯MyBatis的SqlSessionFactoryBean那么根据Spring的Bean覆盖规则通常后定义的会覆盖先定义的只有一个会生效。如果手动配置的纯MyBatis版本生效了那么MP的所有增强功能都将失效。2.2 Mapper接口的代理生成机制混淆MyBatis通过JDK动态代理为Mapper接口生成实现类。MP在此基础上做了扩展它生成的代理类不仅包含从XML或注解中解析的SQL还注入了一系列MP内置的通用方法如selectById、insert等。当你的一个Mapper接口同时被MyBatis和MP的扫描机制处理时可能会生成两个不同的代理Bean造成NoUniqueBeanDefinitionExceptionBean不唯一异常。或者虽然只有一个Bean但其代理逻辑混杂了非预期的行为。2.3 插件与拦截器链的冲突MyBatis的插件机制是其强大扩展性的基石它通过Interceptor接口实现。MP的分页、乐观锁、动态表名等功能本质上都是通过实现Interceptor来实现的。当项目中既有MP的插件又有自定义的MyBatis插件例如一个用于打印SQL日志的自定义插件时它们会被添加到同一个InterceptorChain中。插件执行顺序取决于它们被添加的顺序。如果顺序不当可能会导致SQL被多次改写、参数被错误处理等问题。例如你的自定义日志插件可能在MP分页插件修改SQL之前就打印了日志导致你看到的“执行SQL”并不是最终发送给数据库的SQL。2.4 事务管理与SqlSession绑定在Spring托管的事务中MyBatis会将一个SqlSession与当前线程绑定。无论你是通过传统的SqlSessionTemplate执行SQL还是通过MP的BaseMapper执行理论上都应该使用同一个SqlSession以确保事务的一致性。但在混合环境下如果配置不当可能导致两者使用了不同的SqlSession实例从而破坏事务的原子性。例如通过MyBatis的SqlSessionTemplate插入一条数据再通过MP的Service更新另一条数据在同一个Transactional方法中后者可能会因为使用了不同的数据库连接而无法看到前者的插入结果在事务隔离级别为“读已提交”时或者更糟导致更新操作不在同一个物理事务中。3. 核心配置策略实现清晰隔离与共存解决冲突的关键在于清晰的隔离和正确的配置顺序。我们的目标不是让两者完全融合而是划定边界让它们各自负责擅长的领域互不干扰。3.1 统一的SqlSessionFactory配置推荐方案这是最根本、最推荐的解决方案。放弃维护两套独立的配置只使用MyBatis Plus增强后的SqlSessionFactory让它来统一管理所有的Mapper无论是需要复杂SQL的老Mapper还是使用MP便捷功能的新Mapper。如何配置在Spring Boot项目中这通常是最简单的因为MP的Starter已经帮你做好了。你只需要确保引入的是mybatis-plus-boot-starter依赖而不是原始的mybatis-spring-boot-starter。在配置文件中正确设置mybatis-plus的相关属性特别是mapper-locations这个路径需要包含所有的Mapper XML文件包括老项目遗留的和为MP新写的。# application.yml mybatis-plus: # 指定XML文件位置支持通配符 mapper-locations: classpath*:mapper/**/*.xml # 实体扫描多个package用逗号隔开 type-aliases-package: com.yourcompany.entity global-config: db-config: id-type: auto # 主键策略 configuration: # 开启驼峰命名转换 map-underscore-to-camel-case: true # 打印SQL配合日志级别使用 log-impl: org.apache.ibatis.logging.stdout.StdOutImpl关键点mapper-locations必须覆盖所有XML。老项目的XML文件可以继续使用传统的#{}、动态SQL标签完全兼容。新写的Mapper接口如果想用MP功能就继承BaseMapper如果只是需要传统MyBatis的XML映射就不继承。MP的SqlSessionFactory能完美处理这两种情况。3.2 扫描注解的精准控制使用MP提供的MapperScan注解并指定正确的扫描路径。绝对不要同时使用MyBatis原生的org.apache.ibatis.annotations.Mapper注解和MP的扫描。Configuration // 使用MP的MapperScan并指定扫描的包路径 MapperScan(basePackages com.yourcompany.mapper) public class MybatisPlusConfig { // 此处可以配置MP的全局策略、插件等 Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 添加分页插件 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 添加乐观锁插件如果需要 // interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); return interceptor; } }将所有的Mapper接口都放在com.yourcompany.mapper包或其子包下。这样无论是继承BaseMapper的接口还是不继承的纯接口都会被MP统一处理。3.3 自定义插件与MP插件的顺序管理如果你有自定义的MyBatis插件需要将其添加到MP的MybatisPlusInterceptor中或者确保它们以正确的顺序注册。方案一将自定义插件添加到MP的拦截器链MP的MybatisPlusInterceptor本身就是一个拦截器它内部维护了一个拦截器列表innerInterceptors。你可以创建自己的InnerInterceptor实现并将其加入这个链这样可以保证插件执行顺序与MP内置插件协调。Component public class CustomSqlInterceptor implements InnerInterceptor { Override public void beforeQuery(Executor executor, MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException { // 你的自定义逻辑例如对特定SQL添加租户过滤条件 System.out.println(自定义插件执行前SQL: boundSql.getSql()); } } Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor(CustomSqlInterceptor customInterceptor) { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 注意顺序先添加自定义的后添加MP的如分页取决于你的业务逻辑 interceptor.addInnerInterceptor(customInterceptor); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }方案二注册独立的Interceptor需谨慎你也可以像传统MyBatis一样通过Bean直接注册一个实现Interceptor接口的插件。但这时你必须显式地在配置中设置插件的执行顺序通过Order注解或实现Ordered接口并充分测试其与MP插件的交互。Bean Order(1) // 确保在MP拦截器之前执行 public Interceptor customLogInterceptor() { return new Interceptor() { // ... 实现方法 }; }注意方案二更容易引发不可预见的冲突尤其是在涉及SQL改写如分页时。优先推荐方案一。4. 编码实践在混合环境中安全操作配置是基础编码是实践。在混合架构下写代码需要遵循一些明确的规则以避免掉入陷阱。4.1 Mapper接口的继承策略使用MP功能的Mapper让其继承com.baomidou.mybatisplus.core.mapper.BaseMapper。这样可以直接使用insert、selectById、update等方法以及配合QueryWrapper进行条件查询。import com.baomidou.mybatisplus.core.mapper.BaseMapper; public interface UserMapper extends BaseMapperUser { // 也可以在此定义自己的方法并在XML中实现 ListUser selectComplexUsers(Param(role) String role); }仅使用传统MyBatis的Mapper不要继承BaseMapper。所有方法都在XML文件中定义。MP的SqlSessionFactory同样能正确解析和执行它们。// 不继承BaseMapper public interface LegacyOrderMapper { LegacyOrder findOrderWithDetails(Param(orderId) Long orderId); }绝对禁止同一个Mapper接口既继承BaseMapper又在XML中定义了同名的方法。这会导致方法冲突MP生成的方法会覆盖XML映射的方法或者反之结果不可预测。4.2 Service层的设计与选择MP提供了强大的IService和ServiceImpl它们封装了常见的服务层逻辑。在混合架构中你可以有选择地使用对新实体或纯CRUD的业务创建对应的Service接口继承IService实现类继承ServiceImpl。这是最高效的方式。public interface UserService extends IServiceUser {} Service public class UserServiceImpl extends ServiceImplUserMapper, User implements UserService {}对涉及复杂业务逻辑、需要调用多个传统Mapper的老业务建议不要强行使用MP的ServiceImpl。可以继续使用传统的Service类在其中注入所需的多个Mapper无论是继承BaseMapper的还是传统的在方法内编排复杂逻辑。这样更清晰也避免了将MP的架构风格强加于复杂旧代码之上。4.3 事务管理的统一性这是混合架构下最容易出错的地方之一。确保事务一致性请牢记使用Spring的Transactional注解管理事务无论是在MP的ServiceImpl方法上还是在传统的Service类的方法上都统一使用Spring的声明式事务。避免在事务方法内混用不同数据源/SqlSessionTemplate在我们的场景中只要按照第3节的配置使用了统一的MPSqlSessionFactory那么所有Mapper操作默认都在同一个Spring事务管理的数据源和SqlSession上下文中。这一点需要确保。测试事务回滚编写单元测试或集成测试验证在混合调用例如先通过传统Mapper插入再通过MP Service更新然后抛出异常时事务是否能正确回滚。一个常见的坑是在同一个Transactional方法内先调用一个this.updateById()MP方法再调用一个this.someComplexMethod()其内部使用了SqlSessionTemplate执行原生SQL。如果someComplexMethod()是同类中的另一个方法并且其内部使用了REQUIRES_NEW之类的事务传播属性就可能破坏事务链。务必理清事务边界。4.4 解决removeBatchByIds与removeByIds的混淆这是一个来自热词的典型问题。在MP中removeByIds(Collection? idList)是BaseMapper接口中的方法。它根据主键ID集合批量删除数据。其内部实现是生成一条DELETE FROM table WHERE id IN (?, ?, ...)的SQL语句。removeBatchByIds(Collection? idList)这个方法并不存在于标准的BaseMapper或IService中。它可能是某些项目自定义的方法或者是早期版本、特定分支中的方法其意图可能是进行“真正的”批量操作例如使用ExecutorType.BATCH模式执行多条DELETE语句。在并存项目中如果你看到或想使用removeBatchByIds必须首先确认其来源。如果是自定义的请查看其实现逻辑。如果项目不需要特殊的批量执行优化强烈建议统一使用标准的removeByIds。因为IN语句在大多数数据库和场景下对于几十上百条数据的删除效率已经足够且逻辑清晰。如果确有大批量删除例如上万条的需求应考虑分页分批调用removeByIds或者使用自定义的Mapper方法编写更优化的SQL如DELETE FROM table WHERE create_time ?而不是纠结于某个不存在的“批量”方法。5. 常见问题排查与实战调试技巧即使配置得当在开发中仍可能遇到一些怪问题。这里分享几个实用的排查技巧。5.1 SQL打印与日志分析在混合架构下看清最终执行的SQL至关重要。配置mybatis-plus.configuration.log-impl如上文配置可以设置为控制台打印。但更推荐与SLF4J日志框架集成在application.yml中配置logging: level: # 将你项目mapper接口所在的包设置为DEBUG级别 com.yourcompany.mapper: DEBUGMyBatisMP会自动将执行的SQL日志输出到该Logger下。使用MyBatis Log Plugin这是IDEA的一款免费插件它能将MyBatis执行的SQL语句包括参数从日志中提取出来并格式化成可直接在数据库客户端执行的语句极大方便调试。安装后在控制台找到MyBatis Log标签页即可。鉴别SQL来源在日志中注意看SQL语句前的准备语句Preparing:和参数Parameters:。如果SQL中包含了LIMIT ?而你并没有写那很可能是MP的分页插件添加的。这有助于判断是传统XML的SQL生效了还是MP的Wrapper生成的SQL生效了。5.2 使用Arthas诊断SQL生成过程当遇到动态SQL生成不符合预期或者插件是否生效存疑时Arthas这个Java诊断神器可以派上用场。特别是热词中提到的“抓取MyBatis生成的SQL”。跟踪Mapper代理方法你可以使用Arthas的trace命令跟踪Mapper接口方法的调用链路看到底层SqlSession的调用和SQL执行。# 启动Arthas并attach到你的Java进程后 trace com.baomidou.mybatisplus.core.override.MybatisMapperMethod execute但这需要比较了解MyBatis内部类名。一个更实用的方法是监控JDBC操作Arthas可以监控所有JDBCPreparedStatement的执行。watch java.sql.PreparedStatement execute {params, returnObj, throwExp} -x 3这会将所有SQL执行时的参数和结果打印出来无论它来自MyBatis还是MP是最直接的查看方式。5.3 处理动态表名等高级特性MP提供了动态表名插件DynamicTableNameInnerInterceptor。在混合架构下使用需注意插件需全局配置按照第3.3节的方式将其添加到MybatisPlusInterceptor中。对传统XML映射的SQL也生效该插件是基于MyBatis的Interceptor机制工作的它会拦截所有通过该SqlSessionFactory执行的SQL。因此即使是在老XML中写的SELECT * FROM order只要表名order在你的动态表名规则中也会被替换。测试要充分动态表名逻辑如果涉及复杂的线程局部变量如ThreadLocal在异步或多线程环境下在传统MyBatis手动编写的复杂SQL中要确保上下文能正确传递。5.4 代码生成器的选择与适配MP提供了一个功能强大的代码生成器AutoGenerator。在混合项目中你可以策略性地使用它仅为新模块生成代码指定新的包路径为新表生成Entity、Mapper继承BaseMapper、Service和Controller。不要覆盖老代码在配置生成器时仔细设置输出目录OutputDir、包名PackageConfig和文件覆盖策略StrategyConfig.setFileOverride()避免意外覆盖已有的传统Mapper和XML文件。生成传统Mapper作为参考你甚至可以通过自定义TemplateEngine修改MP代码生成器的模板让它生成不继承BaseMapper的“传统”Mapper接口和对应的XML文件用于替换或参考老旧代码。但这需要一定的模板定制能力。6. 演进策略从并存走向统一并存架构是过渡状态长远来看维护两套模式会增加认知负担和风险。可以考虑以下演进路线冻结与隔离对于极其稳定、几乎不再修改的老核心模块将其Mapper和XML彻底隔离。通过清晰的包结构划分如com.xx.legacy.mapper并在团队内达成共识除非重大BUG否则不修改此区域代码。新功能全部使用MP风格开发。渐进式重构当需要修改或优化某个老功能时借机对其进行重构。将复杂的XML SQL逻辑用MP的QueryWrapper或UpdateWrapper进行重写如果逻辑等价且更清晰或者将其重构成一个清晰的Service方法内部调用多个简单的MP查询进行组合。每次修改一小块逐步消化技术债。建立新规范在团队中确立新的开发规范所有新开发的持久层操作除非有极特殊的性能优化需求如复杂联表查询、批量更新否则优先使用MP提供的Lambda查询和更新方式。这样代码更简洁、类型安全也便于后续统一维护。最终一个健康的项目架构应该是清晰一致的。MyBatis与MyBatis Plus的并存可以看作是一个项目在技术演进路上的一个特定阶段。通过合理的配置隔离、清晰的编码规范以及渐进式的重构我们完全有能力驾驭这种混合状态并稳步地将其导向更统一、更可维护的未来。