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 必须有 <mapper></mapper> 根标签，并通过 namespace 绑定接口全限定名。SQL 语句用 <select></select>、<insert></insert> 等标签包裹，id 必须和接口方法名一致。
<?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="findById" resultType="com.example.model.User">
SELECT * FROM user WHERE id = #{id}
</select>
</mapper>注意点：
-
#{id}是预编译参数占位符，防 SQL 注入；${id}是字符串拼接，仅用于动态表名/列名等极少数场景 -
resultType和resultMap二选一：resultType适用于字段名与 POJO 属性名完全匹配；复杂映射（如字段别名、嵌套对象、类型转换）必须用<resultmap></resultmap> - MyBatis 3.4+ 支持在 XML 中使用
<bind></bind>或 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 成功记录。
