尧图网页设计 
1. SpringBootMyBatis-Plus报错sqlSessionFactory缺失问题解析最近在整合SpringBoot和MyBatis-Plus时不少开发者遇到了Property sqlSessionFactory or sqlSessionTemplate are required的报错。这个错误看似简单但背后涉及到SpringBoot自动配置机制、MyBatis-Plus版本兼容性等多个技术点。作为经历过这个坑的老手我来详细拆解这个问题的成因和解决方案。这个问题通常发生在SpringBoot 2.7.x及以上版本与MyBatis-Plus 3.5.x的整合过程中。当你启动应用时控制台会抛出如下异常org.springframework.beans.factory.BeanCreationException: Error creating bean with name xxxMapper defined in file [xxx.class]: Invocation of init method failed; nested exception is java.lang.IllegalArgumentException: Property sqlSessionFactory or sqlSessionTemplate are required这个错误的核心在于MyBatis-Plus无法自动装配sqlSessionFactory或sqlSessionTemplate这两个关键bean。要彻底解决这个问题我们需要先理解其背后的技术原理。2. 问题根源深度剖析2.1 SpringBoot自动配置机制SpringBoot的自动配置是其核心特性之一。对于MyBatis集成SpringBoot提供了MybatisAutoConfiguration自动配置类。这个类会尝试自动创建SqlSessionFactory和SqlSessionTemplatebean。关键点在于SpringBoot 2.7.x开始对自动配置机制做了调整特别是对于条件装配的逻辑更加严格。这导致在某些情况下自动配置可能不会按预期工作。2.2 MyBatis-Plus的扩展机制MyBatis-Plus通过MybatisPlusAutoConfiguration扩展了SpringBoot的MyBatis自动配置。在理想情况下它会自动配置数据源(DataSource)创建SqlSessionFactory创建SqlSessionTemplate扫描Mapper接口并注册到Spring容器但当版本不匹配或配置缺失时这个链条就会断裂导致我们看到的错误。2.3 版本兼容性问题矩阵经过大量项目实践我整理出以下版本兼容性表格SpringBoot版本MyBatis-Plus版本兼容性状态2.4.x及以下3.4.x及以下✅ 完全兼容2.5.x-2.6.x3.5.0-3.5.2⚠️ 需额外配置2.7.x及以上3.5.3及以上✅ 推荐组合3.0.x最新版✅ 最佳实践3. 六种解决方案及实操指南3.1 方案一检查基础配置新手必看这是最基本的排查步骤很多开发者跳过这步直接尝试复杂方案结果浪费时间。确保pom.xml中正确引入了依赖dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency检查主启动类是否有MapperScan注解SpringBootApplication MapperScan(com.yourpackage.mapper) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }确认application.yml/properties中有数据源配置spring: datasource: url: jdbc:mysql://localhost:3306/your_db username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver3.2 方案二显式配置SqlSessionFactory推荐如果自动配置失效我们可以手动配置Configuration public class MyBatisConfig { Bean public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { MybatisSqlSessionFactoryBean sessionFactory new MybatisSqlSessionFactoryBean(); sessionFactory.setDataSource(dataSource); // 其他自定义配置... return sessionFactory.getObject(); } }注意这种方法虽然可靠但失去了部分MyBatis-Plus的自动配置特性需要自行处理分页插件等配置。3.3 方案三版本降级方案如果项目环境允许可以考虑版本组合!-- SpringBoot 2.6.x -- parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.6.13/version /parent !-- MyBatis-Plus 3.5.2 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.2/version /dependency3.4 方案四检查依赖冲突使用mvn dependency:tree检查依赖冲突特别注意mybatis-spring的版本mybatis-plus-core的版本spring-boot-autoconfigure的版本常见冲突模式[INFO] - com.baomidou:mybatis-plus-boot-starter:jar:3.5.3.1:compile [INFO] | \- org.mybatis:mybatis-spring:jar:2.0.7:compile [INFO] \- org.mybatis:mybatis:jar:3.5.6:compile如果发现版本不一致需要排除旧版本exclusions exclusion groupIdorg.mybatis/groupId artifactIdmybatis/artifactId /exclusion /exclusions3.5 方案五完整配置示例这是我在生产环境中验证过的完整配置Configuration EnableTransactionManagement public class MyBatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 分页插件 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 乐观锁插件 interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); return interceptor; } Bean public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { MybatisSqlSessionFactoryBean sqlSessionFactory new MybatisSqlSessionFactoryBean(); sqlSessionFactory.setDataSource(dataSource); sqlSessionFactory.setPlugins(mybatisPlusInterceptor()); // 其他配置... return sqlSessionFactory.getObject(); } }3.6 方案六SpringBoot 3.x适配方案对于使用SpringBoot 3.x的用户必须使用MyBatis-Plus 3.5.3需要Java 17添加特殊配置mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl4. 深度排查技巧与日志分析4.1 启用DEBUG日志在application.yml中添加logging: level: org.springframework: DEBUG com.baomidou: DEBUG关键日志点检查MybatisPlusAutoConfiguration是否被加载查看SqlSessionFactorybean的创建过程观察Mapper接口的注册情况4.2 常见异常模式分析循环依赖问题The dependencies of some of the beans in the application context form a cycle解决方案使用Lazy注解延迟加载多数据源冲突 当配置了多个DataSource时需要明确指定哪个用于MyBatis插件加载顺序问题 分页插件等需要在SqlSessionFactory创建前配置好5. 生产环境最佳实践经过多个项目的实战检验我总结出以下最佳实践版本锁定properties mybatis-plus.version3.5.3.1/mybatis-plus.version /properties配置检查清单[ ] 数据源配置正确[ ] MapperScan路径正确[ ] 无mybatis-core版本冲突[ ] 无重复的SqlSessionFactory定义监控集成Bean public PerformanceInterceptor performanceInterceptor() { PerformanceInterceptor interceptor new PerformanceInterceptor(); interceptor.setMaxTime(1000); // SQL执行最大时长(ms) interceptor.setFormat(true); // 是否格式化SQL return interceptor; }多模块项目特别处理 对于多模块项目确保主模块包含mybatis-plus-boot-starter其他模块只依赖mybatis-plus-core6. 高级话题自定义扩展对于需要深度定制的场景可以考虑继承MybatisPlusAutoConfiguration重写关键方法实现ConfigurationCustomizer接口自定义SqlSessionFactoryBean示例代码public class CustomMyBatisConfig extends MybatisPlusAutoConfiguration { Override public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { // 自定义实现... } }7. 常见误区与避坑指南误区一盲目添加Bean多余的手动配置会干扰自动装配应先确认自动配置为何失效误区二忽略依赖冲突mybatis、mybatis-spring、mybatis-plus的版本必须协调误区三扫描路径错误MapperScan的basePackage必须包含所有Mapper接口误区四多数据源未指定使用Primary标注主数据源误区五过早放弃自动配置自动配置失败时应先调试而不是直接全手动配置8. 性能优化建议启用二级缓存mybatis-plus: configuration: cache-enabled: true合理配置连接池spring: datasource: hikari: maximum-pool-size: 20 minimum-idle: 5批量操作优化 使用MyBatis-Plus的saveBatch方法时合理设置batchSize// 最佳实践值通常在1000-2000之间 mybatisPlusInterceptor.addInnerInterceptor(new BatchInsertInnerInterceptor(1500));9. 未来兼容性考量随着SpringBoot 3.x的普及需要注意Jakarta EE 9的包名变化javax→jakartaJava 17的语言特性模块化系统的影 SpringBoot+MyBatis-Plus整合报错解决方案
1. SpringBootMyBatis-Plus报错sqlSessionFactory缺失问题解析最近在整合SpringBoot和MyBatis-Plus时不少开发者遇到了Property sqlSessionFactory or sqlSessionTemplate are required的报错。这个错误看似简单但背后涉及到SpringBoot自动配置机制、MyBatis-Plus版本兼容性等多个技术点。作为经历过这个坑的老手我来详细拆解这个问题的成因和解决方案。这个问题通常发生在SpringBoot 2.7.x及以上版本与MyBatis-Plus 3.5.x的整合过程中。当你启动应用时控制台会抛出如下异常org.springframework.beans.factory.BeanCreationException: Error creating bean with name xxxMapper defined in file [xxx.class]: Invocation of init method failed; nested exception is java.lang.IllegalArgumentException: Property sqlSessionFactory or sqlSessionTemplate are required这个错误的核心在于MyBatis-Plus无法自动装配sqlSessionFactory或sqlSessionTemplate这两个关键bean。要彻底解决这个问题我们需要先理解其背后的技术原理。2. 问题根源深度剖析2.1 SpringBoot自动配置机制SpringBoot的自动配置是其核心特性之一。对于MyBatis集成SpringBoot提供了MybatisAutoConfiguration自动配置类。这个类会尝试自动创建SqlSessionFactory和SqlSessionTemplatebean。关键点在于SpringBoot 2.7.x开始对自动配置机制做了调整特别是对于条件装配的逻辑更加严格。这导致在某些情况下自动配置可能不会按预期工作。2.2 MyBatis-Plus的扩展机制MyBatis-Plus通过MybatisPlusAutoConfiguration扩展了SpringBoot的MyBatis自动配置。在理想情况下它会自动配置数据源(DataSource)创建SqlSessionFactory创建SqlSessionTemplate扫描Mapper接口并注册到Spring容器但当版本不匹配或配置缺失时这个链条就会断裂导致我们看到的错误。2.3 版本兼容性问题矩阵经过大量项目实践我整理出以下版本兼容性表格SpringBoot版本MyBatis-Plus版本兼容性状态2.4.x及以下3.4.x及以下✅ 完全兼容2.5.x-2.6.x3.5.0-3.5.2⚠️ 需额外配置2.7.x及以上3.5.3及以上✅ 推荐组合3.0.x最新版✅ 最佳实践3. 六种解决方案及实操指南3.1 方案一检查基础配置新手必看这是最基本的排查步骤很多开发者跳过这步直接尝试复杂方案结果浪费时间。确保pom.xml中正确引入了依赖dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency检查主启动类是否有MapperScan注解SpringBootApplication MapperScan(com.yourpackage.mapper) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }确认application.yml/properties中有数据源配置spring: datasource: url: jdbc:mysql://localhost:3306/your_db username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver3.2 方案二显式配置SqlSessionFactory推荐如果自动配置失效我们可以手动配置Configuration public class MyBatisConfig { Bean public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { MybatisSqlSessionFactoryBean sessionFactory new MybatisSqlSessionFactoryBean(); sessionFactory.setDataSource(dataSource); // 其他自定义配置... return sessionFactory.getObject(); } }注意这种方法虽然可靠但失去了部分MyBatis-Plus的自动配置特性需要自行处理分页插件等配置。3.3 方案三版本降级方案如果项目环境允许可以考虑版本组合!-- SpringBoot 2.6.x -- parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.6.13/version /parent !-- MyBatis-Plus 3.5.2 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.2/version /dependency3.4 方案四检查依赖冲突使用mvn dependency:tree检查依赖冲突特别注意mybatis-spring的版本mybatis-plus-core的版本spring-boot-autoconfigure的版本常见冲突模式[INFO] - com.baomidou:mybatis-plus-boot-starter:jar:3.5.3.1:compile [INFO] | \- org.mybatis:mybatis-spring:jar:2.0.7:compile [INFO] \- org.mybatis:mybatis:jar:3.5.6:compile如果发现版本不一致需要排除旧版本exclusions exclusion groupIdorg.mybatis/groupId artifactIdmybatis/artifactId /exclusion /exclusions3.5 方案五完整配置示例这是我在生产环境中验证过的完整配置Configuration EnableTransactionManagement public class MyBatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 分页插件 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 乐观锁插件 interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); return interceptor; } Bean public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { MybatisSqlSessionFactoryBean sqlSessionFactory new MybatisSqlSessionFactoryBean(); sqlSessionFactory.setDataSource(dataSource); sqlSessionFactory.setPlugins(mybatisPlusInterceptor()); // 其他配置... return sqlSessionFactory.getObject(); } }3.6 方案六SpringBoot 3.x适配方案对于使用SpringBoot 3.x的用户必须使用MyBatis-Plus 3.5.3需要Java 17添加特殊配置mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl4. 深度排查技巧与日志分析4.1 启用DEBUG日志在application.yml中添加logging: level: org.springframework: DEBUG com.baomidou: DEBUG关键日志点检查MybatisPlusAutoConfiguration是否被加载查看SqlSessionFactorybean的创建过程观察Mapper接口的注册情况4.2 常见异常模式分析循环依赖问题The dependencies of some of the beans in the application context form a cycle解决方案使用Lazy注解延迟加载多数据源冲突 当配置了多个DataSource时需要明确指定哪个用于MyBatis插件加载顺序问题 分页插件等需要在SqlSessionFactory创建前配置好5. 生产环境最佳实践经过多个项目的实战检验我总结出以下最佳实践版本锁定properties mybatis-plus.version3.5.3.1/mybatis-plus.version /properties配置检查清单[ ] 数据源配置正确[ ] MapperScan路径正确[ ] 无mybatis-core版本冲突[ ] 无重复的SqlSessionFactory定义监控集成Bean public PerformanceInterceptor performanceInterceptor() { PerformanceInterceptor interceptor new PerformanceInterceptor(); interceptor.setMaxTime(1000); // SQL执行最大时长(ms) interceptor.setFormat(true); // 是否格式化SQL return interceptor; }多模块项目特别处理 对于多模块项目确保主模块包含mybatis-plus-boot-starter其他模块只依赖mybatis-plus-core6. 高级话题自定义扩展对于需要深度定制的场景可以考虑继承MybatisPlusAutoConfiguration重写关键方法实现ConfigurationCustomizer接口自定义SqlSessionFactoryBean示例代码public class CustomMyBatisConfig extends MybatisPlusAutoConfiguration { Override public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { // 自定义实现... } }7. 常见误区与避坑指南误区一盲目添加Bean多余的手动配置会干扰自动装配应先确认自动配置为何失效误区二忽略依赖冲突mybatis、mybatis-spring、mybatis-plus的版本必须协调误区三扫描路径错误MapperScan的basePackage必须包含所有Mapper接口误区四多数据源未指定使用Primary标注主数据源误区五过早放弃自动配置自动配置失败时应先调试而不是直接全手动配置8. 性能优化建议启用二级缓存mybatis-plus: configuration: cache-enabled: true合理配置连接池spring: datasource: hikari: maximum-pool-size: 20 minimum-idle: 5批量操作优化 使用MyBatis-Plus的saveBatch方法时合理设置batchSize// 最佳实践值通常在1000-2000之间 mybatisPlusInterceptor.addInnerInterceptor(new BatchInsertInnerInterceptor(1500));9. 未来兼容性考量随着SpringBoot 3.x的普及需要注意Jakarta EE 9的包名变化javax→jakartaJava 17的语言特性模块化系统的影