MyBatis映射文件 ＜resultMap＞ 元素详解与示例

---

引言

<resultMap> 是 MyBatis 中最核心的映射配置元素，用于解决数据库字段与 Java 对象属性之间的复杂映射问题，尤其是字段名不一致、嵌套对象关联、集合映射等场景。ResultMap 的设计思想是，对简单的语句做到零配置，对于复杂一点的语句，只需要描述语句之间的关系就行了。以下是 <resultMap> 的详细解析和用法说明。

---

一、<resultMap> 基础结构

1. 核心属性

• id：唯一标识符，用于其他操作引用此映射。
• type：映射的目标 Java 对象类型（全限定类名或别名）。
• autoMapping：是否启用自动映射（默认 false，建议部分场景开启）。
  

2. 基础示例

场景：数据库字段为 user_id，Java 对象属性为 userId。

<!-- 
用户结果映射（基础版本）
功能：将数据库查询结果映射到com.example.User对象
说明：1. id="BaseUserMap"：标识这个结果映射的唯一名称。2. type="com.example.User"：指定目标Java对象的完整类路径。3. <id property="userId" column="user_id">：定义主键属性userId与数据库列user_id的映射关系。4. <result property="userName" column="user_name">：定义普通属性userName与数据库列user_name的映射关系。5. <result property="age" column="age">：定义普通属性age与数据库列age的映射关系。
用法：在需要复杂映射的场景下，可复用此结果映射。-->
<resultMap id="BaseUserMap" type="com.example.User"><id property="userId" column="user_id" /><result property="userName" column="user_name" /><result property="age" column="age" />
</resultMap><!-- 
查询用户基本信息
功能：从users表中查询user_id、user_name和age列，并使用BaseUserMap结果映射转换为Java对象
说明：1. id="getUser"：标识这个查询操作的唯一名称。2. resultMap="BaseUserMap"：指定使用BaseUserMap结果映射来处理查询结果。3. SELECT user_id, user_name, age FROM users：从users表中查询指定列。
用法：在Mapper接口中定义对应的方法，例如：User getUser();返回一个包含用户基本信息的User对象。-->
<select id="getUser" resultMap="BaseUserMap">SELECT user_id, user_name, age FROM users
</select>

---

二、字段映射详解

1. <id> 与 <result> 的区别

• <id>：标记主键字段，影响缓存和性能优化（必须配置）。
• <result>：普通字段映射。
  

2. 显式映射 vs 自动映射

• 显式映射：手动配置所有字段（推荐复杂场景）。
• 自动映射：开启 autoMapping="true" 后，未配置的字段按名称自动映射。

<!-- 
自动映射主键的用户结果映射
功能：使用MyBatis的自动映射功能，将数据库查询结果映射到User对象
特别说明：1. autoMapping="true"：表示开启MyBatis的自动映射功能。- MyBatis会自动将查询结果中与User对象属性名匹配的列映射到对应的属性上。2. <id property="userId" column="user_id">：手动配置主键映射，确保主键列与User对象的userId属性正确对应。- 通常主键列需要显式定义，其他非主键列可以依赖自动映射完成。-->
<resultMap id="AutoUserMap" type="User" autoMapping="true"><id property="userId" column="user_id" /> <!-- 只需配置主键 -->
</resultMap><!-- 
查询用户信息（使用自动映射）
功能：从users表中查询所有用户信息，并通过AutoUserMap结果映射转换为User对象。
特别说明：- 该查询语句只需简单地从表中选择所有列（SELECT *），因为开启了自动映射，MyBatis会自动处理列名与User对象属性的映射。- 如果某些列名与User对象属性名不一致，可以手动在resultMap中配置对应的映射关系。-->
<select id="getUser" parameterType="String" resultMap="AutoUserMap">SELECT * FROM users
</select>

---

三、关联关系映射

1. 一对一关联 <association>

场景：用户（User）与身份证（IDCard）一对一关联。
Java 对象：

