Spring Boot + MyBatis 报 Invalid bound statement 原因与排查方法

这个报错我在好几个用 Spring Boot + MyBatis 搭管理后台的项目里都遇到过，最近一次是在跑若依（RuoYi）二开项目的时候——登录正常，页面也加载出来了，一点“参数设置”就抛异常，控制台第一行写着：

code复制org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.ruoyi.system.mapper.SysConfigMapper.selectConfigList

这句话翻译成大白话就是：MyBatis 在执行 SysConfigMapper.selectConfigList() 这个方法时，在它自己的“语句注册表”里找不到对应的 SQL。注意这跟你 SQL 写没写对没有直接关系，不管 SQL 里放了什么东西，MyBatis 连这个“语句”都没登记上，后面自然没法执行。这也是为什么新手刚接触这块时会非常困惑：代码明明从仓库拉下来了，接口没改过，XML 也摆在资源目录里，凭什么说 not found？

这类问题本质上是 Spring Boot + MyBatis 项目里的“高频经典病”，搜索热词里能同时出现 SprintBootException、BindingException 和 invalid bound statement not found，本身就说明很多人踩过。标题里那个 SprintBootException 是拼写变形，实际要处理的还是 Spring Boot 应用里 MyBatis 的绑定异常。而报错尾缀拖着一串 com.ruoyi.system.mapper.SysConfigMapper，恰好是若依这类多模块框架里最有代表性的场景。下面我会从报错原理开始，把常见成因一层层剥开，再按实际排查顺序给出可复现的解决办法，同时对 SysConfigMapper 这个具体报错做一次完整复盘。无论是第一次写 Spring Boot 的初学者，还是被多模块项目反复折腾过的后端开发，都可以照着这个思路快速定位问题。

1. 先把报错读明白：Invalid bound statement 到底在说什么

1.1 从异常堆栈看它发生在哪一步

只贴第一行异常往往不够，完整的堆栈里最有价值的信息其实是方法调用链。一个典型的异常开头长这样：

code复制org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.ruoyi.system.mapper.SysConfigMapper.selectConfigList
	at org.apache.ibatis.binding.MapperMethod$SqlCommand.<init>(MapperMethod.java:227)
	at org.apache.ibatis.binding.MapperMethod.<init>(MapperMethod.java:49)
	at org.apache.ibatis.binding.MapperProxy.invoke(MapperProxy.java:63)
	at org.springframework.aop.framework.JdkDynamicAopProxy.invoke(JdkDynamicAopProxy.java:223)
	at com.sun.proxy.$ProxyXXX.selectConfigList(Unknown Source)
	...

看到 MapperProxy.invoke 这层就很清楚了：调用方拿到的其实是一个 MyBatis 为 Mapper 接口生成的动态代理对象。方法被调用时，代理会先去做一次“翻译”，把接口方法翻译成 MyBatis 内部真正要执行的 statement。如果翻译失败，就抛 BindingException。再往下看，异常出自 MapperMethod$SqlCommand 的构造方法，这个构造过程要做的事就是从全局配置里反查一个 MappedStatement。你可以把 MappedStatement 理解成一条“已经解析好、可以在数据库上执行”的 SQL 指令，它包含 SQL 文本、参数映射、返回值映射、缓存策略等一堆信息。没有它，MyBatis 根本没有执行依据。

所以 Invalid bound statement not found 的核心意思就是：mappedStatements 这个大字典里，没有 com.ruoyi.system.mapper.SysConfigMapper.selectConfigList 这个 key。查不到 key，自然构造不出执行命令。

1.2 为什么启动时不报、调用时才炸

很多人在这时候会有一个巨大的疑问：如果是 Mapper XML 没加载，那为什么 Spring Boot 启动阶段不直接失败？项目照样起来，登录也正常，偏偏点某个功能才把这个异常炸出来。这个疑问背后是 MyBatis 和 Spring 协作时的一个“懒惰”机制。

当 Spring 容器扫描到 Mapper 接口并注册 Bean 时，它做的只是生成一个代理对象放进了容器。这个阶段会检查接口能不能被代理、有没有重复声明等问题，但不会去确保接口里的每个方法都能找到对应 SQL。换句话说，容器只知道 SysConfigMapper 是可用 Bean，不知道 selectConfigList() 背后有没有 SQL。等你真正调用 selectConfigList() 的时候，代理才去全局配置里找 statement。如果 XML 没加载，或者 XML 里没有对应的标签，或者加载到的不是这个 namespace，命中的结果就是 not found。

