前一阵同事抱着一串报错来找我第一行写的是Error creating bean with name sqlSessionFactory defined in class path resource [spring-mybatis.xml]。同事已经对着sqlSessionFactory这个bean翻了大半天配置越看越觉得没问题。我跟他说别看第一行往上翻真正的答案在Caused by里面。果不其然翻了几屏之后一行java.lang.IllegalArgumentException: Mapped Statements collection already contains value for ...静静地躺在那里。这个报错大概是Spring MyBatis项目里最经典的“启动失败全家桶”之一了网上搜出来的方案五花八门有说加依赖的有说改路径的有说换版本的。其实这个报错本身只是一个“外套”真正的病灶永远藏在它的nested exception里。如果你没搞清楚这层关系就会像我的同事一样对着sqlSessionFactory反复检查却始终摸不到问题核心。这篇内容我按自己的排障经验整理了一下希望能让你下次遇到它时十分钟内定位根因而不是花一个下午。1. 先看懂异常层次Error creating bean只是“外套”真正信息在nested exception1.1 报错信息的完整链条从BeanCreationException到caused by先看一段完整报错的典型形态org.springframework.beans.factory.BeanCreationException: Error creating bean with name sqlSessionFactory defined in class path resource [spring-mybatis.xml]: Initialization of bean failed; nested exception is java.lang.IllegalArgumentException: Mapped Statements collection already contains value for com.example.mapper.UserMapper.selectUser at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.doCreateBean(AbstractAutowireCapableBeanFactory.java:607) ... Caused by: java.lang.IllegalArgumentException: Mapped Statements collection already contains value for com.example.mapper.UserMapper.selectUser at org.apache.ibatis.session.Configuration.addMappedStatement(Configuration.java:107) ...第二行的Initialization of bean failed已经透露了更多信息这是一个FactoryBean的初始化失败也就是说 Spring 在创建SqlSessionFactoryBean的过程中调用了它的初始化逻辑内部会加载 MyBatis 全局配置、解析 Mapper XML、构建Configuration对象在这个环节抛出了异常。所以你在报错信息里看到的“名字叫 sqlSessionFactory 的 bean 创建失败”不代表sqlSessionFactory这个 bean 本身的声明写得不对而是它内部某个环节在执行时出了问题。如果把BeanCreationException看成“车间装配线上的一个总报警器”那Caused by才是具体哪颗螺丝钉断裂的现场报告。Spring 容器里几十种 Bean 创建失败都会走同一个报警器真正的排查入口永远在异常链的最底端。1.2 为什么第一行屁用没有Spring Bean容器的统一异常出口我见过不少人看到Error creating bean with name sqlSessionFactory第一反应是去搜sqlSessionFactory的配置或者怀疑是mybatis-config.xml写错了。但实际上sqlSessionFactory创建失败可以因为无数种原因触发它只是异常向上抛出的一个“出口”。举几个例子你感受一下它们最后都会落在同一个报错上mybatis-config.xml路径写错文件加载不到抛的是FileNotFoundExceptionMapper XML 里有两个 statement 的 id 相同抛的是IllegalArgumentException数据源连不上数据库抛的是数据库驱动层异常某个 Mapper 接口找不到 XML 实现抛的是BindingException缺了mybatis-spring依赖抛的是ClassNotFoundException。这些异常最后都会被打包成Error creating bean with name sqlSessionFactory但根因各自不同排查方向也完全不同。所以第一行的作用只有一个——告诉你问题发生在容器装配sqlSessionFactory的哪个环节剩下的全在它下面的异常链里。1.3 完整堆栈里哪些行才是有效信息这是一段实际生产中常见的堆栈我截取关键部分做标注org.springframework.beans.factory.BeanCreationException: Error creating bean with name sqlSessionFactory defined in class path resource [spring-mybatis.xml] at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.doCreateBean(...) ... Caused by: org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.example.mapper.UserMapper.selectPage at org.apache.ibatis.binding.MapperMethod$SqlCommand.init(MapperMethod.java:227) ... Caused by: java.sql.SQLException: Cannot create PoolableConnectionFactory (Communications link failure ...) at com.alibaba.druid.pool.DruidDataSource.init(DruidDataSource.java:952)注意看Caused by是可以连续多个的。每多一层Caused by问题就往下深一层。我的习惯是一次性把所有Caused by全看完以最底部那一层为准。上面这个例子第一层Caused by 是 MyBatis 的语句绑定问题但继续往下看底层是数据库连接不上——也就是说selectPage找不到其实也可能是数据库没连上导致初始化链路异样或者两个问题同时存在。排障铁律不看完所有Caused by不轻易下结论。2. 一张表对号入座从堆栈最底部反推故障类型2.1 按最底层异常分类排查我把这些年积累的高频根因做了个表每次拿到报错先对照最底层的异常类型基本能确定排查方向堆栈底部异常关键词第一嫌疑方向排查动作FileNotFoundException/class path resource [xxx] cannot be opened配置文件路径或文件名错误核对实际路径、文件名、打包产物里是否真的有这个文件IllegalArgumentException: Mapped Statements collection already contains value forMapper XML 中 statement 重复 / 与 MyBatis-Plus 内置方法冲突全局搜索报错提示的那个 key检查所有 XML 的 namespace 和 idBindingException: Invalid bound statement (not found)Mapper 接口找不到 XML 实现检查 XML 的 namespace、mapper-locations 路径是否匹配CannotGetJdbcConnectionException/Communications link failure/Access denied for user数据源连不上数据库检查数据库地址、端口、账号密码、网络连通性NoUniqueBeanDefinitionException容器中存在多个同类型 Bean如多个 DataSource没有指定主选加Primary或Qualifier明确指定ClassNotFoundException/NoClassDefFoundError缺少依赖或依赖版本冲突用mvn dependency:tree检查 mybatis、mybatis-spring、驱动包Circular referenceBean 之间循环依赖检查Bean方法之间的依赖链这张表解决的是“往哪个方向查”的问题。我遇到一个sqlSessionFactory创建失败的报错第一件事不是开启 IDE 去搜代码而是先把最下面的Caused by贴出来对号入座定位方向后心里就有底了。2.2 注意叠加根因先解决数据源再看Mapper绑定实际生产里报错经常是连环的。最常见的一种叠加是数据源初始化失败 → MyBatis 加载 Mapper 的时候拿不到连接 → 报了一堆BindingException或者连接超时异常 → 最外层被包装成sqlSessionFactory创建失败。这种时候如果你只盯着最表层的BindingException去查 Mapper 配置会走很多弯路。我的经验是先解决数据库连接层问题再重新启动看剩余错误。这个优先级同样适用于其它叠加场景。比如报错底部有NoUniqueBeanDefinitionException说明容器里有多个 DataSource 或 SqlSessionFactory 类型的 BeanSpring 不知道该注入哪个得先把 Bean 定义理清楚再比如 Mapper XML 里的 statement 重复注册得先把重复项清掉。2.3 一个快速定位的小脚本习惯我在本地排障时会顺手复制完整堆栈到一个临时文本然后用下面的命令只看异常链主干grep -E Caused by|Exception|Error 完整堆栈.txt也可以直接数一下Caused by出现的次数grep -c Caused by 完整堆栈.txt这个数字不用太当真但能直观告诉你问题埋得有多深。真正的根因只在最后一个Caused by之后的几行里。3. 高频根因逐一拆解五个场景的报错现场、排查链路与修复验证3.1 配置文件路径错位classpath里根本没有这个文件这个属于最基础但也不少见的坑。报错形态通常是Caused by: java.io.FileNotFoundException: class path resource [mybatis/config/mybatis-config.xml] cannot be opened because it does not exist原因一般就几个SqlSessionFactoryBean的configLocation写成了classpath:mybatis/config/mybatis-config.xml但实际文件在src/main/resources/mybatis-config.xml或者文件名写错了比如把mybatis-config.xml写成了mybatis_config.xml又或者多模块项目里文件在 A 模块的src/main/resources但 B 模块引用时没有通过依赖把资源带过去。排查链路很简单先看异常里提示的路径再去项目的src/main/resources和编译后的target/classes目录里找这个文件。很多人在 IDE 里能看到文件就以为配置没问题但 IDE 的资源目录和运行时类路径并不是一回事。如果你用的是 Maven可以直接检查jar tf 你的应用jar包.jar | grep mybatis-config.xml看打包产物里有没有这个文件如果没有说明资源被排除或者放错位置了。修复就是把文件放到正确的资源目录并确保构建工具把它带进去。验证方式也直接重新编译启动直到sqlSessionFactory的初始化日志正常出现。3.2 Mapper绑定类异常XML缺失、namespace错误、statement重复这类在sqlSessionFactory创建失败里占比相当高而且表现非常多。我干活时反复遇到过下面三种典型形态第一种Invalid bound statement (not found)Caused by: org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.example.mapper.UserMapper.selectPage这表示UserMapper接口里的selectPage方法没有找到对应的 SQL 实现。常见触发点有三个Mapper XML 文件不在mapperLocations扫描路径内XML 的 namespace 写错了和接口全限定名不一致XML 文件压根没被打进target/classes。这里有个容易忽略的细节很多项目用MapperScan扫描接口但 XML 文件扫描是交给mybatis-plus或mybatis-spring-boot-starter的mapper-locations配置控制的。如果你项目里配的是mybatis-plus: mapper-locations: classpath*:mapper/**/*.xml而实际 XML 放在了resources/mapper/xxx/yyy.xml这个通配符是能匹配到的但如果 XML 放在了src/main/java目录下面Maven 默认不会把它打进target/classes于是启动时就会报 Invalid bound statement。第二种namespace 与 id 重复导致Mapped Statements collection already contains value for ...Caused by: java.lang.IllegalArgumentException: Mapped Statements collection already contains value for com.example.mapper.UserMapper.selectUser这个异常的意思是MyBatis 在注册 MappedStatement 时发现同一个 key 已经存在。你可以把它理解成往同一个储物箱里放两件同样编号的衣服新衣服塞不进去。造成这种重复的原因通常是两个 Mapper XML 文件配了相同的 namespace 和相同的 id同一个 XML 文件里写了重复 idMyBatis-Plus 项目里XML 里的自定义方法 id 和 MyBatis-Plus 内置的 BaseMapper 方法 id 撞了尤其是selectPage、insert、updateById这种高频方法。排查方式拿异常里提示的com.example.mapper.UserMapper.selectUser当线索全局搜索这个字符串重点检查resources/mapper下的 XML 文件再检查自动生成的 BaseMapper 方法列表。定位到具体重复项后把其中一个 statement 改名或者移除重复定义。第三种Mapper 接口扫描重复如果你有两个MapperScan配置扫到了同一个接口包或者多个 SqlSessionFactory 共用同一个 XML 目录也会出现上面的重复注册异常。这种场景通常出现在多数据源配置中两个 SqlSessionFactory 扫描了同一批 Mapper需要给每个 SqlSessionFactory 配置独立的 mapper-locations。3.3 数据源连不上库SqlSessionFactory背了“连接超时”的锅这是我个人遇到最多的情况之一也是最有迷惑性的。表面上是sqlSessionFactory创建失败实际上问题出在它依赖的DataSource上。典型的异常链长这样Caused by: org.springframework.jdbc.CannotGetJdbcConnectionException: Could not get JDBC Connection ... Caused by: com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure ... Caused by: java.net.ConnectException: Connection refused (Connection refused)这里的关键在于SqlSessionFactoryBean在初始化阶段需要构建 MyBatis 的Configuration对象而这个过程中可能触发数据库连接的获取尤其是 Mapper XML 里配置了databaseIdProvider或者解析某些依赖数据库元数据的场景。另外如果你用了DruidDataSource且配置了initialSize 0那么数据源初始化时就会立即建立若干物理连接。数据库地址写错、密码不对、网络不通、防火墙拦截都会在容器启动阶段直接暴露。排查时记住一个顺序先看 SQL 异常细节是超时、拒绝连接还是Access denied超时可能是网络或防火墙问题拒绝连接多半是端口问题Access denied则是账号密码问题。然后把配置文件里的数据库地址单独拿出来用命令行客户端手动连一次mysql -h 127.0.0.1 -P 3306 -u root -p能连上再回来看应用配置。如果数据库地址本身是个域名顺手ping或nslookup一下确认域名解析正常。修好数据源后重启sqlSessionFactory创建失败往往就消失了——因为它从来没真正出过问题是下面的人先坏了。3.4 手写Bean依赖顺序与自动装配的坑用 JavaConfig 方式配置 MyBatis 时有不少人为了图省事在Bean方法里手动new出一个DataSource再传给SqlSessionFactoryBeanBean public SqlSessionFactory sqlSessionFactory() throws Exception { DruidDataSource ds new DruidDataSource(); ds.setUrl(jdbc:mysql://localhost:3306/test); ds.setUsername(root); ds.setPassword(123456); ds.init(); SqlSessionFactoryBean factoryBean new SqlSessionFactoryBean(); factoryBean.setDataSource(ds); return factoryBean.getObject(); }这个写法最大的问题在于手工new出来的DataSource不在 Spring 容器管理范围内事务管理器拿到的数据源和 MyBatis 用的数据源可能不是同一个实例而且ds.init()如果抛异常报错同样会包装成sqlSessionFactory创建失败迷惑性极强。正确的做法是用声明式注入让 Spring 帮你管理依赖关系Bean public SqlSessionFactory sqlSessionFactory(Qualifier(dataSource) DataSource dataSource, Value(${mybatis.mapper-locations}) String mapperLocations) throws Exception { SqlSessionFactoryBean factoryBean new SqlSessionFactoryBean(); factoryBean.setDataSource(dataSource); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources(mapperLocations)); return factoryBean.getObject(); }用方法参数引入DataSourceSpring 会保证它先被创建完成再注入进来依赖顺序由容器管理。这能规避掉很多隐性问题。另一方面如果项目是 Spring Boot 且引入了mybatis-spring-boot-starter它自己就会自动装配一个SqlSessionFactory。如果你又在配置类里手写了一个同名同类型的Bean两个 Bean 就会打架。Spring Boot 2.1 默认不允许 Bean 覆盖会直接抛BeanDefinitionOverrideException规则宽松一点的老项目则可能出现两个SqlSessionFactory同时存在之后任何按类型注入的地方都可能报NoUniqueBeanDefinitionException。解决原则一句话要么全部交给 starter 自动装配要么自己完全接管不要混着来。如果坚持自己接管请在启动类上排除自动配置SpringBootApplication(exclude {MybatisAutoConfiguration.class})验证方式启动日志里只应出现一条 SqlSessionFactory 初始化记录然后启动不再报错。3.5 依赖缺失或版本拉扯ClassNotFoundException现场还有一种sqlSessionFactory创建失败根因完全和你的配置无关纯粹是项目类路径里少了东西或同一个类存在多个冲突版本。最典型的几种Caused by: java.lang.ClassNotFoundException: org.mybatis.spring.SqlSessionFactoryBean说明没引入mybatis-spring或者mybatis-spring被错误的依赖管理移除了。Caused by: java.lang.NoClassDefFoundError: org/apache/ibatis/session/Configuration说明mybatis核心包缺失或者版本冲突导致类加载器加载不到。Caused by: java.lang.NoClassDefFoundError: com/mysql/cj/jdbc/Driver说明 MySQL 驱动没引入或者引入了太老的驱动版本。排查手段很固定先看完整异常里缺的是什么类再去依赖树里确认mvn dependency:tree -Dincludesorg.mybatis,org.mybatis.spring,org.mybatis.plus,mysql重点检查mybatis、mybatis-spring、mybatis-plus、mysql-connector-java这些核心组件的版本。如果项目同时引入了mybatis-spring-boot-starter和mybatis-plus-boot-starter很容易出现两套 MyBatis 核心代码互相覆盖的惨状。我的建议是MyBatis-Plus 项目直接只保留mybatis-plus-boot-starter它内部已经带了mybatis和mybatis-spring不需要再单独引原生 starter。版本兼容上给一个参考基准场景版本建议Spring Boot 2.x MyBatismybatis-spring-boot-starter 2.2.x / 2.3.xSpring Boot 2.x MyBatis-Plusmybatis-plus-boot-starter 3.4.x / 3.5.x传统 Spring 项目非Bootmybatis 3.5.x mybatis-spring 2.0.x同一条依赖链上的版本尽量保持一致不要出现 mybatis 3.4 和 mybatis-spring 2.0 这种明显错配的组合。4. 三次生产环境实盘复盘当堆栈只有一行报错时怎么一步步挖到根4.1 案例一XML文件“失踪”之谜问题出在Maven多模块有一次上线测试环境启动直接挂掉报错就是Error creating bean with name sqlSessionFactory defined in class path resource [spring-mybatis.xml]。当时我让负责的同事先把最下面的Caused by发过来结果是Caused by: java.io.FileNotFoundException: class path resource [mapper/UserMapper.xml] cannot be opened because it does not exist项目是多模块 Maven 结构Common模块里放了 Mapper 接口Web模块里放了 Mapper XML。我让他去Web模块的target/classes目录下看mapper/UserMapper.xml在不在——果然不在。原因很常见XML 被放进了src/main/java目录下IDE 里看着好好的但 Maven 构建时默认不会把src/main/java里的非.java文件复制到target/classes。这个问题在本地用 IDE 直接跑可能没问题IDE 自己会处理资源但一打成可执行 jar 或部署到测试环境就必然炸。修复也很直接两种方案任选把 XML 移回src/main/resources/mapper/目录在 pom.xml 里显式配置资源目录build resources resource directorysrc/main/java/directory includes include**/*.xml/include /includes /resource resource directorysrc/main/resources/directory /resource /resources /build我个人的偏好是第一种把 XML 规规矩矩放在resources下避免绕开 Maven 默认约定。事后复盘这个问题的核心还是对构建产物缺乏检查——排查链路的每一步都不能跳过验证。4.2 案例二多数据源下没有 Primary两个SqlSessionFactory互相打架另一次线上事故项目做读写分离配置了主从两个DruidDataSource同时也配置了两个SqlSessionFactory。启动时报错Caused by: org.springframework.beans.factory.NoUniqueBeanDefinitionException: No qualifying bean of type javax.sql.DataSource available: expected single matching bean but found 2: masterDataSource,slaveDataSource这个报错其实已经把答案写在脸上了容器里有两个DataSourceSpring 不知道该往SqlSessionFactoryBean里注入哪一个。但是同事的困惑点在于我在SqlSessionFactory方法里明明用的是Qualifier(masterDataSource)为什么还会报 NoUnique后来发现主库的SqlSessionFactory确实指定了masterDataSource但某个自动配置或者某个第三方组件的 DataSource 依赖注入没有指定于是 Spring 试图按类型自动注入时就遇到了两个候选 Bean。修复思路有两层给主数据源加Primary让它成为按类型注入时的默认选择所有需要区分主从的地方统一用Qualifier精确指定不依赖默认选择。注意Primary只在按类型注入时生效如果你明确写了Qualifier还是以Qualifier为准。另外加了Primary后事务管理器那边也会默认选中主数据源读写分离里这通常正是我们想要的行为但要确认从库事务没有被悄悄切到主库。4.3 案例三Druid密码加密导致的主库初始化失败第三个案例是典型的“表面是 sqlSessionFactory实际是数据源配置”问题。项目为了安全用 Druid 的ConfigTools对数据库密码做了加密配置里放的是密文私钥解密逻辑由 Druid 框架自动完成。上线后启动报错Caused by: com.alibaba.druid.pool.DruidDataSource$CreateConnectionThread ... Caused by: java.sql.SQLException: Cannot create PoolableConnectionFactory (Access denied for user root...)账号密码怎么看都没问题明文测试也能连上。最后发现是publicKey配置没有被加载到DruidDataSource的connectionProperties里导致 Druid 用密文去解密时拿不到正确的公钥解出来的密码是错的数据库自然拒绝访问。排查链路是这样的看到Access denied→ 先去确认密码是否正确 → 手动明文连接成功 → 再回头看加密配置 → 定位到publicKey未注入。最终修复是把公钥配置正确写入连接属性spring: datasource: druid: username: root password: 加密后的密文 connection-properties: config.decrypttrue;config.decrypt.key公钥这类问题给我的教训是看到数据库访问被拒绝先别急着改密码。它是sqlSessionFactory创建失败里最“深”的一类根因但深不代表难一层层往下剥总会找到。5. 减少这类报错的日常动作配置即验证的五个习惯5.1 每次改完配置后的“三看”固定动作这类报错多起来之后我给自己定了一个“三看”动作每次改完配置都执行一遍第一看编译产物。target/classes里有没有对应的 XML、properties、yml 文件。很多启动报错在 IDE 里看不出来一部署就现原形多半就是资源没被打进去。第二看完整的启动日志。不是只看报错第一行而是看从Tomcat started往回推的所有Caused by确保没有隐藏的连环问题。第三看 Mapper 扫描路径和 XML 实际位置的匹配关系。拿一个具体的 Mapper 接口比如UserMapper手动去mapper-locations匹配的目录里找UserMapper.xml确认 namespace 的前缀和接口包名完全一致。这三看听起来简单但每次都能帮我拦住一半以上的低级失误。5.2 用最小上下文测试代替盲目重启在传统 Spring 项目里反复重启容器验证问题非常耗时。后来我习惯写一个最小上下文测试只加载数据源和 SqlSessionFactory 相关配置用 JUnit 快速验证RunWith(SpringJUnit4ClassRunner.class) ContextConfiguration(locations {classpath:spring-datasource.xml, classpath:spring-mybatis.xml}) public class SqlSessionFactoryInitTest { Autowired private SqlSessionFactory sqlSessionFactory; Test public void shouldInit() { assertNotNull(sqlSessionFactory); } }Spring Boot 项目就更简单了直接一个空SpringBootTest测试方法SpringBootTest class ContextLoadsTest { Test void contextLoads() { } }这个测试的目的不是验证业务逻辑而是验证 Spring 容器是否能成功启动。每次改完配置文件跑一次比反复手动重启省太多时间而且能更快定位到是不是容器装配问题。5.3 日志与依赖树把排查成本前置我还建议在项目里把 Bean 创建和 MyBatis 相关的日志级别调出来平时用不到出问题的时候能省大量时间logging: level: org.springframework.beans.factory: DEBUG org.mybatis: DEBUG org.mybatis.spring: DEBUG com.alibaba.druid: DEBUGorg.springframework.beans.factory的 DEBUG 日志会把每个 Bean 的创建流程打出来sqlSessionFactory的初始化过程也会有时间线可查。另一个前置动作是项目里固定用依赖树检查尤其在上线前mvn dependency:tree deps.txt然后把deps.txt里所有带 mybatis 的行拉出来看一眼确认没有奇怪的版本覆盖。现在团队里再有同事发这种报错我的第一反应还是那句把最底下那行Caused by发我。这句话看着不像是技术建议但确实是我踩过无数次坑之后总结出来的本能反应——Error creating bean with name sqlSessionFactory从来都不是问题的起点反而是整条排查链路的入口。学会往堆栈深处追比记住任何一条配置文件写法都管用。