【复盘问题-mybatis的mapper.xml文件映射不到】

Spring Boot 整合 MyBatis 时 Mapper.xml 映射不到的问题

常见原因分析

1. 文件路径问题
   Mapper.xml 文件未放置在正确目录下，Spring Boot 默认扫描 resources/mapper 或 resources/mybatis/mapper。若自定义路径，需在配置文件中明确指定。

2. 配置缺失或错误
   application.properties 或 application.yml 中未配置 MyBatis 的 mapper-locations 属性，或路径格式错误。例如：

   mybatis.mapper-locations=classpath:mapper/*.xml
   

3. 未启用 Mapper 扫描
   主启动类缺少 @MapperScan 注解，或注解的包路径未覆盖 Mapper 接口所在包。

4. 命名不规范
   Mapper.xml 文件名与 Mapper 接口名不一致，或 <mapper> 标签的 namespace 未正确指向接口全限定名。

5. 资源过滤问题
   Maven 或 Gradle 未将 XML 文件打包到最终产物中，需检查构建工具的资源配置。

---

解决方法

检查文件路径与配置
确保 Mapper.xml 文件位于 resources/mapper 目录，并在配置文件中添加：

mybatis:
  mapper-locations: classpath:mapper/*.xml

添加 Mapper 扫描注解
在主启动类上指定 Mapper 接口的包路径：

@MapperScan("com.example.mapper")
@SpringBootApplication
public class Application { ... }

验证 XML 与接口映射
检查 Mapper.xml 的 namespace 是否与接口全限定名一致，例如：

<mapper namespace="com.example.mapper.UserMapper">
    <select id="selectUser" resultType="User">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

配置 Maven 资源过滤
在 pom.xml 中确保 XML 文件被打包：

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*.xml</include>
            </includes>
        </resource>
    </resources>
</build>

---

举一反三：其他场景的排查思路

1. 多模块项目中的路径问题
   若 Mapper.xml 位于子模块，需确认路径是否为 classpath*:（多模块扫描）且子模块依赖已正确引入。

2. 动态数据源与多数据库映射
   使用多数据源时，需为每个数据源单独配置 SqlSessionFactory，并指定对应的 mapper-locations。

3. 注解与 XML 混合使用冲突
   避免同一方法既在 XML 中配置又在接口上用 @Select 注解，会导致映射冲突。

4. MyBatis-Plus 的兼容性问题
   若集成 MyBatis-Plus，需检查是否因默认配置覆盖了原生 MyBatis 的路径规则。

---

通用排查流程

1. 通过日志确认是否加载了目标 XML 文件（开启 debug 日志级别）。
2. 使用 IDE 的全局搜索功能检查 namespace 和 id 是否匹配。
3. 解压最终生成的 JAR 包，验证 XML 文件是否存在于预期路径。

遇到问题：
1.思考问题的原因
2.排查核心原因
3.查询问题的核心/直接原因