MyBatis无法识别Mapper XML文件报Invalid bound statement (not found)问题求助

针对你遇到的MyBatis无法识别Mapper XML文件，但注解方式正常的问题，结合你的技术栈（最新Gradle、Java15、SpringBoot2.4.1），我整理了几个关键的排查和解决步骤：

1. 确保Gradle正确打包XML文件 #

Gradle默认不会将src/main/java目录下的XML文件打包到编译后的classpath中，这是最常见的原因。你需要在build.gradle中添加资源配置，让Gradle扫描并打包Java目录下的XML文件：

sourceSets {
    main {
        resources {
            srcDirs = ['src/main/java', 'src/main/resources']
            includes = ['**/*.xml']
        }
    }
}

或者你也可以将Mapper XML文件迁移到src/main/resources目录下，保持和Mapper接口相同的包结构（比如resources/nutri/api/infrastructure/datasource/client/ClientMapper.xml），这样Gradle会自动打包这些资源文件。

2. 配置MyBatis的Mapper扫描路径 #

在Spring Boot的配置文件（application.yml或application.properties）中，明确指定MyBatis要扫描的Mapper XML文件路径，确保路径和文件位置匹配：

YAML格式： #

mybatis:
  mapper-locations: classpath:nutri/api/infrastructure/datasource/client/*.xml
  # 或者使用通配符扫描所有Mapper XML：classpath*:**/*Mapper.xml

Properties格式： #

mybatis.mapper-locations=classpath:nutri/api/infrastructure/datasource/client/*.xml

3. 检查XML文件的Namespace和Statement ID #

• Namespace必须严格匹配Mapper接口的全类名：比如你的XML文件中namespace属性必须是nutri.api.infrastructure.datasource.client.ClientMapper，注意大小写和包路径的拼写，不能有任何错误。
• Statement ID必须和接口方法名完全一致：XML中select（或其他SQL标签）的id属性要和接口中的getClientById方法名完全相同，包括大小写。

4. 验证XML文件的语法正确性 #

检查XML文件是否存在语法错误，比如未闭合的标签、SQL语句拼写错误、参数占位符#{id}是否正确使用，以及resultType/resultMap是否正确配置（确保返回类型和接口方法的返回类型匹配）。

5. 验证打包结果 #

执行gradle build后，查看build/classes/java/main目录下对应的包路径（nutri/api/infrastructure/datasource/client）中是否存在ClientMapper.xml文件。如果不存在，说明Gradle打包配置有问题，回到第一步调整配置。

你提供的错误栈关键信息： #

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): nutri.api.infrastructure.datasource.client.ClientMapper.getClientById

这个错误明确指向MyBatis无法找到对应接口方法的XML映射配置，按照上面的步骤逐一排查，应该能解决问题。

内容的提问来源于stack exchange，提问作者Leo