17370845950

XML Mapper 是 MyBatis 中定义 SQL 映射关系的 XML 文件，用于解耦 Java 接口方法与 SQL 语句，需满足命名、路径约定并显式配置才能被正确加载。

XML Mapper 是什么

XML Mapper 是 MyBatis 中用于定义 SQL 映射关系的 XML 文件，它把 Java 接口方法和 SQL 语句解耦，让 SQL 集中管理、便于维护。它不是运行时生成的代理类，也不是注解替代品——而是 MyBatis 加载 Mapper 接口时，按命名约定查找并绑定的外部 SQL 定义载体。

如何让 MyBatis 找到并加载 XML Mapper 文件

MyBatis 不会自动扫描任意路径下的 XML 文件，必须满足命名与路径双重约定：

• XML 文件名必须和对应 Mapper 接口类名一致（如 UserMapper.java → UserMapper.xml）
• XML 文件必须放在与接口相同的包路径下（如 com.example.mapper.UserMapper 对应 resources/com/example/mapper/UserMapper.xml）
• 在 mybatis-config.xml 或 Spring Boot 的 application.yml 中显式配置 mapper 路径（Spring Boot 默认扫描 mapper-locations: classpath*:mapper/**/*.xml，但若改过包结构或用了非标准路径，就得手动配）

常见错误：IDE 编译后 .xml 没进 target/classes —— 检查 pom.xml 是否漏了 resources 配置，Maven 默认不复制非 *.java 文件到输出目录。

XML Mapper 中写 SQL 的基本结构

每个 UserMapper.xml 必须有 根标签，并通过 namespace 绑定接口全限定名。SQL 语句用 、 等标签包裹，id 必须和接口方法名一致。

  
    SELECT * FROM user WHERE id = #{id}
  

注意点：

• #{id} 是预编译参数占位符，防 SQL 注入；${id} 是字符串拼接，仅用于动态表名/列名等极少数场景
• resultType 和 resultMap 二选一：resultType 适用于字段名与 POJO 属性名完全匹配；复杂映射（如字段别名、嵌套对象、类型转换）必须用
• MyBatis 3.4+ 支持在 XML 中使用 或 OGNL 表达式做简单逻辑，但别写业务逻辑——XML 只管 SQL 结构，不该承担判断职责

为什么有时 XML Mapper 没生效？几个典型卡点

不是语法错，而是绑定失败或加载遗漏，最常发生在以下环节：

• 接口方法有重载（如两个 findById），XML 中 id 冲突 → MyBatis 只认名字，不看参数，直接报 BindingException: Invalid bound statement
• XML 文件编码不是 UTF-8，含中文注释或字段名时乱码 → 导致解析失败，日志里可能只报 “Error parsing SQL Mapper” 无明细
• 用了 @MapperScan 但没扫到 XML 所在包，或用了 @Mapper 注解在接口上却忘

  

  了加 @MapperScan（后者仅对当前接口有效，不递归子包）
• Spring Boot + MyBatis-Plus 混用时，MP 默认禁用 XML（mybatis-plus.configuration.map-underscore-to-camel-case=false 不影响 XML，但 MP 的自动扫描可能绕过 XML）→ 查 MybatisConfiguration 日志确认是否加载了该 XML

调试建议：启动时加 logging.level.org.apache.ibatis=DEBUG，看日志里有没有 MapperRegistry.addMapper 和 XMLMapperBuilder.parse 成功记录。