Mybatis Mapper XML文件怎么写 Mybatis SQL映射文件编写指南

MyBatis Mapper XML 文件需规范命名与路径、正确配置 namespace 和 id，合理使用 #{} 与 ${} 传参，显式定义 resultMap 处理结果映射，善用动态 SQL 标签提升灵活性与安全性。

MyBatis 的 Mapper XML 文件本质是把 SQL 语句从 Java 代码里抽出来，集中管理、方便维护。写对的关键不是堆语法，而是理清“谁映射谁”“参数怎么传”“结果怎么回”。下面直接说实用要点。

命名和位置要规范

XML 文件名必须和对应 Mapper 接口名一致（如 UserMapper.java 对应 UserMapper.xml），且放在相同包路径下（或通过 显式注册）。否则 MyBatis 找不到映射关系，报 Invalid bound statement 错误。

• 推荐放在 resources/mapper/ 目录下，用 注册
• namespace 必须写全限定名，即对应接口的完整类名（如 com.example.mapper.UserMapper）
• 每个 SQL 语句用 、、、 标签包裹，id 值必须和接口方法名完全一致

参数传递：#{} 和 ${} 别乱用

#{} 是预编译占位符，防 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 提供了 、、、、 等标签，核心是让 SQL 更灵活，同时保持可读性。

• 会智能处理开头的 AND/OR，比手写 WHERE 1=1 干净得多
• 自动剔除末尾逗号，更新语句中推荐使用
• 遍历集合时，注意 collection（入参集合名）、item（当前元素别名）、open/close/separator 的配合，例如 IN 查询：AND id IN #{id}
• 多个条件组合优先用 （类似 switch），避免嵌套太多

基本上就这些。写 XML 不是炫技，目标是清晰、安全、易维护。每次加一个 SQL，先想清楚参数来源、结果结构、边界情况，再动手写标签——比后期调试省力得多。