MyBatis：对不起，这锅我不能背（给年轻的程序员上一课呀）

关注

原创最新推荐文章于 2026-03-31 04:39:21 发布 341 阅读 AI 写同款· GEO 优化 ›

Ubuntu22.04 上ROS1 Noetic的安装与常见问题解决本文详细介绍了在Ubuntu 22.04系统上安装ROS1 Noetic的两种主要方法：推荐使用社区维护的适配仓库进行便捷安装，并提供了从源码编译的备选方案。文章重点解决了安装后编译ROS包时极易遇到的“shared_mutex”等C++标准库冲突问题，并给出了其他常见错误的排查与解决指南，帮助开发者顺利搭建稳定的ROS开发环境。阅读详情

前文

写代码多年，我一直有个习惯，只要是要做的功能模块不是很复杂，一般都是上来狂写一通代码，等功能做好了，再启动服务测试，哪里有问题再改（实话说，单元测试写的也不多）。

而不是写完一个接口或方法就测试一下，最长的记录应该是连着写4、5天代码，然后一把测试通过，那感觉，爽到可以多吃一碗饭。

代码路上的滑铁卢

然而，就在前两天，我感觉遭遇到了代码人生的滑铁卢，其实遇到过不只一次了，每次滑完铁，再爬起来慢慢就忘了。这次，我把它写下来，这样就不会忘了。

事情是这样的，前两天要对项目加个功能。项目 ORM 采用的是 MyBatis，因为增加了数据库表，所以要对应的生成 DAO 层和 MyBatis 映射文件(mapper.xml)。由于对之前业务不是熟悉，我只是先把各个实体类啊、业务类啊、映射文件啊、枚举类啊等等都建出来，然后写了两个简单接口准备调试一下，于是我点了启动按钮，没问题，没有一点错误，项目正常启动了，看上去是那么的完美。

我构造了一个请求，打算测一下刚刚写好的接口，当请求发送出去之后，一个熟悉的异常出现在了 IDEA 控制台中，invalid bound statement (not found)，用过 MyBatis 的同学恐怕没有不认识这个异常的，它的意思就是我们调用 DAO 方法的时候，在 mapper.xml 文件中没有找到对应的 statement，或者说是没有找到你定义的 SQL 查询语句块。

出现这个异常可能是下面的这几个原因：

xml 文件的 namespace 和对应的接口名不一致
接口类中的方法和 xml 文件中的 statement id 对应不上
xml 文件中有中文注释
随意在 xml 文件中加一个空格或者空行然后保存，可能能解决问题

如果你是用工具自动生成 xml 还好，如果是手动创建的，那很可能由于疏忽出现这个问题，比如我们从另一个文件复制过来，忘记改 namespace 了，或者接口方法名和 statement id 差了一个字母或者字母顺序不一致。这个异常是很令人头疼的，就比如相差一个字母这种情况，很难被发现，所以最好还是写好接口方法名，然后复制到 xml 中。

我虽然有段时间没有碰 MyBatis 了，作为一个老司机，我碰到这个问题其实一点也不慌，因为虽然是工具自动生成的 xml 文件，但是我确实又加了几个 statement 块儿，而且 id 也是手敲的，并且报错的确实也是我手动加上的，所以，我猜测应该是名字没对上，敲错字母或者顺序不一致，于是我进去排查了一下，但是没发现什么问题，为了保险起见，我又到接口中把方法名字复制到 xml 中了，然后确定 namespace 没问题，没有中文注释，并且又在 xml 中加了个空行(虽然从来没用这个方法解决过问题)，然后重新启动项目，但是，异常还是没有消失。

及时跳出来，不要陷在里面

这就有点奇怪了，又重新检查了一遍，没错，都正常，看不出问题所在。

**当确定没有问题的时候，就要跳出来了，得从其他方向或者更高层次考虑一下了，不然很可能就陷在里面了。

**划重点，这是多次教训总结出来的规律。我可以确定当前调用的这个接口方法和 statement 都完全没有问题，那很有可能是别的问题，会不会是这个 xml 文件没有被编译打包进去，于是我进到 target 目录查探一番，有的，而且查看内容，确定是没有问题的。

有时候问题很奇怪，可能和 IDE 有关，于是我用 mvn clean 命令清理了一下，然后重新运行，但是，问题依旧在。

接下来，我又试了删除这个 xml ，然后新建了一个，但是，问题依旧。