public class User {private Integer userId;private String userName;private IDCard idCard; // 一对一对象
}

映射配置：

<!-- 
用户与身份证信息的结果映射
功能：将用户信息和其关联的身份证信息映射到User对象
说明：1. id="UserWithIDCardMap"：标识这个结果映射的唯一名称。2. type="User"：指定目标Java对象类型为User。3. <id property="userId" column="user_id">：定义User对象的userId属性与数据库表的user_id列对应，作为主键。4. <result property="userName" column="user_name">：定义User对象的userName属性与数据库表的user_name列对应。5. <association property="idCard" javaType="IDCard">- property="idCard"：User对象中的idCard属性，表示用户的身份证信息。- javaType="IDCard"：指定关联对象的Java类型为IDCard。- <id property="cardId" column="card_id">：定义IDCard对象的cardId属性与数据库表的card_id列对应，作为主键。- <result property="cardNumber" column="card_number">：定义IDCard对象的cardNumber属性与数据库表的card_number列对应。- 通过这个关联映射，可以将用户的身份证信息嵌套到User对象中。-->
<resultMap id="UserWithIDCardMap" type="User"><id property="userId" column="user_id"/><result property="userName" column="user_name"/><!-- 嵌套对象映射 --><association property="idCard" javaType="IDCard"><id property="cardId" column="card_id"/><result property="cardNumber" column="card_number"/></association>
</resultMap><!-- 
查询用户及其身份证信息
功能：从users和id_card表中查询用户及身份证数据，并通过UserWithIDCardMap结果映射转换为Java对象
说明：1. id="getUserWithIDCard"：标识这个查询操作的唯一名称。2. resultMap="UserWithIDCardMap"：指定使用UserWithIDCardMap结果映射来处理查询结果。3. SELECT u.user_id, u.user_name, c.card_id, c.card_number FROM users u LEFT JOIN id_card c ON u.user_id = c.user_id：- 查询users表和id_card表的联合数据。- LEFT JOIN将users表和id_card表连接，连接条件为用户ID（u.user_id = c.user_id）。- 查询结果将包含用户的基本信息和其关联的身份证信息。
用法：在Mapper接口中定义对应的方法，例如：User getUserWithIDCard();返回一个包含用户及其身份证信息的User对象。-->
<select id="getUserWithIDCard" resultMap="UserWithIDCardMap">SELECT u.user_id, u.user_name, c.card_id, c.card_numberFROM users uLEFT JOIN id_card c ON u.user_id = c.user_id
</select>

---

2. 一对多关联 <collection>

场景：用户（User）与订单（Order）一对多关联。
Java 对象：

public class User {private Integer userId;private String userName;private List<Order> orders; // 一对多集合
}

映射配置：