这也是类似问题排查起来有点绕的原因。项目能启动，日志里也看不到红字，只有业务操作到特定方法时才崩，表现非常像“某个方法写错了”。实际上问题并不在方法本身，而在 MyBatis 的“方法—SQL 映射登记表”里。因此遇到这种情况，先别急着改 SQL，先确认 statement 到底有没有注册进去，以及为什么没有注册进去。

2. MyBatis 是怎么把方法和 SQL 绑到一起的

2.1 statement 就是一条带唯一 ID 的 SQL 执行配置

深入到 MyBatis 内部，有一张非常核心的表，名字叫 mappedStatements，本质是一个 Map，key 是 statement 的完整 ID，value 是 MappedStatement 对象。每次执行 SQL，MyBatis 都会用这个 ID 去 Map 里取对应的执行配置。

这个 ID 不是随便起的，它由两部分拼接：接口的全限定名 + 方法名。比如 com.ruoyi.system.mapper.SysConfigMapper.selectConfigList 就是一个完整的 statement ID。前面一大串是 Mapper 接口的全限定名，后面是对应的 select、insert、update、delete 标签里 id 属性的值。

从用户视角看，你在 Java 里写的是：

java复制List<SysConfig> list = sysConfigMapper.selectConfigList(new SysConfig());

MyBatis 看到的请求是：

code复制statementId = "com.ruoyi.system.mapper.SysConfigMapper.selectConfigList"

如果 Map 里查不到这个 ID，就立刻抛出 Invalid bound statement。所以整个问题的本质可以压缩成一句话：方法名到 statement ID 的注册链路断掉了。

2.2 XML 里的 namespace 和 id 必须能拼出同一个 ID

接口方法那边通过“接口全限定名 + 方法名”生成查询 key，那 XML 这边怎么保证 key 一致？靠的是 <mapper> 标签的 namespace 和内部 SQL 标签的 id。一个标准结构是这样：

