Mapper XML是MyBatis的核心配置文件之一，它承担着SQL语句定义、参数映射和结果映射这三项关键职责。相比直接使用JDBC编写代码，Mapper XML将数据访问逻辑集中放在独立的XML文件中，既能保持Java代码与SQL语句的分离，又具备动态SQL等灵活特性。但在实际项目中，不少开发者面对Mapper XML却容易犯难，不知道文件结构怎么搭，不清楚标签如何组合，更不理解为什么参数写法不同会带来截然不同的执行效果。理解Mapper XML的完整写法，从整体结构到细枝末节都梳理清楚，是写出可维护数据访问层的必要条件。
Mapper XML的基本结构与命名空间
一个标准的Mapper XML文件以XML声明开头，并指定对应的MyBatis DTD约束。根元素是<mapper>，它的namespace属性是文件的身份标识，必须与某个Mapper接口的全限定名保持一致。这样做的原因是MyBatis运行时通过namespace加语句id来定位一条SQL，例如namespace为com.demo.mapper.UserMapper，语句id为selectById，最终会用UserMapper.selectById这样的全限定key注册到配置中。接口中的方法之所以能和XML中的语句自动关联，靠的正是这套命名规则，接口方法名对应语句id，接口全限定名对应namespace。
在实际项目中，每个实体对象往往对应一个Mapper接口和一个同名XML文件，两者放在同一个包目录下，管理起来更清晰。一个最小化的XML配置文件结构大致如下：
<?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"> <!-- 具体的SQL语句写在这里 --> </mapper>
这里有一个容易忽略的细节：DOCTYPE中的DTD地址是一个URL，MyBatis在启动时会尝试从本地classpath中寻找对应的DTD文件，如果本地没有，才会通过网络去获取。在离线环境下，请务必确保mybatis的jar包中携带了DTD，否则会抛出解析异常。命名空间的唯一性也值得注意，如果多个XML文件使用了相同的namespace，MyBatis会在启动阶段直接抛出BindingException，错误信息中会明确指出重复映射的语句。这一点在团队协作时尤其容易发生，不同模块的mapper文件必须严格保证命名空间和语句id都不重复。
四类核心标签的详细写法
SQL映射中出场率最高的四类标签是<select>、<insert>、<update>和<delete>。每一个标签都对应接口中的一个方法，它们有公共的属性，也各有各的专属配置。以<select>为例，最常用的属性包括id、parameterType和resultType。id是语句的唯一标识，不能与同namespace下的其他id重复；parameterType描述传入参数的类型；resultType则指定返回结果映射到哪个Java对象。MyBatis的返回值处理有一个贴心之处：如果查询结果只有一行，返回的就是对象本身，如果有多行，MyBatis会自动把每条记录映射成一个对象并封装成List。因此接口方法返回List<User>时，XML中仍然写resultType为User即可，不需要额外声明List类型。
<insert>标签相比select多了一个常见的需求，就是获取数据库自动生成的主键。此时可以使用useGeneratedKeys属性配合keyProperty来完成。useGeneratedKeys设置为true后，MyBatis会通过JDBC的getGeneratedKeys方法取得自增主键值，并回填到传入参数对象的指定属性中。示例代码如下：
<insert id="insertUser" parameterType="com.example.entity.User" useGeneratedKeys="true" keyProperty="id">
insert into user (name, age, email)
values (#{name}, #{age}, #{email})
</insert>
执行完上述插入语句后，调用user.getId()拿到的就不再是null，而是数据库生成的自增主键。这个机制在MySQL和PostgreSQL中表现稳定，但在Oracle这类不支持自增主键的数据库中，就需要借助selectKey标签来提前查询序列值。selectKey的执行时机由order属性控制，BEFORE表示在insert语句之前执行并设置主键值，AFTER表示在insert之后执行。update和delete标签相对简单，它们的核心属性同样是id和parameterType，返回值统一是int类型，表示受影响的行数。接口方法的返回值可以写成int、long或者boolean，MyBatis都会自动适配，受影响行数大于0时boolean为true。
动态SQL的组装与场景分析
动态SQL是MyBatis最值得称道的特性之一，它在XML中允许使用<if>、<choose>、<where>、<set>、<foreach>等标签来组合出灵活的SQL语句。不少开发者接触这些标签时会下意识地跟JSP中的标签库做类比，但实际上MyBatis的动态SQL标签是在解析SQL语句阶段就完成的文本拼接，其本质上更接近模板引擎的工作方式。以<if>为例，它有一个必填属性test，test中写OGNL表达式，表达式的计算结果决定标签体内容是否拼接到最终SQL中。常见的写法是按条件追加查询条件：
<select id="selectByCondition" parameterType="com.example.query.UserQuery" resultType="com.example.entity.User">
select * from user
where 1 = 1
<if test="name != null and name != ''">
and name = #{name}
</if>
<if test="age != null">
and age >= #{age}
</if>
</select>
在这个例子中，where 1 = 1 是一种常见的处理技巧，它的目的是让后续的and条件可以无条件地拼接，而不用去判断当前是否是第一条条件。这种写法虽然简单直观，但拼接出来的SQL在语义上不够优雅。更推荐使用<where>标签来替代where关键字，<where>会自动识别内部是否有条件成立，只有存在条件时才输出where，并且会自动去掉第一个条件前面的and或者or。上面的代码用<where>改写后会更简洁：
<select id="selectByCondition" parameterType="com.example.query.UserQuery" resultType="com.example.entity.User">
select * from user
<where>
<if test="name != null and name != ''">
and name = #{name}
</if>
<if test="age != null">
and age >= #{age}
</if>
</where>
</select>
<set>标签的应用场景主要集中在update语句中，用于动态更新非空字段。它同样具备智能处理能力：如果内部有内容，会输出set关键字，并自动去掉最后一个逗号。结合<if>标签后，可以避免把整条记录的所有字段都更新一遍，只更新需要变化的字段。这个做法在数据权限比较严格的系统中很有价值，例如用户资料只允许修改部分字段时，通过<set>动态拼装就能防止穷举传参覆盖掉不允许修改的字段。<foreach>则用于处理in集合查询和批量插入的常见场景，它的collection属性接收一个集合或数组，item定义循环变量名，open和close定义前缀后缀，separator定义元素间的分隔符。需要注意的是，如果接口方法接收的是List参数，而不是使用@Param注解命名的参数，collection属性必须写成list，数组则写成array，这是新手最容易遗漏的地方。
参数绑定与结果映射的细节
在Mapper XML中写参数时，最常见的两种占位方式是#{}和${}。这两者的差别绝不仅仅是写法不同，其底层处理逻辑完全不同。#{}在SQL预编译阶段被解析为JDBC的占位符?，参数值通过setObject方法安全绑定，整个过程不需要对拼接到SQL中的值做任何文本处理。因此它能有效防止SQL注入。而${}则是直接将参数值作为字符串拼接到SQL语句中，如果参数值来自用户输入，就会带来严重的安全风险。在实际开发中，#{}几乎可以应用于所有传值场景。那${}用在什么地方呢？最常见的是动态传入表名、列名或者排序字段，因为这些数据库对象名不能被预编译占位符替代，必须直接拼接到SQL文本中。如果这些数据库对象名也来自外部输入，那么必须加白名单校验，绝不能直接把用户输入拼进去。
关于单参数传递，还有一个容易困扰新手的问题：当接口方法只有一个参数时，XML中parameterType可以省略，同时#{}里面的名称可以随意写，比如方法签名是一个String类型的name，那么XML中可以写#{value}，也可以写#{name}，MyBatis都不会报错。在MyBatis 3.4.2及以上版本中，参数名解析变得更智能，即使不写@Param注解，也可以通过参数名字直接引用。但如果方法有多个参数且没有使用@Param注解，则只能通过arg0、arg1或param1、param2这样的名称来访问，从代码可读性角度看，建议方法参数统一加上@Param注解声明，这样XML中引用的名字就与注解一一对应，语义清晰，也能避免编译期参数名丢失带来的坑。
结果映射方面，resultType适合数据库列名与Java对象属性名能够直接对应的情况，MyBatis默认会做简单的驼峰转换，前提是mybatis-config.xml配置了mapUnderscoreToCamelCase为true。如果两者列名差异较大，比如数据库使用company_id而Java属性是companyId，开启驼峰转换后就无需额外处理。当遇到多表联合查询、聚合字段、复杂嵌套对象时，resultType就显得力不从心，此时需要使用resultMap来定义更精确的映射规则。resultMap中主键列用<id>子标签描述，普通列用<result>子标签描述，column对应数据库列名，property对应Java属性名。resultMap还支持通过association标签一对一类比，collection标签一对多集合映射，这是构建复杂报表查询时常用的方式。在使用association时要注意嵌套查询的N+1问题，如果每查一条记录又触发一次子查询，数据量稍大就可能造成严重的性能瓶颈，可以考虑改用联表查询一次性查出来。
常见错误与避坑技巧
XML映射文件在运行时出现的错误通常比Java代码错误更隐蔽，原因在于错误信息发生在MyBatis初始化或SQL执行阶段，堆栈信息不够直观。围绕这些容易踩中的坑，可以总结出几条实用的规避思路。第一，XML中出现了小于号<、大于号>这样的字符时，必须使用转义形式，因为这个字符在XML解析阶段就会被当作标签边界处理。例如age > 18必须写成age > 18，age < 18要写成age < 18。为了增强可读性，更推荐将比较逻辑反过来写，比如18 < age。如需映射between条件，可以直接使用BETWEEN关键字，同样能避开转义问题。如果SQL中有大量这样的字符，可以使用<![CDATA[ ... ]]>片段包裹SQL，CDATA范围内的文本不做XML解析，可以把比较运算符直接写出来，但要注意CDATA内部不能再嵌套动态SQL标签，因为标签在这种情况下不会被解析。
第二，resultType和resultMap混用时经常出错。两者只能选其一，不能同时设置。如果方法返回的是一个Map类型，那么resultType直接写map即可，MyBatis会返回以列名为键、列值为值的Map对象，需要注意不同数据库列名大小写返回的行为并不一致，MySQL默认不区分大小写，而Oracle返回的列名通常是大写。如果希望使用resultMap却忘记在XML中定义对应的resultMap，启动时会直接抛出IllegalArgumentException，提醒resultMap不存在。第三，参数类型为集合或者数组的时候要注意参数名的解析方式，详情在前文foreach部分已有说明。第四，MyBatis缓存导致数据不实时的问题在开发环境中经常出现，明明数据库数据已变更，但查询结果没有变，此时可以检查Mapper对应的XML中是否配置了<cache/>标签，开发阶段可以先关闭缓存避免困惑。第五，在Windows开发环境下，项目配置文件中如果是硬编码方式指定mapper文件路径，务必使用反斜杠形式，例如C:\workspace\mybatis-demo\src\main\resources\mapper\UserMapper.xml，同时检查资源目录是否被正确打包进classes目录，最常见的错误是mapper文件漏打包，导致运行时报Invalid bound statement not found。
最后补充一个关于自动映射和部分字段为空的细节。当resultType返回对象时，如果查询出来的个别字段为null，MyBatis默认不会赋值，对象中的该属性保持Java对象的默认值。如果业务上需要区分空值和默认值，比如需要把null传递给前端，那么需要设置mybatis-config.xml中的callSettersOnNulls为true。在MyBatis 3.5.0及以上版本中，这个参数默认值依然是false。调优配置后，null字段也会调用对应的setter方法，确保对象属性被明确定义为null。这个细节在对接前端展示时很关键，不少联调问题都源于此。掌握这些后，再配合仔细阅读MyBatis官方文档中关于XML映射的章节，便能够自如应对大多数企业级项目中的数据持久化需求。
MyBatisMapper XML映射文件修改时间：2026-08-24 19:06:35