<!-- 
用户与订单的结果映射
功能：将用户信息及其关联的订单信息映射到User对象
说明：1. id="UserWithOrdersMap"：标识这个结果映射的唯一名称。2. type="User"：指定目标Java对象类型为User。3. <id property="userId" column="user_id">：定义User对象的userId属性与数据库表的user_id列对应，作为主键。4. <result property="userName" column="user_name">：定义User对象的userName属性与数据库表的user_name列对应。5. <collection property="orders" ofType="Order">- property="orders"：User对象中的orders属性，表示用户的订单集合。- ofType="Order"：指定集合中元素的类型为Order。- <id property="orderId" column="order_id">：定义Order对象的orderId属性与数据库表的order_id列对应，作为主键。- <result property="orderNo" column="order_no">：定义Order对象的orderNo属性与数据库表的order_no列对应。- <result property="amount" column="amount">：定义Order对象的amount属性与数据库表的amount列对应。- 通过这个集合映射，可以将用户的订单信息作为嵌套集合封装到User对象中。-->
<resultMap id="UserWithOrdersMap" type="User"><id property="userId" column="user_id"/><result property="userName" column="user_name"/><!-- 集合映射 --><collection property="orders" ofType="Order"><id property="orderId" column="order_id"/><result property="orderNo" column="order_no"/><result property="amount" column="amount"/></collection>
</resultMap><!-- 
查询用户及其订单信息
功能：从users和orders表中查询用户及订单数据，并通过UserWithOrdersMap结果映射转换为Java对象
说明：1. id="getUserWithOrders"：标识这个查询操作的唯一名称。2. resultMap="UserWithOrdersMap"：指定使用UserWithOrdersMap结果映射来处理查询结果。3. SELECT u.user_id, u.user_name, o.order_id, o.order_no, o.amount FROM users u LEFT JOIN orders o ON u.user_id = o.user_id：- 查询users表和orders表的联合数据。- LEFT JOIN将users表和orders表连接，连接条件为用户ID（u.user_id = o.user_id）。- 查询结果将包含用户的基本信息和其关联的订单信息。
用法：在Mapper接口中定义对应的方法，例如：User getUserWithOrders();返回一个包含用户及其订单信息的User对象。-->
<select id="getUserWithOrders" resultMap="UserWithOrdersMap">SELECT u.user_id, u.user_name,o.order_id, o.order_no, o.amountFROM users uLEFT JOIN orders o ON u.user_id = o.user_id
</select>

---

四、高级用法

1. 继承映射 (extends)

复用已有的 resultMap，避免重复配置。

<!-- 
基础用户结果映射
功能：定义了一个基础的结果映射，包含用户的基本字段（user_id 和 user_name）
说明：1. id="BaseUserMap"：标识这个结果映射的唯一名称。2. type="User"：指定目标Java对象类型为User。3. <id property="userId" column="user_id">：定义User对象的userId属性与数据库表的user_id列对应，作为主键。4. <result property="userName" column="user_name">：定义User对象的userName属性与数据库表的user_name列对应。5. 这个基础映射可以被其他映射继承和扩展，避免重复定义公共字段。-->
<resultMap id="BaseUserMap" type="User"><id property="userId" column="user_id"/><result property="userName" column="user_name"/>
</resultMap><!-- 
扩展基础用户结果映射，添加新字段
功能：在基础用户映射的基础上，添加一个新的字段（email）
说明：1. id="ExtendedUserMap"：标识这个结果映射的唯一名称。2. extends="BaseUserMap"：表示继承BaseUserMap中的所有字段和配置。3. type="User"：指定目标Java对象类型为User。4. <result property="email" column="email">：新增字段，定义User对象的email属性与数据库表的email列对应。5. 通过继承基础映射，可以避免重复定义公共字段，简化配置。-->
<resultMap id="ExtendedUserMap" extends="BaseUserMap" type="User"><result property="email" column="email"/>
</resultMap>

---

2. 构造函数映射 <constructor>

通过构造方法注入字段（适合不可变对象）。
Java 对象：

public class User {private final Integer userId;private final String userName;public User(Integer userId, String userName) {this.userId = userId;this.userName = userName;}
}

映射配置：

<!-- 
用户结果映射（基于构造函数）
功能：将数据库查询结果通过构造函数映射到User对象
说明：1. id="UserConstructorMap"：标识这个结果映射的唯一名称。2. type="User"：指定目标Java对象类型为User。3. <constructor>：表示将通过User类的构造函数来初始化对象。4. <arg column="user_id" javaType="int">：- 定义构造函数的第一个参数，对应数据库列user_id，Java类型为int。5. <arg column="user_name" javaType="String">：- 定义构造函数的第二个参数，对应数据库列user_name，Java类型为String。6. 这个结果映射要求User类有一个接受两个参数（int user_id, String user_name）的构造函数。
用法：在需要使用构造函数映射的场景下，通过这个resultMap将查询结果转换为User对象。-->
<resultMap id="UserConstructorMap" type="User"><constructor><arg column="user_id" javaType="int"/><arg column="user_name" javaType="String"/></constructor>
</resultMap>

