java mapper 映射 invalid bound statement not found

### 三级标题：问题分析 `Invalid bound statement (not found)` 是 MyBatis 或 MyBatisPlus 中常见的错误，表示无法找到对应的 Mapper 映射语句。这种问题通常与以下几方面有关： 1. **Mapper 接口与 XML 文件未正确绑定** Mapper 接口中定义的方法名必须与 XML 文件中 `<select>`, `<insert>`, `<update>`, `<delete>` 标签的 `id` 属性完全一致，包括大小写和拼写 [^4]。 2. **XML 文件路径配置不正确** 如果 Mapper XML 文件放置在 `resources` 目录下，则需要在配置文件（如 `application.yml` 或 `application.properties`）中指定正确的映射文件路径。例如： ```yaml mybatis: mapper-locations: classpath:/mapper/**/*.xml ``` 或者多个路径使用逗号分隔 [^4]。 3. **构建过程中 XML 文件未被正确打包到 target/classes 下** 在 Maven 项目中，如果 XML 文件没有放在 `src/main/resources` 路径下，而是放在了其他位置（如 `static` 目录），则不会被复制到编译输出目录中，导致运行时找不到文件 [^3]。应确保 XML 文件位于资源目录中，并且在 `pom.xml` 中配置资源过滤： ```xml <build> <resources> <resource> <directory>src/main/resources</directory> <includes> <include>**/*.xml</include> </includes> </resource> </resources> </build> ``` 4. **MyBatis 配置文件中缺少必要的组件注册** 如果使用了自定义类型处理器（TypeHandler），需要在 `mybatis-config.xml` 文件中注册该处理器，否则可能导致某些内置方法失效。示例配置如下： ```xml <configuration> <typeHandlers> <typeHandler handler="com.example.handler.JSONTypeHandler"/> </typeHandlers> </configuration> ``` 同时，在 Spring Boot 中还需要通过 `@MapperScan` 注解扫描 Mapper 接口所在的包 [^2]。 5. **Mapper 接口未被 Spring 管理或未正确注入** 检查是否为 Mapper 接口添加了 `@Mapper` 注解，或者是否在启动类上使用了 `@MapperScan` 来自动扫描所有 Mapper 接口 [^1]。 6. **模块依赖关系未正确配置** 在多模块项目中，新添加的模块可能没有正确引用包含 Mapper 的父模块或公共模块，导致运行时无法加载相关资源。检查 `pom.xml` 或 Gradle 构建文件中的依赖关系，确保模块间依赖配置正确 [^1]。 --- ### 三级标题：解决方案总结 以下是解决 `Invalid bound statement (not found)` 错误的关键步骤： 1. **确认接口方法与 XML 中的 id 一致** - 检查大小写、拼写是否完全匹配。 - 确保每个方法都有对应的 SQL 定义。 2. **检查 XML 文件路径并配置 mapper-locations** - 将 XML 文件放在 `resources/mapper/` 或类似结构化路径下。 - 在 `application.yml` 或 `application.properties` 中配置正确的路径： ```yaml mybatis: mapper-locations: classpath:/mapper/**/*Mapper.xml ``` 3. **确保 XML 文件被正确打包到 target/classes** - 避免将 XML 文件放在 `static` 等非资源目录。 - 配置 `pom.xml` 中的 `<resources>` 部分以确保 XML 文件被包含进构建流程 [^3]。 4. **注册自定义 TypeHandler（如有）** - 在 `mybatis-config.xml` 中添加 `<typeHandlers>` 配置。 - 确保不影响 MyBatis 自带方法的正常使用 [^2]。 5. **检查 Mapper 扫描配置** - 使用 `@Mapper` 注解单个接口或使用 `@MapperScan` 批量扫描接口。 - 确保启动类所在包能覆盖所有 Mapper 接口 [^1]。 6. **处理多模块项目的依赖问题** - 确认新模块已正确引入包含 Mapper 和 XML 文件的模块。 - 查看 `target` 输出目录中是否存在 `.xml` 文件 [^1]。 --- ### 三级标题：示例代码 #### 示例一：MyBatis 配置文件 `mybatis-config.xml` ```xml <configuration> <typeHandlers> <typeHandler handler="com.example.handler.JSONTypeHandler"/> </typeHandlers> </configuration> ``` #### 示例二：Spring Boot 应用主类 ```java @SpringBootApplication @MapperScan("com.example.mapper") public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } } ``` #### 示例三：Mapper 接口 ```java @Mapper public interface UserMapper { @Select("SELECT * FROM user WHERE id = #{id}") User selectById(Long id); } ``` #### 示例四：Mapper XML 文件 ```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 * FROM user WHERE id = #{id} </select> </mapper> ``` --- ###