1. 先在IDE里复现一次这个报错：对“Invalid bound statement”的理解不能只停留在字面
做SpringBoot项目的人，十有八九都见过这么一段异常：
org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.example.mapper.UserMapper.selectById我第一次遇到时，第一反应是“XML里SQL写错了”，翻半天没发现问题。后来慢慢才知道，这个报错的真正意思是：MyBatis在运行时根据Mapper接口的方法名，去自己的配置里找对应的SQL语句，结果没找到。大白话就是，接口方法有了，但MyBatis没把XML里的那条SQL和这个接口方法绑定起来。
这个报错在SpringBoot+MyBatis项目里属于高频问题。不管你是刚入门的同学，还是已经写了两三年业务的开发，都值得把它的原理和排查路线完整过一遍。因为很多情况下，它不会在项目启动时报错，而是等接口第一次被调用时突然炸出来，线上问题一旦出现，定位成本往往比本地开发高很多。
1.1 一个最典型的复现场景
先看一个非常典型的例子。项目结构大概是这样：
src/main/java/com/example/ ├── SpringBootApplication.java ├── controller/UserController.java ├── mapper/UserMapper.java └── service/UserService.java src/main/resources/ ├── application.yml └── mapper/UserMapper.xmlUserMapper接口内容：
public interface UserMapper { User selectById(Long id); }UserMapper.xml内容：
<mapper namespace="com.example.mapper.UserMapper"> <select id="selectById" resultType="com.example.entity.User"> select * from user where id = #{id} </select> </mapper>application.yml里配置了：
mybatis: mapper-locations: classpath:mapper/*.xml启动类上也加了@MapperScan("com.example.mapper")。
看起来该配的都配了，但一调用userMapper.selectById(1L)，控制台照样抛Invalid bound statement (not found)。问题出在哪？接下来我把MyBatis的绑定机制拆开讲，你就明白了。
1.2 MyBatis绑定机制：接口方法是如何和XML关联起来的
MyBatis在启动过程中，会做几件关键的事：
第一，扫描Mapper接口。通过@MapperScan或者@Mapper注解，把接口注册到MyBatis的MapperRegistry中。这一步决定了“哪些接口是MyBatis要管理的”。
第二，解析XML文件。根据mybatis.mapper-locations配置，加载所有XML，读取<mapper namespace="...">节点，把namespace作为Mapper接口的全限定名，把<select>、<insert>、<update>、<delete>节点的id和SQL语句包装成MappedStatement对象。
第三，建立绑定。当调用某个Mapper接口的方法时，MyBatis会通过MapperProxy动态代理，根据当前方法所属的接口全限定名和方法名，拼接成一个statementId，例如：
com.example.mapper.UserMapper.selectById然后在自己的配置里找有没有对应的MappedStatement。找到了就执行SQL，找不到就抛出BindingException: Invalid bound statement (not found)。
这里可以打个比方：接口方法相当于“柜员号”，XML里的SQL语句相当于“柜子里的业务凭证”。MyBatis要做的事情，就是把柜员号和业务凭证一一对应起来。如果柜员号存在，但凭证没放进柜子，或者凭证标签上的柜员号写错了，业务就没法办，最后就是“not found”。
1.3 为什么不是启动报错，而是等到调用时才炸
很多人会问：既然绑定不上，为什么启动时不告诉我？
MyBatis的默认行为是：Mapper接口会被注册，XML里的statement也会被加载，但并不会在启动阶段逐一校验“每个接口方法是否都能找到statement”。接口方法被调用时，MapperProxy才会去执行查找逻辑。如果没有提前做校验测试，这个问题会一直潜伏到第一次调用。
这一点和Spring的依赖注入有点像：很多Bean之间的引用问题，也是等到真正调用时才暴露。所以我在项目里强烈建议，至少要有一个轻量级的冒烟测试，把所有Mapper方法都“碰”一遍。
不过话说回来，有些场景下启动阶段也会报错。比如你的XML文件本身格式非法，或者namespace对应了一个不存在的接口，MyBatis在解析XML时就会抛异常。但“接口方法有、XML没绑定上”这个类型，绝大多数是运行期才出现。
2. 从六个方向排查：XML没生效还是Mapper接口没注册
这个报错一旦出现，我建议按照下面六个方向依次排查。十分钟内基本能定位。
2.1 第一检查：XML文件到底有没有进到编译产物里
最先要看的是target/classes目录。很多人只在IDE里看到src/main/resources/mapper下有XML，但项目跑起来时用的是编译后的target/classes，如果XML没有被打包进去，MyBatis根本扫描不到。
在项目根目录执行：
mvn clean compile然后查看：
ls target/classes/mapper/如果目录里没有UserMapper.xml，说明Maven没有把XML文件复制到输出目录。常见原因是：XML文件被放在了src/main/java某个包下，而不是src/main/resources下。Maven默认不会把src/main/java里的非Java文件全部打包，除非你在pom.xml里明确配置了resources覆盖。
我个人的建议是：XML统一放在src/main/resources/mapper目录下，不要和Java源码混在一起。如果项目历史原因导致XML已经在src/main/java里了，可以临时在pom.xml中这样加：
<build> <resources> <resource> <directory>src/main/java</directory> <includes> <include>**/*.xml</include> </includes> </resource> <resource> <directory>src/main/resources</directory> </resource> </resources> </build>但这不是长期方案。把XML放回resources目录，才是更干净的维护方式。
2.2 第二检查：mybatis.mapper-locations配的路径和实际目录对不对
路径配置是最容易被忽视的环节。常见配置有这么几种：
mybatis: mapper-locations: - classpath:mapper/*.xml但很多项目实际目录是src/main/resources/mapper/user/UserMapper.xml，这时候classpath:mapper/*.xml只能匹配mapper目录下的一层XML，无法匹配子目录里的文件。应该改成：
mybatis: mapper-locations: - classpath:mapper/**/*.xml*只匹配当前目录，**匹配任意多层子目录。这个通配符的差别，是很多“文件夹套了一层就没扫描到”的根源。
另外还要注意classpath:和classpath*:的区别。单模块项目用classpath:够用；多模块工程里，如果MyBatis的XML分布在多个模块的jar包中，建议使用classpath*:mapper/**/*.xml，这样会扫描整个classpath路径下的所有匹配资源。
如果你用的是MyBatis-Plus，还要特别注意配置前缀。MyBatis-Plus虽然底层兼容MyBatis，但它的自动配置读的是mybatis-plus前缀，很多人写了：
mybatis: mapper-locations: classpath*:mapper/**/*.xml实际上MyBatis-Plus根本不认，正确写法是：
mybatis-plus: mapper-locations: classpath*:mapper/**/*.xml我见过太多因为前缀写错，导致BaseMapper自带方法正常、自定义XML方法全部Invalid bound statement的情况。
2.3 第三检查：@MapperScan到底扫了哪些包
接口本身没有注册到MyBatis，也会导致这个报错。SpringBoot中有两种方式注册Mapper接口：
方式一，在接口上加@Mapper注解：
@Mapper public interface UserMapper { User selectById(Long id); }方式二，在配置类或启动类上加@MapperScan：
@SpringBootApplication @MapperScan("com.example.mapper") public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }如果@MapperScan扫描的包和实际接口所在的包不一致，接口就没注册成功。MyBatis启动时可能不会说“找不到Mapper”，只会在调用时发现接口根本不在管理范围内，最终同样表现成Invalid bound statement。
这里有个容易踩的坑：项目里用了tk.mybatis或者mybatis-plus，它们各有自己的@MapperScan注解。比如tk.mybatis.spring.annotation.MapperScan和org.mybatis.spring.annotation.MapperScan包名看起来很相似，但机制不同。如果导错了包，扫描行为可能不符合预期。建议在IDE里点进@MapperScan，确认import路径是你想要的那个。
2.4 第四检查：namespace和statementId必须一字不差
XML里的namespace必须等于接口的全限定名，不能有大小写错误、不能多空格。<select>的id必须等于接口方法名。
举个例子，接口是：
package com.example.mapper; public interface UserMapper { User selectById(Long id); }XML就应该是：
<mapper namespace="com.example.mapper.UserMapper"> <select id="selectById" resultType="com.example.entity.User"> select * from user where id = #{id} </select> </mapper>如果namespace少写了一个包名，比如com.example.UserMapper，或者select id写成了selectByIdd，MyBatis在拼接statementId时肯定对不上。
还有一个细节：接口方法重载在MyBatis里非常容易出问题。MyBatis的statementId由“接口全限定名+方法名”组成，它不支持同方法名重载时的精确区分。如果你在一个Mapper接口里写了两个同名方法，XML里也配了多个相同id的select，最终会有一个方法绑定不到正确的statement。所以我的规矩是：Mapper接口中不要使用方法重载。
再看一眼resultType。虽然resultType不对不会直接触发Invalid bound statement，但有可能导致MyBatis在解析XML时报其他错误，从而让这个statement没有成功注册。XML中如果存在参数类型、返回值类型类找不到的情况，同样会表现为该语句没绑定上。排查时可以把resultType里的类先写成简单的map试一下。
2.5 第五检查：Spring Boot版本和MyBatis Starter版本是否匹配
这个点早期很容易被忽略，尤其Spring Boot 3.x出来以后，整个生态的javax到jakarta迁移带来了很多兼容性问题。
如果你用的是Spring Boot 3.x，却还在用mybatis-spring-boot-starter1.x或者2.x版本，MyBatis的自动配置很可能没有正确生效。结果是：接口没有被代理，或者XML没被加载，运行时各种Invalid bound statement、Mapper method not found。
我根据当前常用版本整理了一个参考组合：
| Spring Boot版本 | 建议MyBatis Starter版本 | 说明 |
|---|---|---|
| 2.5.x | mybatis-spring-boot-starter 2.2.x | 经典组合 |
| 2.7.x | mybatis-spring-boot-starter 2.3.x | 2.x最后一个稳定区间 |
| 3.0.x-3.2.x | mybatis-spring-boot-starter 3.0.x | 基于jakarta包名 |
| 3.3.x及以上 | mybatis-spring-boot-starter 3.0.4+ | 持续跟进新版本修复 |
如果是公司老项目升级Spring Boot，一定要同步升级MyBatis Starter。不要只在pom里改了Spring Boot版本，其它依赖不跟着动。排查时，先看依赖树：
mvn dependency:tree -Dincludes=org.mybatis:mybatis-spring-boot-starter看看实际生效的starter版本，再对照Spring Boot版本判断是否合理。还有一种情况是项目里同时引入了mybatis-spring-boot-starter和mybatis-plus-boot-starter，两者都尝试创建SqlSessionFactory，可能造成配置互相覆盖。这类问题很难一眼看出来，建议把多余的依赖去掉，保持单一来源。
2.6 第六检查：热部署、缓存、编译环境带来的“假报错”
有时候代码和配置都没问题，但运行环境里的class是旧的。常见场景包括：
- 使用spring-boot-devtools，资源文件没有触发重启，XML没有被重新加载。
- IDE增量编译没有把新加的XML复制到target目录。
- 本地启动了一个旧进程，新代码根本没生效。
- Docker镜像里打进去的jar包没有包含最新XML。
遇到这种情况，清理并重启一次最有效：
mvn clean mvn package -DskipTests java -jar target/your-app.jar如果是IDE，最好先Build -> Rebuild Project，再检查target目录。不要觉得这种低级问题不会发生在自己身上，忙起来的时候我经常因为“没重启”白查半小时。
3. 一套可以直接抄的完整落地方案：从零搭建不报错的配置
为了让你少走弯路，我给出一个完整的、当前比较稳的SpringBoot + MyBatis配置方案。
3.1 依赖和版本选择
以Spring Boot 3.2.x为例，pom.xml核心依赖如下：
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.5</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>3.0.4</version> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> </dependencies>这里最关键的版本是mybatis-spring-boot-starter，一定要使用3.0.x及以上。2.x版本在Spring Boot 3.x下无法正常工作，这是社区里已经验证过很多次的结论。
3.2 application.yml配置
spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: root mybatis: mapper-locations: classpath:mapper/**/*.xml configuration: map-underscore-to-camel-case: true重点说明两点：
第一，mapper-locations使用的是classpath:mapper/**/*.xml，可以覆盖子目录。
第二，map-underscore-to-camel-case开启后，数据库列名user_name能自动映射到Java属性userName。这虽然不是本次报错的直接原因，但能减少大量字段映射错误引起的其它问题。
3.3 Mapper接口与XML的对应写法
实体类：
public class User { private Long id; private String userName; private Integer age; // 省略getter/setter }Mapper接口：
package com.example.mapper; import com.example.entity.User; public interface UserMapper { User selectById(Long id); }XML文件放在src/main/resources/mapper/UserMapper.xml：
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="com.example.mapper.UserMapper"> <select id="selectById" resultType="com.example.entity.User"> select id, user_name, age from user where id = #{id} </select> </mapper>注意<mapper>节点上我加入了DOCTYPE声明。别小看这一行，很多XML复制场景下丢掉它会引入奇怪的解析问题。
启动类：
@SpringBootApplication @MapperScan("com.example.mapper") public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }3.4 编译产物验证步骤
写完上述代码后，每次改动XML，建议执行一次编译验证：
mvn clean compile然后查看目录结构：
find target/classes -name "*.xml"正常输出应该包含：
target/classes/mapper/UserMapper.xml如果XML没有出现，说明Maven资源配置有问题，先去检查pom.xml的build节点和文件存放位置。
3.5 用单元测试提前暴露问题
因为这类问题通常不是启动时报错，所以最好写一个简单的单元测试，在项目启动时自动检查所有Mapper方法是否都有对应的MappedStatement。
推荐做法是注入SqlSessionFactory，拿到MyBatis的Configuration，遍历所有已注册的Mapper接口方法，逐个判断configuration.hasStatement(...)：
@Component public class MapperBindingChecker implements ApplicationRunner { private final SqlSessionFactory sqlSessionFactory; public MapperBindingChecker(SqlSessionFactory sqlSessionFactory) { this.sqlSessionFactory = sqlSessionFactory; } @Override public void run(ApplicationArguments args) { Configuration configuration = sqlSessionFactory.getConfiguration(); for (Class<?> mapperType : configuration.getMapperInterfaces()) { for (Method method : mapperType.getMethods()) { if (method.isDefault() || method.getDeclaringClass() == Object.class) { continue; } String statementId = mapperType.getName() + "." + method.getName(); if (!configuration.hasStatement(statementId, false)) { throw new IllegalStateException("Mapper method not bound: " + statementId); } } } } }这段代码会在SpringBoot启动完成后自动执行，一旦有Mapper方法没有绑定SQL，立刻抛异常，把问题挡在发布之前。
4. 现场问题排查实录：这些场景我都踩过
下面整理几个我实际处理过的真实场景，每个场景都有特定的特征和坑。
4.1 启动正常，第一次调用service就报错
现象：项目能起来，前端一发请求，控制台立刻抛Invalid bound statement。
排查过程：先看了target/classes/mapper目录，发现是空的。再检查application.yml，配置的是：
mybatis: mapper-locations: classpath:mapper/*.xml实际XML文件在：
src/main/resources/mapper/user/UserMapper.xml目录多了一层user，*匹配不到子目录。改成classpath:mapper/**/*.xml后，问题消失。
经验：遇到这个报错，第一件事不是看XML内容，而是确认XML有没有真正出现在编译输出目录里。
4.2 多模块工程里resource没有跟随打包
现象：本地IDEA启动没问题，但打成jar包部署后，调用Mapper方法报错。
排查过程：本地IDE编译时，IDEA会自己把resources资源复制到target目录，所以本地正常。但Maven打包时，某个模块的pom配置有问题，没有把src/main/resources/mapper下的XML打进去。解开jar包一看，里面没有XML。
解决方式：检查子模块pom.xml里的<resources>配置，确认没有把**/*.xml排除掉。Maven默认会打resources目录下的内容，但如果之前为了某些优化配置了excludes，就可能把XML也过滤掉了。
我后来在所有子模块统一了规范：XML只放在src/main/resources/mapper，不在pom里做特殊排除。这样最省心。
4.3 使用MyBatis-Plus和自定义XML混用时的绑定冲突
现象：项目用MyBatis-Plus，BaseMapper自带的selectById、selectList都是好的，但自定义的selectUserWithOrders一调用就报Invalid bound statement。
排查过程：MyBatis-Plus的BaseMapper方法是由Plus本身提供的，不依赖XML，所以自带方法没问题。自定义方法需要XML绑定。检查application.yml发现项目里写的是：
mybatis: mapper-locations: classpath*:mapper/**/*.xml但MyBatis-Plus不使用mybatis这个前缀，需要改成：
mybatis-plus: mapper-locations: classpath*:mapper/**/*.xml改成之后，自定义方法立刻正常。
经验：使用MyBatis-Plus时，所有MyBatis相关配置都走mybatis-plus前缀，包括type-aliases-package、map-underscore-to-camel-case等。混着写会让人排查半天。
4.4 Spring Boot 3.x + 新版starter的组合陷阱
现象：项目从Spring Boot 2.7升级到3.2，启动后部分Mapper方法能正常执行，部分方法报Invalid bound statement，还有的启动直接报错，提示找不到SqlSessionFactory。
排查过程：依赖树里发现mybatis-spring-boot-starter还是2.3.2。Spring Boot 3.x用的是jakarta.*包名，而MyBatis Starter 2.x依赖的是javax.*，自动装配条件不成立，导致Mapper接口没有被正常代理。
解决方式：把mybatis-spring-boot-starter升到3.0.4，重新clean package后恢复正常。
经验：升级Spring Boot大版本时，先用mvn dependency:tree把所有和MyBatis相关的依赖全部确认一遍。不要只看主版本升级，starter版本也要同步。
5. 防止再犯的几个工作习惯
经历过几次Invalid bound statement之后，我沉淀了几个小习惯，能大幅降低出现问题的概率。
5.1 给XML文件在IDE里装“眼睛”
在IDEA里安装MyBatisX插件，或者使用MyBatis自带的Mapper跳转功能。配置正确的情况下，接口方法左侧会有一个小图标，点击可以直接跳到XML里的对应SQL。
如果方法没有被绑定，IDEA会有明显提示，XML里的namespace和接口不匹配时也会给出警告。这些东西虽然不能完全替代编译期检查，但能给日常开发提供很强的即时反馈。
5.2 提交前用一条命令检查XML与接口的对应关系
如果没有MyBatisX插件，也可以用一个小脚本或者单元测试来检查。最简单的方式是写一个测试，扫描所有Mapper接口，再遍历XML中的statementId，看看集合是否一致。
更轻量的做法是，提交代码前执行：
grep -r "namespace=" src/main/resources/mapper看看namespace是否都是预期的接口全限定名。虽然粗糙，但能抓住很多手误。
5.3 使用代码生成器保持命名统一
新项目或者新模块，我强烈建议直接用MyBatis Generator或MyBatisX代码生成器生成Mapper接口、XML和实体类。生成器产出的文件命名规范统一，namespace、id这些都是现成的，不会出现手写时打错字母的问题。
但生成器也有一个坑：它默认把XML生成在src/main/java对应的包目录下，这个位置和Maven默认资源打包方式不兼容。生成后一定要手动把XML移动到src/main/resources/mapper目录，或者调整生成器的输出目录配置。
最后分享一个我个人的排查习惯：遇到Invalid bound statement (not found)，我先看这个statementId后面的接口路径，拿它去target/classes里全局搜索，看XML有没有、namespace对不对、id对不对。把这三个点确认完，百分之八十的问题都能定位。真正难的往往不是报错本身，而是报错被各种构建缓存、路径通配符、版本兼容性掩盖之后，我们还在用错误的方式去找原因。