---

3. 嵌套查询（分步查询）

解决关联查询的 N+1 性能问题，通过分步加载数据。

<!-- 
用户与订单的延迟加载映射 先查用户，再通过 user_id 查订单
功能：定义了一个结果映射，用于将用户信息和其关联的订单信息进行映射。在查询用户时，不会立即加载订单信息，而是通过延迟加载的方式在需要时再加载。
说明：1. id="UserWithLazyOrdersMap"：标识这个结果映射的唯一名称。2. type="User"：指定目标Java对象类型为User。3. <id property="userId" column="user_id">：定义User对象的userId属性与数据库表的user_id列对应，作为主键。4. <result property="userName" column="user_name">：定义User对象的userName属性与数据库表的user_name列对应。5. <collection property="orders" ofType="Order" select="com.example.OrderMapper.getOrdersByUserId" column="user_id">- property="orders"：User对象中的orders属性，表示用户关联的订单集合。- ofType="Order"：指定集合中元素的类型为Order。- select="com.example.OrderMapper.getOrdersByUserId"：指定一个单独的SQL查询语句，用于根据用户ID查询订单信息。- column="user_id"：将查询结果中的user_id列作为参数传递给子查询。-->
<resultMap id="UserWithLazyOrdersMap" type="User"><id property="userId" column="user_id"/><result property="userName" column="user_name"/><collection property="orders" ofType="Order"select="com.example.OrderMapper.getOrdersByUserId"column="user_id"/> <!-- 将 user_id 作为参数传递给子查询 -->
</resultMap><!-- 
查询用户信息（延迟加载订单）
功能：根据用户ID查询用户的基本信息，并通过延迟加载的方式获取其关联的订单信息。
说明：1. id="getUser"：标识这个查询操作的唯一名称。2. resultMap="UserWithLazyOrdersMap"：指定使用UserWithLazyOrdersMap结果映射来处理查询结果。3. SELECT user_id, user_name FROM users WHERE user_id = #{id}：- 查询users表中的user_id和user_name列。- WHERE user_id = #{id}：根据传入的用户ID进行查询。
用法：在Mapper接口中定义对应的方法，例如：User getUser(int id);返回一个包含用户基本信息的User对象，其orders属性在需要时才会加载。-->
<select id="getUser" resultMap="UserWithLazyOrdersMap">SELECT user_id, user_name FROM users WHERE user_id = #{id}
</select>

OrderMapper.xml：

<!-- 
根据用户ID查询订单信息
功能：从orders表中查询指定用户的所有订单
参数：userId（用户ID）
返回：Order对象的列表，包含该用户的所有订单信息
说明：1. id="getOrdersByUserId"：标识这个查询操作的唯一名称。2. resultType="Order"：指定查询结果的类型为Order对象。3. SELECT * FROM orders WHERE user_id = #{userId}：- 查询orders表中所有列的数据。- WHERE user_id = #{userId}：条件是订单的user_id等于传入的userId参数。
用法：在Mapper接口中定义对应的方法，例如：List<Order> getOrdersByUserId(int userId);调用时传入用户ID，返回该用户的所有订单信息。-->
<select id="getOrdersByUserId" resultType="Order">SELECT * FROM orders WHERE user_id = #{userId}
</select>

---

五、常见问题与最佳实践

1. 主键必须配置：<id> 影响缓存机制，未配置可能导致性能下降。
2. 避免过度嵌套：复杂关联建议使用分步查询（嵌套查询）减少单次 SQL 复杂度。
3. 自动映射的取舍：简单场景可开启 autoMapping，复杂字段仍需显式配置。
4. 性能优化：一对多关联使用懒加载（fetchType="lazy"），按需加载数据。

---

六、总结

拓展阅读：MyBatis映射文件常用元素详解与示例
官方文档：MyBatis | XML 映射文件