再往外跳，你不是这个方法有问题吗，那我再新建一个方法，就写一条最简单的 SQL，方法名也起的简单一点，看看会不会有问题，结果，发现新大陆了，这个新建的方法也报这个错误。那就有了新的排查方向了，我再试试别的接口中的方法呢，结果，这个包名下的几个方法，全都有这个错误，而其他包名下的方法则没有问题，因为不同功能的 xml 文件放在不同的包下，也就是不同的路径下。

那我就知道了，是 xml 文件扫描出问题了，肯定是 MyBatis 配置的 mapperLocations 有问题了，有可能是被我或者其他同事不小心多敲了个字母之类的。于是打开配置文件看了一下，

mybatis:
mapperLocations: com/xxx/aaa/mapper/*.xml,com/xxx/aaa/bbb/mapper/*.xml,com/xxx/aaa/ccc/mapper/*.xml

MyBatis 配置 mapperLocations 配置了三个包路径，也就是从这三个包中寻找 *.xml去解析，但是经过检查发现，并没有问题，配置文件没有 git 提交记录，而且配置的包路径也是正确无误的，其他两个包都扫描正常，就是 com/xxx/aaa/ccc/mapper/*.xml这个包有问题。于是我又试了如下几个方法：

把这个有问题的包路径放到第一个，无效。
把其他两个注释，只留这个有问题的，无效。
难道是 MyBatis 读取了其他地方的配置？于是我把这个配置注释掉，结果都出问题了，说明就是读的这个配置。

源码大法好

此时，已经过去很长时间了，问题变得越来越诡异，但是事出必有因，肯定是某些地方出现了问题。实在找不出项目本身的问题了，没办法，我只能怀疑是 MyBatis 有问题了，也许真的是触发了 MyBatis 本身的隐藏 bug。

不到万不得已是不会用这种方式的，那就是调试 MyBatis 源码。想来，MyBatis 源码我还是比较熟悉的。那咱们就再会一会吧。

mybatis-spring-boot-starter 只有三个 Java 文件，其中 MybatisAutoConfiguration是关键业务类。

MyBatis：对不起，这锅我不能背（给年轻的程序员上一课呀）

而我们知道 MyBatis 中 SqlSessionFactory 是非常核心的对象，所以我们就把断点加在 sqlSessionFactory(DataSource dataSource)这个方法上。

如果是第一次调试开源框架源码，往往不能一下子找准位置，其实没有关系，把断点打在任何一个位置都可以，大不了就慢慢跟两遍嘛，本身读源码、调试的过程就是个漫长的过程。

@Bean
@ConditionalOnMissingBean
public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
    SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
    factory.setDataSource(dataSource);
   // 省略...
    if (!ObjectUtils.isEmpty(this.properties.resolveMapperLocations())) {
      factory.setMapperLocations(this.properties.resolveMapperLocations());
    }
    return factory.getObject();
}

以上代码我只保留了本次问题相关的代码，那就是解析 mapperLocations 的过程，也就是上面代码中this.properties.resolveMapperLocations()这个方法。

public Resource[] resolveMapperLocations() {
    ResourcePatternResolver resourceResolver = new PathMatchingResourcePatternResolver();
    List<Resource> resources = new ArrayList<Resource>();
    if (this.mapperLocations != null) {
      for (String mapperLocation : this.mapperLocations) {
        try {
          Resource[] mappers = resourceResolver.getResources(mapperLocation);
          resources.addAll(Arrays.asList(mappers));
        } catch (IOException e) {
          // ignore
        }
      }
    }
    return resources.toArray(new Resource[resources.size()]);
}

当我继续跟踪代码的时候，发现 MyBatis 确实已经识别到了配置文件中的那三个包路径，this.mapperLocations就是那三个包路径的数组集合。

接着往下跟，在方法 resourceResolver.getResources(mapperLocation)中对每一个路径进行解析，发现前两个包都正常返回了Resource[]，也就是对应的 xml 文件资源，而最后一个返回的确实空数组，问题原因已经很近了。

接着再次启动调试，当解析最后一个包路径是，进入resourceResolver.getResources(mapperLocation)方法内部，看看里面都干了什么，最后发现在调用以下代码之后，返回的 rootDirURL 是一个绝对路径，也就是 xml 所在的物理路径。

URL rootDirURL = rootDirResource.getURL();

这时，终于发现问题所在了，这个绝对路径竟然不是 xml 所在的路径，而是另外一个子模块下的路径，经过对比发现，原来，子模块中被新建了一个名称一样的文件夹，造成存在两个完全一样的包路径，而以上代码返回了另一个包的绝对路径。于是，联系同事，问清楚这个包被创建的原因，发现是最近新加的但是已经废弃无用的，于是删掉解决了问题。