1. 这个报错到底在说什么先别急着改代码把这个报错拆开看。Invalid bound statement (not found)翻译成人话就是你在代码里调用的那个 Mapper 接口方法MyBatis 在运行的时候找不到它对应的 SQL 语句。我最早碰到这个报错是在一次上线前的联调环境里半夜部署完 SpringBoot 项目启动倒是没问题结果一调用某个查询接口直接就抛异常日志里就这行红字。当时第一反应是“SQL 写错了”后来排查了一圈发现SQL 根本没被加载进去。说白了MyBatis 的工作原理是你在接口里声明一个方法比如UserMapper.selectById(Long id)然后在一个 XML 文件或者注解里写对应的 SQL。运行的时候MyBatis 会动态给这个接口生成代理实现代理拿到方法名去一个“注册表”里找对应的 SQL 语句。如果找不到它就告诉你Invalid bound statement (not found)。所以这个问题的本质不是 SQL 语法错也不是数据库连不上而是MyBatis 压根不知道你这个方法对应哪条 SQL。这个报错在 SpringBoot MyBatis 的项目里太常见了无论是刚入门的新手还是写了几年 Java 的老手几乎都踩过这个坑。这篇文章我就把这几年排查这个问题的经验完整梳理一遍从原理到场景从排查到预防一次说清楚。2. 根源在哪MyBatis 的“绑定”机制要理解为什么会有这个报错得先搞清楚 MyBatis 是怎么把接口方法和 SQL 语句绑在一起的。你自己手写 JDBC 的时候要执行一条 SQL得先获取连接、创建 PreparedStatement、传参数、执行、处理结果集每一步都要手写。MyBatis 做的事就是把这一整套封装起来让你只需要写接口和 SQL映射关系由框架处理。这个映射关系是怎么建立的接口的全限定名比如com.example.mapper.UserMapper方法名比如selectByIdXML 文件里的 namespace 和 idMyBatis 启动的时候会扫描配置里指定的 XML 文件路径把每个 XML 解析成MappedStatement对象存到一个 Map 里key 就是namespace . id也就是com.example.mapper.UserMapper.selectById这样的字符串。当你代码里调用userMapper.selectById(1L)的时候MyBatis 的代理类就去这个 Map 里找 key 等于com.example.mapper.UserMapper.selectById的条目。找到就执行找不到就抛Invalid bound statement (not found)。这就是“绑定”两个字的含义。整个链路就像一本字典接口方法是你要查的词XML 里的 namespaceid 是词条解释两者对不上字典就查不到。理解了这个机制你就知道排查方向了要么是字典里没这个词条XML 没加载要么是词条拼写和你要查的不一样namespace 或 id 不一致要么是字典根本没被翻开配置没生效。2.1 为什么很多人第一反应会误判这个报错太容易让人误判了。我见过不少同事第一反应是去查 SQL 语法然后把 XML 里的 SQL 翻来覆去地看结果 SQL 一点问题没有。还有人以为是数据库连接问题去检查数据源配置同样找不到原因。实际上这个报错和 SQL 内容、数据库连接都无关它发生在 MyBatis 框架内部的“映射解析”阶段。SQL 就算写成一坨也能报这个错——因为它压根没被加载框架根本没机会去解析 SQL 内容。所以排查的第一步是先建立正确的心智模型这是一个“接口方法到 SQL 语句的映射断链”问题不是在 SQL 本身。3. 最常见的原因XML 文件没被扫到这是出现频率最高的原因占我遇到的情况大概七八成。SpringBoot 项目里如果你用的是 XML 方式写 SQL那么 XML 文件的位置决定了 MyBatis 能不能找到它。很多新手会把 XML 文件放在src/main/java目录下跟 Mapper 接口放在同一个包。这本身没有错但问题在于Maven 默认只把src/main/resources下面的文件打包进 classpathsrc/main/java下面的.java文件会被编译成.class但.xml文件不会被复制进去。结果就是项目跑起来的时候classpath 里根本没有那个 XML 文件MyBatis 扫描路径的时候自然找不到于是所有接口方法都报Invalid bound statement (not found)。3.1 解决方案一把 XML 放到 resources 目录最直接的办法把 XML 文件放到src/main/resources/mapper/目录下然后在 application.yml 里配置 MyBatis 的 mapper 扫描路径。mybatis: mapper-locations: classpath:mapper/*.xml这样 MyBatis 就会去 classpath 下的mapper目录扫描所有 XML 文件。这是最标准、最不容易出错的方案。3.2 解决方案二让 Maven 把 java 目录下的 XML 也打包进去有些团队习惯把 XML 跟接口放同一个包这样看代码的时候方便。那就得在pom.xml里配置 Maven 的资源插件让.xml文件也能从src/main/java打包进 classpath。build resources resource directorysrc/main/java/directory includes include**/*.xml/include /includes /resource resource directorysrc/main/resources/directory /resource /resources /build注意如果你这么配了src/main/java下的 XML 会被打包到 classpath 的对应包路径下MyBatis 的mapper-locations也要跟着配置正确。比如接口在com.example.mapper包下XML 也放同包下打包后 XML 就在classpath:com/example/mapper/下。我当时用这种方式踩过一个坑加了这段配置之后src/main/java下所有的 XML 都被打进去了但同时也把一些测试用的临时 XML 也打进去了导致 MyBatis 解析的时候报了别的错。所以这个方案能用但不推荐最好还是规规矩矩把 XML 放 resources。提示判断 XML 是否真的打进了 classpath最简单的办法是打开打出来的 jar 包看一眼或者直接看 target/classes 目录下有没有对应的 XML 文件。4. 第二个高发原因namespace 和接口不匹配如果你确认 XML 文件确实在 classpath 里那接下来要查的就是 namespace。MyBatis 对 XML 的 namespace 要求非常严格必须等于 Mapper 接口的全限定名。比如你的接口是package com.example.mapper; public interface UserMapper { User selectById(Long id); }那么 XML 里就必须是mapper namespacecom.example.mapper.UserMapper这里哪怕少写一个字母或者包路径写错MyBatis 就会把这个 XML 里的 SQL 注册到错误的命名空间下。你在代码里调用UserMapper.selectById的时候它去的是com.example.mapper.UserMapper.selectById但 XML 里实际注册的是com.example.mapper.UserMmapper.selectById那自然查不到报错。4.1 还有一个很容易忽略的坑id 和方法名不一致namespace 对了还要看每条 SQL 的id。mapper namespacecom.example.mapper.UserMapper select idselectById resultTypecom.example.entity.User SELECT * FROM user WHERE id #{id} /select /mapper这个id必须和你接口里的方法名保持一致。如果接口里是selectByIdXML 里写的是selectByID大小写对不上那也是找不到的。这个坑看起来低级但真的会发生尤其是在多人协作、代码合并的场景下。有人改了接口方法名忘了改 XML或者从其他地方复制了一段 XMLid 没改成当前方法的名字。4.2 排查这两个问题的最快方法打开 MyBatis 的日志级别设为 DEBUG。日志里会打印出 MyBatis 加载了哪些 XML、每个 XML 的 namespace、每条 SQL 的 id。一眼就能看出实际注册的 key 是什么再和你代码里调用的接口方法对比马上就能定位。logging: level: org.mybatis: debug注意这里写的是org.mybatis不是org.apache.ibatis。我把这个搞混过结果日志没输出又浪费了十分钟。正确写法是logging: level: com.example.mapper: debug org.apache.ibatis: debug两个都加上一个看 SQL 执行日志一个看映射解析日志。5. 配置层面的三个坑如果文件位置对了namespace 和 id 也对但依然报错那就要检查配置了。这里我总结三个最容易出问题的配置点。5.1 Mapper 接口没有加 Mapper 注解SpringBoot 项目里Mapper 接口必须被 Spring 容器扫描到MyBatis 才能为它生成代理。如果你在接口上没加Mapper注解也没在主类上加MapperScan那 Spring 容器里根本没有这个接口对应的 Bean。你代码里注入UserMapper的时候启动阶段可能就报“没有该类型的 Bean”了。但有些场景下如果你用了Autowired(required false)之类的宽松注入启动不报错运行到这个方法的时候MyBatis 拿不到对应的代理也可能出现奇怪的现象。解决方式有两种方式一在每个 Mapper 接口上加MapperMapper public interface UserMapper { // ... }方式二在启动类或配置类上加MapperScanSpringBootApplication MapperScan(com.example.mapper) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }注意MapperScan的包路径要写对路径写宽了不会报错只是多扫描了一些没用的接口路径写窄了某些接口没被扫到就少了 Bean。5.2 MyBatis 的 configuration 配置覆盖了 mapperLocationsSpringBoot 集成的 MyBatis 里MybatisProperties类负责读取mybatis前缀的配置。如果你在代码里另外又配置了一个SqlSessionFactoryBean而且没有把mapperLocations传进去那默认的配置就会被覆盖XML 就不会被加载。这种情况我碰到过一次是接手一个老项目里面有人为了自定义拦截器手动建了SqlSessionFactoryBean但没设置mapperLocations。结果所有 XML 全不生效每个 Mapper 方法都报Invalid bound statement。如果你也手动配置了SqlSessionFactoryBean记得加上Bean public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception { SqlSessionFactoryBean factoryBean new SqlSessionFactoryBean(); factoryBean.setDataSource(dataSource); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources(classpath:mapper/*.xml)); return factoryBean.getObject(); }5.3 多模块工程里 XML 路径跨了 jar 包如果是多模块 Maven 项目Mapper 接口在 A 模块XML 在 B 模块的 resources 里那配置classpath:mapper/*.xml只能扫到当前模块的 classpath扫不到依赖 jar 里面的 XML。这时候要改用classpath*:前缀注意有个星号mybatis: mapper-locations: classpath*:mapper/*.xmlclasspath和classpath*的区别是前者只从当前 classpath 根路径找一次后者会扫描所有 classpath 上的 jar 包去匹配。多模块项目里用classpath*能避免很多“找不到 XML”的问题。6. 进阶排查从启动日志找到关键线索很多情况下我们不需要瞎猜看启动日志就能发现端倪。MyBatis 启动的时候会打印加载的 XML 信息我整理了一张速查表方便你对照。日志特征可能原因解决方向日志里完全没有出现任何 XML 加载记录mapper-locations 配置无效或 XML 不在 classpath检查路径配置和打包结果日志里出现了 XML但报错说找不到方法namespace 或 id 不匹配对比接口全限定名和方法名接口能被注入但运行时报错Mapper 接口扫描和 XML 扫描不在同一套配置统一 MyBatis 配置来源部分方法报错部分方法正常同个 XML 里有几条 SQL 的 id 写错逐个对比接口方法和 XML id6.1 用单元测试单独验证 Mapper 加载我在公司里排查的时候如果现场不方便重启整个项目就写一个简单的单元测试只初始化 MyBatis 的 SqlSessionFactory打印出所有已加载的 MappedStatement。SpringBootTest class MapperLoadTest { Autowired private SqlSessionFactory sqlSessionFactory; Test void listMappedStatements() { Configuration configuration sqlSessionFactory.getConfiguration(); for (String statement : configuration.getMappedStatementNames()) { System.out.println(statement); } } }跑一下这个测试所有已经注册的 statement key 一目了然。如果里面没有com.example.mapper.UserMapper.selectById那问题就在 XML 加载环节如果有那问题可能在别的地方。这个办法比翻日志更快尤其是项目大、启动慢的时候省去很多等待时间。6.2 检查 MyBatis 版本和 SpringBoot 版本的兼容性版本兼容问题也是一个容易忽略的坑。SpringBoot 2.x 和 3.x 对 MyBatis 的支持是不同的。SpringBoot 3.x 用的是 Jakarta EE 规范如果 mybatis-spring-boot-starter 版本太低可能不兼容。我见过一个项目SpringBoot 版本升到 3.x 之后原来用的 mybatis-spring-boot-starter 还是 2.x 的旧版本结果不仅出现了Invalid bound statement还有其他奇怪的初始化报错。后来把 starter 升到 3.x 对应的版本才解决。以下是目前比较稳定的配套版本参考SpringBoot 版本mybatis-spring-boot-starter 版本2.7.x2.3.x3.0.x ~ 3.2.x3.0.x需要注意这只是参考实际以你项目的具体依赖树为准。升级版本之前先看 Maven 依赖树里有没有冲突。7. 实操案例一步步定位并解决挑一个我最近处理的实际案例完整走一遍排查流程展示一下解决问题的思路。7.1 现象描述项目是 SpringBoot 2.7.5 MyBatis Plus 3.5.3新增了一个OrderMapperXML 文件放在src/main/resources/mapper/OrderMapper.xml。启动项目正常调用orderMapper.selectOrderList()的时候抛出Invalid bound statement (not found)。7.2 第一步确认 XML 是否进入 classpath我先看了 target/classes/mapper/ 目录下有没有 OrderMapper.xml。结果有所以不是打包问题。7.3 第二步检查 namespace 和 id打开 OrderMapper.xml看 namespacemapper namespacecom.example.mapper.OrderMapper select idselectOrderList resultTypecom.example.entity.Order SELECT * FROM order /select /mapper再看接口package com.example.mapper; public interface OrderMapper { ListOrder selectOrderList(); }namespace 和 id 看起来都对。问题不在这里。7.4 第三步检查 mybatis 配置我打开 application.ymlmybatis: mapper-locations: classpath:mapper/*.xml这也很正常。但项目里配置了 PageHelper 分页插件为了注册拦截器在配置类里手动创建了SqlSessionFactoryBean。问题就在这里——手动创建的 FactoryBean 没有设置mapperLocations导致默认配置失效。把mapperLocations补上之后重启项目问题解决。这个案例的教训是如果你的项目里既用了mybatis开头的配置又手动创建了SqlSessionFactoryBean那 mybatis 配置里的内容可能不会全部生效。手动创建 FactoryBean 时所有的关键属性都要自己设置一遍。8. 注解方式为什么也会报这个错有的人不用 XML全用注解写 SQL。比如Mapper public interface UserMapper { Select(SELECT * FROM user WHERE id #{id}) User selectById(Long id); }这种情况理论上不该报Invalid bound statement。但有一种特殊情况接口里有个方法没有加任何注解而项目里又同时配置了 XML 加载路径。MyBatis 会认为这个方法应该有对应的 XML SQL但没有找到于是报错。所以说注解和 XML 混用的时候要格外小心。一个接口里如果有 10 个方法8 个用 注解2 个写在 XML 里那那两个 XML 方法必须严格按前面说的规则配置好。或者你把所有方法都统一成一种方式避免混用带来的心智负担。我在项目里定的规矩是简单的单表操作用注解复杂的多表关联查询用 XML但同时明确要求同一个 Mapper 接口内尽量只用一种方式。如果确实要混用新加方法的时候先看一眼现有方式是哪种保持一致。8.1 注解写错导致的现象还有一种情况注解 SQL 的返回值类型和接口方法返回类型对不上MyBatis 在解析阶段可能放过去但运行阶段反射到返回类型的时候出问题。这个不会直接报Invalid bound statement但它会转移你的排查视线。我建议排查顺序是先确认是不是绑定问题再看是不是返回类型问题。不要被表象带偏。9. 排查工具和习惯分享除了上面说的排查手段我这里再分享几个实际工作中好用的工具和习惯。9.1 IDEA 自带的结构分析IDEA 里打开 XML 文件时左边会出现一个结构树。如果 MyBatis 插件比如 MyBatisX正确识别了 namespace 和接口的关联那接口方法旁边会有一个小的跳转箭头可以直接从接口跳到 XML 对应的 SQL。如果发现接口方法旁边没有箭头大概率就是映射关系没建立。这个视觉反馈比看日志还要快适合日常开发中即时发现问题。9.2 依赖一个版本也要排除Maven 项目里如果两个依赖传递引入了不同版本的 mybatis 核心包可能会出现实现类加载了 A 版本的而配置类用的是 B 版本的导致映射信息不共享。检查方法mvn dependency:tree重点看有没有多个org.mybatis:mybatis版本。如果有排除旧版本的传递依赖只保留一个。这种问题很隐蔽报错信息和普通的Invalid bound statement一模一样但文件和配置都查不出问题。我大概花了大半天才定位到版本冲突这个经验分享出来希望大家少走弯路。9.3 从“控制台异常堆栈”里还能看出更多这个报错的完整信息一般是org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.example.mapper.UserMapper.selectById注意看冒号后面的全限定名。这个字符串就是 MyBatis 实际查找的 key。把它记下来去configuration.getMappedStatementNames()打印出来的结果里搜一下能搜到就是绑定问题搜不到就是加载问题。这两个问题的解决方向完全不同所以先看这个 key 到底是“有”还是“没有”是最高效的切入点。10. 一劳永逸的预防方案排查经验再多都不如让问题根本不发生。我这里建议几条可以在团队里推行的规范。10.1 强制 XML 文件位置统一项目里统一约定所有 Mapper 的 XML 文件放在src/main/resources/mapper/目录下命名和接口保持一致比如UserMapper.xml。避免有的放 resources有的放 java 目录有的包名又不对。在团队协作中统一约定是降低这类低级错误最有效的办法。我见过不少项目一开始大家都守规矩后来新成员加入没有遵守约定埋下了隐患。10.2 启动时自动校验所有 Mapper 方法都有对应 SQLMyBatis 有个配置项configuration.addMapper或MapperScan的扫描行为。在 SpringBoot 里可以通过实现ApplicationRunner在项目启动完成后检查每个 Mapper 接口的每个方法是否都能在 configuration 中找到对应的 MappedStatement。Component public class MapperBoundCheckRunner implements ApplicationRunner { Autowired private SqlSessionFactory sqlSessionFactory; Override public void run(ApplicationArguments args) { Configuration configuration sqlSessionFactory.getConfiguration(); CollectionClass? mappers configuration.getMapperRegistry().getMappers(); for (Class? mapper : mappers) { for (Method method : mapper.getMethods()) { if (method.isDefault() || method.getDeclaringClass() ! mapper) { continue; } String statementId mapper.getName() . method.getName(); if (!configuration.hasStatement(statementId, false)) { throw new IllegalStateException(Mapper 方法未找到对应的 SQL 语句: statementId); } } } } }这样启动的时候就报错而不是等到运行的时候才报Invalid bound statement。把问题前置到启动阶段修复成本低很多。这个方案我在一个几十人的后端团队里推广过大家都觉得好用。尤其适合那种 Mapper 数量多、命名容易出错的场景。10.3 代码提交前检查在 Git 提交前加一个简单的脚本检查扫描所有 Mapper 接口里的方法名检查 XML 里是否有对应的select id方法名等标签。用 Python 写也完全可以几行正则的事。这种检查不用特别智能只要能把明显的遗漏暴露出来就够用了真正的兜底还是第 10.2 节里的启动校验。11. 不同场景下的完整解决方案对照把前面讲的这些原因和方案整理成一张表以后遇到问题直接对着看。场景典型特征排查重点解决方案XML 没打进 classpathtarget/classes 下没有 XML 文件打包配置、文件位置移到 resources 或配置 build 资源文件在但扫不到target/classes 下能看到 XMLmapper-locations 语法、classpath*检查 yml 配置多模块用 classpath*namespace 不一致启动日志里 XML 注册的 key 和接口全限定名不同包名路径、接口名修正 namespaceid 不一致某个方法报错其他方法正常方法名和 id 逐一对比修正 id没有 Mapper / MapperScan启动时就报没有 Bean扫描注解缺失添加注解手动配置覆盖项目里有自定义 SqlSessionFactoryBean是否设置了 mapperLocations补上 mapperLocations版本冲突多种依赖版本共存依赖树统一版本、排除旧版本注解混用部分方法没加注解也没 XML方法绑定完整性统一方式或补 XML这张表上一列照着查能解决 95% 以上的Invalid bound statement (not found)。12. 最后分享几个冷门但实用的经验上面的内容基本覆盖了主流场景最后我再分享几个平时不怎么被写到文章里的冷门经验。12.1 从 Git 历史里找线索如果你昨天跑得好好的今天突然报了Invalid bound statement那八成是有代码改动。先用git diff看看哪些文件变了重点看这三个维度Mapper 接口是否被重命名或移动包路径XML 文件是否被修改application.yml 里的 mapper 配置是否变过很多时候这种报错是重构的时候不小心导致的。我遇到过一个案例把UserMapper改名为MemberMapper后XML 文件也重命名了但 XML 里面保留了一段旧接口的 SQLid 还是旧方法名结果那段 SQL 就成了“孤儿”调用的时候就报错。12.2 IDEA 缓存导致的“假报错”有几次代码和配置都是对的但 IDEA 编译的时候用了旧的 class 文件。特别是热部署的时候XML 文件被修改了但 IDEA 没有触发重新复制资源导致运行目录里的 XML 还是旧的。解决办法Build - Rebuild Project或者直接mvn clean之后再启动。如果用了 DevTools 热重启有时候要手动点一下重新编译。这个“假报错”是最让人头疼的因为你查了一圈全是对的最后发现是环境缓存的问题。养成一个习惯改完 XML 之后先看一眼 target/classes 里的对应文件时间戳是不是最新的。12.3 线上环境怎么排查线上环境不能随便重启也不会打印 DEBUG 日志。这时候先查两件事第一确认线上包的版本和本地一致。用diff命令比对一下本地构建的 jar 和线上运行的 jar 大小或哈希值排除部署了旧包的可能。第二写一个临时接口调用 Mapper 加载的校验逻辑通过测试调用获知具体的 missing statement而不是直接看是否所有方法都没有绑定。线上不像本地有完整 IDE所以思维要更收敛一些。核心原则还是那句话先确定是“没有这个 key”还是“key 对不上”然后对症下药。我在实际排查中写过最多的结论就是这个报错 80% 是 XML 文件位置问题15% 是 namespace/id 不一致剩下 5% 是各种稀奇古怪的配置或环境问题。把前 95% 的排查流程走一遍最多半小时就能定位。分享这篇文章就是希望大家遇到Invalid bound statement (not found)的时候能少走弯路直接按图索骥。我自己踩过太多次这个坑了有时候一个问题能折腾一整天后来把这些经验沉淀成上面的排查流程之后再遇到类似问题基本 10 分钟内就能定位。如果你在排查过程中有别的场景我漏掉了欢迎补充我后续再更新进去。