MyBatis Mapper XML 文件需规范命名与路径、正确配置 namespace 和 id，合理使用 #{} 与 ${} 传参，显式定义 resultMap 处理结果映射，善用动态 SQL 标签提升灵活性与安全性。
MyBatis 的 Mapper XML 文件本质是把 SQL 语句从 Java 代码里抽出来，集中管理、方便维护。写对的关键不是堆语法，而是理清“谁映射谁”“参数怎么传”“结果怎么回”。下面直接说实用要点。
命名和位置要规范
XML 文件名必须和对应 Mapper 接口名一致（如 UserMapper.java 对应 UserMapper.xml），且放在相同包路径下（或通过 Invalid bound statement 错误。
- 推荐放在
resources/mapper/目录下，用 - namespace 必须写全限定名，即对应接口的完整类名（如
com.example.mapper.UserMapper） - 每个 SQL 语句用
、
参数传递：#{} 和 ${} 别乱用
#{} 是预编译占位符，防 SQL 注入，适用于大多数场景；${} 是字符串拼接，只在动态表名、列名、排序字段等无法预编译的地方才用，且必须确保输入安全。
- 单个参数：直接写
#{id}或#{username}（参数名来自方法形参或@Param注解） - 多个参数：必须用
@Param("xxx")注解命名，XML 中用#{xxx}引用 - 对象参数：用点号取属性，如
#{user.username}、#{user.createTime} - 动态列/表名示例：
ORDER BY ${orderByColumn}（注意校验该变量是否白名单）
结果映射：别总依赖自动映射
字段名和属性名不一致时，自动映射（mapUnderscoreToCamelCase=true）能解决部分问题，但复杂场景必须显式配置
- 简单一对一：用
- 关联查询：用
javaType/ofType和resultMap属性 - 避免写
SELECT *，明确列出字段，防止新增字段干扰映射或影响性能 - 字段别名要和 resultMap 中的 property 名一致，例如
SELECT user_id AS id, user_name AS username FROM user
动态 SQL：用对标签，少写硬编码
MyBatis 提供了
-
WHERE 1=1干净得多 -
-
collection（入参集合名）、item（当前元素别名）、open/close/separator的配合，例如 IN 查询：AND id IN#{id} - 多个条件组合优先用
基本上就这些。写 XML 不是炫技，目标是清晰、安全、易维护。每次加一个 SQL，先想清楚参数来源、结果结构、边界情况，再动手写标签——比后期调试省力得多。