xml复制<mapper namespace="com.ruoyi.system.mapper.SysConfigMapper">
    <select id="selectConfigList" parameterType="SysConfig" resultMap="SysConfigResult">
        select config_id, config_name, config_key, config_value, config_type
        from sys_config
        <where>
            <if test="configName != null and configName != ''">
                AND config_name like concat('%', #{configName}, '%')
            </if>
        </where>
    </select>
</mapper>

MyBatis 解析这份 XML 时，会把 namespace + "." + id 拼起来，得到 com.ruoyi.system.mapper.SysConfigMapper.selectConfigList，然后作为 key 放进 mappedStatements。只要这个步骤成功，接口调用时就能查到。

这里有一点特别容易忽略：namespace 写错了不会在解析 XML 的时候立刻报错，而是会让 XML 里的 SQL 注册到另一个“马甲”下面。比如 namespace 写成 com.ruoyi.system.mapper.SysConfigMapperCopy，XML 能正常解析，接口也是正常 Bean，但两边 ID 对不上，照样 not found。所以排查时不要只看 XML 文件存在不存在，还要看 namespace 到底写的什么。

2.3 Spring Boot 启动阶段其实干了一串注册动作

在 Spring Boot + MyBatis 项目里，Mapper 接口要能被 Service 层注入，一般靠 @MapperScan 或者 @Mapper 注解完成。但接口扫描只是第一件事，后头还有一串组装动作：

1. Spring 扫描到 Mapper 接口，为它注册一个 MapperFactoryBean；
2. MyBatis 的 Configuration.addMapper() 把接口加入 MapperRegistry；
3. 注册过程中会解析接口方法上的注解 SQL，以及寻找同路径下的 XML 映射文件；
4. 所有 XML 中的 MappedStatement 被放入全局 mappedStatements；
5. 调用时再按 key 检索执行。

刚才说到的 mapperLocations 配置，负责告诉 MyBatis 去哪些资源路径下扫描 XML。若依框架里的典型配置是：

yaml复制mybatis:
    typeAliasesPackage: com.ruoyi.**.domain
    mapperLocations: classpath*:mapper/**/*Mapper.xml

如果你用的不是纯 MyBatis 而是 MyBatis-Plus，配置前缀会变成 mybatis-plus，但 mapperLocations 的写法逻辑基本一致。很多出错项目的症状，就是配置文件里少了这一行，或者路径通配符写错，导致 XML 压根没进入扫描范围。文件在磁盘上位置没错，但 MyBatis 根本没被引导去看它。

3. 分梯队排查：我建议的从浅入深顺序

这类问题有一个很致命的陷阱：成因多，症状雷同。XML 路径不对会报这个，namespace 错了也报这个，甚至方法重载也会造成异常。面对多种成因，我建议按下面几个梯队依次排查，而不是凭感觉乱改配置。

3.1 第一梯队：确认 XML 文件是否真的在运行环境中

最容易被忽略的答案是“文件不在”。注意这里是“运行环境”，不是“源码目录”。开发时你在 IDEA 里看到的 src/main/resources/mapper/system/SysConfigMapper.xml 只是源码，真正被加载的是编译输出目录里的文件。如果 IDE 没有自动同步资源，或者 Maven 过滤配置漏掉了某个目录，编译输出的 target/classes 里可能根本没有这个 XML。

所以第一件事就是打开 target/classes 目录，按同样的包路径看一眼：

bash复制find target/classes -name "SysConfigMapper.xml"

如果项目是多模块，比如若依把 mapper 放在 ruoyi-system 模块，而启动模块是 ruoyi-admin，还得检查每个模块各自的 target/classes。缺失的情况下，先别纠结 MyBatis 配置，把构建流程修好才是重点。Maven 构建后重新 find，文件出现，问题就解决了一大半。

3.2 第二梯队：检查 mapperLocations 配置是否管到了 XML 所在目录

XML 文件确定存在后，接下来看配置。重点检查两个项目：

yaml复制mybatis:
    mapper-locations: classpath*:mapper/**/*Mapper.xml

使用通配符 * 和 ** 的语义要先确认：* 只匹配当前目录下的一个名字段，** 才能匹配任意层级目录。很多同学的 XML 放在 com/ruoyi/system/mapper/ 下面，但配置写的是 classpath*:mapper/*/*.xml，层级差一层就导致扫描不到。

另外不要忘了字符编码问题。如果 XML 或 YAML 文件里出现了特殊符号、中文注释，并且构建工具开了资源过滤，可能导致运行时 XML 已经被破坏。更隐蔽的是某些资源插件会把 ${...} 当作占位符去替换，把 SQL 里的字符串表达式改得面目全非。这种问题不体现在 find 的结果上，而是体现在文件内容上，所以要顺手打开编译后的 XML 看一眼，而不是只看源码 XML。

3.3 第三梯队：逐字比对 namespace 和 id

配置没问题，文件也存在，这时候要坐下来把接口和 XML 摊开，用肉眼或脚本比对命名空间和方法名。最常犯的错误包括：

• namespace 里把 SysConfigMapper 误写成 SysConfigMap，多一个字母少一个字母；
• XML 的 <select> 标签 id 和接口方法名不一致，比如接口叫 selectConfigList，XML 写成了 selectConfigLists；
• 从别的模块复制代码时，namespace 忘了改成新模块的完整包名。

这里我提供一个比较实用的验证技巧：在启动日志里临时打开 MyBatis 的日志级别，看启动阶段到底加载了哪些 XML 和 statement。以 logback 为例，可以在配置里临时加：

yaml复制logging:
    level:
        org.mybatis: debug
        org.apache.ibatis: debug

然后观察启动日志，搜索 SysConfigMapper。如果日志里根本没有加载这条 XML 的记录，说明文件路径或扫描配置不对；如果加载了但不报错，再看 XML 里的 statement 名。日志是定位这类问题最直接的“证词”。

3.4 第四梯队：接口方法多了一个，而 XML 里没加对应标签

前几个梯队排查的是“整片 XML 没加载”的场景，但还有另一种高频场景：整个 XML 加载了，大部分方法也正常，只有某一个方法报 not found。这种情况十有八九是新加了接口方法，却忘记在 XML 里补对应的 <select> 或 <update> 标签。

比如你为了新增需求，在 SysConfigMapper 接口里加了一个新方法：

java复制public List<SysConfig> selectConfigListByUser(Long userId);

XML 里却只保留原有的 selectConfigList。当 Service 调用 selectConfigListByUser 时，MyBatis 拿着 SysConfigMapper.selectConfigListByUser 去找 statement，结果自然是空。这个问题在团队协作开发时特别常见，A 同事改了接口代码，B 同事不知道，或者 Git 合并时 XML 改动冲突后被丢弃。遇到“只有某个方法报错，其他方法都正常”的情况，直接对比接口方法和 XML 标签即可。

3.5 第五梯队：target 目录和 Jar 包里的“幽灵文件”

还有一种非常折磨人的情况：源码 XML 正确，配置也正确，find 能看到文件，但程序就是报错。这时候要怀疑你的运行环境加载的并不是你刚看到的那个文件。

在 IDEA 中直接点启动时，如果项目是多模块，并且某些模块是以 Jar 形式依赖的，那么实际生效的是本地 Maven 仓库里的旧 Jar。旧 Jar 里可能没有最新的 XML，也可能包含一份旧的 namespace 配置。你改了源码后没有执行多模块的 install，导致启动模块还是引着仓库里那份过期文件。

遇到这种情况，最好把依赖关系摊开看，甚至用命令检查 Jar 内部。以若依项目为例：

bash复制jar tf ruoyi-system-4.7.0.jar | grep -i SysConfigMapper

如果 Jar 里 XML 路径不对或者压根没有，就把整个多模块重新构建一遍：

bash复制mvn clean install -Dmaven.test.skip=true

然后再去启动。这个动作能解决相当大比例的“我明明改了却没有效果”问题。

3.6 第六梯队：多 Module 与 Maven 构建过滤的特殊问题

走到这里还没解决的话，就要考虑 Maven 资源过滤导致的隐蔽问题。典型场景是：项目在 pom.xml 中配置了资源过滤，想对 properties 文件做变量替换，但没有排除 xml 后缀，导致 XML 文件在打包时也被过滤了一遍。如果 XML 里的内容碰上有 ${xxx} 这种文本，就会被替换成空字符串或错误内容，XML 结构被破坏，MyBatis 在解析时就可能跳过部分文件，甚至直接拒绝加载。

检查思路是看 pom.xml 中 <resources> 标签的内容：

xml复制<resources>
    <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
        <excludes>
            <exclude>mapper/**</exclude>
        </excludes>
    </resource>
</resources>

比较稳妥的做法是把 mapper 目录排除在过滤范围之外，或者把非过滤扩展名加上。用 Spring Boot 官方打包插件时，多数情况下不会主动过滤 XML，但有些自己定义了 parent pom 的项目，很容易在这里翻车。排查这种问题，一定要对比 src/main/resources 和 target/classes 下同名 XML 的内容，而不是只看文件列表。

4. 以 SysConfigMapper 为例做一次完整排查复盘

4.1 根据报错信息先缩小范围

这次遇到的具体报错是 com.ruoyi.system.mapper.SysConfigMapper.selectConfigList，重点在 ruoyi-system 模块。知道了模块，先去确认三件事：接口文件在哪、XML 文件在哪、启动模块的配置在哪。

若依的目录结构大致是这样：

text复制ruoyi-admin/src/main/resources/application.yml
ruoyi-system/src/main/java/com/ruoyi/system/mapper/SysConfigMapper.java
ruoyi-system/src/main/resources/mapper/system/SysConfigMapper.xml

看一眼接口方法与 XML 的对应关系，内容正常，说明问题大概率不在方法拼写。于是我直接打开了 ruoyi-system/target/classes，结果没找到 mapper/system/SysConfigMapper.xml。这就解释了为什么启动时没有加载到 statement。但源码里难道没有？有一种原因很常见：ruoyi-system 的 pom.xml 中资源目录配置写了只包含某些路径，或者构建时 IDE 没有重新编译该模块，把目标目录清空了。这种情况下，源码还在，但编译产物里没有。

处理方式不复杂，回到项目根目录执行：

bash复制mvn clean install -Dmaven.test.skip=true

重新构建后，再次查看 ruoyi-system/target/classes/mapper/system/SysConfigMapper.xml，文件出现了。启动服务，再调用一次功能，异常消失。

4.2 换一种更常见的场景：XML 文件和接口方法错位

有时候构建没问题，XML 文件也正常出现了，但某个接口方法还是报 not found。这次我把场景模拟得更具体一点。团队里有人在 SysConfigMapper.java 里新增了一个方法：

java复制SysConfig selectConfigByKey(String configKey);

但 SysConfigMapper.xml 文件中，对应的 <select> 标签写得不对：

xml复制<select id="selectConfigByKeys" parameterType="String" resultMap="SysConfigResult">

selectConfigByKey 和 selectConfigByKeys 就差一个字母，运行时却会被 MyBatis 判定为两个完全不同的 statement。这种错误靠肉眼 review 不一定能看出来，最好的办法是写个小脚本把接口方法名和 XML 标签 ID 都抽取出来做差集。手写脚本可能有点重，但小型项目里用文本搜索就已经够用。

4.3 验证问题是否真正被修复

改动完成之后，不要光看管理页面能访问就结束。建议再做一次更有说服力的验证：在调用链路上打印 MyBatis 的执行日志，确认 SQL 真的发到了数据库。开启方式很简单：

yaml复制mybatis:
    configuration:
        log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

这时再调一次接口，日志里能看到这样的输出：

text复制==>  Preparing: select config_id, config_name, config_key, config_value, config_type from sys_config ...
==> Parameters: ...
<==    Columns: ...
<==        Row: ...

看到 Preparing 和 Parameters 就说明 statement 已经绑定成功了。如果日志还是只报 BindingException，说明修复还没有真正生效，需要回到第五梯队继续查 Jar 包和编译产物。

5. 我的快速判断脚本与长期预防思路

5.1 从日志到文件的两条直接命令

排查这类问题，我不建议每次都从头翻文件。先跑几个命令把最基础的信息收集回来，能省下一半时间。在项目根目录执行：

bash复制mvn clean install -Dmaven.test.skip=true -q
find . -path "*/target/classes/*" -name "SysConfigMapper.xml" -print

第一行是干净构建，第二行确认所有模块的编译产物里都有 XML。如果 Output 里列出了 ruoyi-system/target/classes/mapper/system/SysConfigMapper.xml，说明文件层面OK。接着再看 Jar 包：

bash复制find ~/.m2/repository -name "ruoyi-system*.jar" | head -n 5
jar tf <对应的jar包路径> | grep -i SysConfigMapper

文件层面确认完毕后，再检查配置。如果是若依项目，搜 application*.yml 里的 mapperLocations，把它和 XML 实际目录放在一起做对比。这三步走完，80% 的问题都能浮出水面。

5.2 用一张自检表覆盖所有成因

我把排查路径整理成了一张速查表，工作中遇到同类异常可以直接对照。这张表覆盖了从开发环境到打包交付的各个阶段：

这张表在团队内部可以作为 review 的参考清单，特别是新增 Mapper 方法之后，最值得花 30 秒做一次接口与 XML 的对应关系检查。

5.3 一个防止问题再次发生的“笨办法”

最后说一个我从实际项目里总结出来的小习惯。每次提交代码前，我会先跑一遍 Maven 构建，然后搜一遍 target 目录下的 XML，确认编译产物里包含了新增的 XML 文件。这个动作很机械，但能提前挡住一大半“本地能跑、部署后挂了”的惨剧。

另一个更推荐的做法是，在团队的 CI 流程里加一步简单的断言脚本，扫描源码中的 Mapper 接口和 XML 标签的差值。只要发现某个接口方法没有对应的 XML statement，就立刻让流水线失败。虽然这个脚本需要一点点额外工作量，但对团队长期维护一个模块不断增多的 Spring Boot 项目来说非常值得。

像 SysConfigMapper.selectConfigList 这种报错，等我经历过几次以后，反而把它当成一次“体检信号”——它往往不只是某个 XML 放错位置，而是提醒我检查构建流程、资源过滤和多模块依赖管理是否健康。按照上面的顺序逐项排查，问题基本不会在同一个地方绊倒你第二次。