MyBatis多表联查返回List仅一条数据？主键冲突BUG排查与解决

- 一、问题背景
- 二、问题复现
- - [2.1 业务场景](#2.1 业务场景)
  - [2.2 核心代码实现](#2.2 核心代码实现)
  - - [1. Mapper.xml查询SQL](#1. Mapper.xml查询SQL)
    - [2. ResultMap配置](#2. ResultMap配置)
    - [3. 异常结果](#3. 异常结果)
- 三、BUG根源分析
- - [3.1 核心问题：字段名冲突](#3.1 核心问题：字段名冲突)
  - [3.2 关键原理](#3.2 关键原理)
- 四、解决方案
- - [4.1 优化查询SQL（添加字段别名）](#4.1 优化查询SQL（添加字段别名）)
  - [4.2 修正ResultMap配置（映射别名列）](#4.2 修正ResultMap配置（映射别名列）)
  - [4.3 优化说明](#4.3 优化说明)
- 五、验证结果
- 六、避坑总结

一、问题背景

在项目开发中，多表联查是高频需求。近期在基于MyBatis实现"管理员-角色-权限"多表关联查询时，遇到了一个诡异的BUG：数据库执行SQL能返回多条正确结果，但项目中通过MyBatis映射后，List集合始终只显示一条数据。经过反复排查，最终定位到是主键字段命名冲突导致MyBatis数据映射异常，现将完整排查过程与解决方案分享如下。

二、问题复现

2.1 业务场景

需通过管理员ID查询该管理员的基本信息、关联的角色列表，以及每个角色对应的权限列表，涉及admin（管理员表）、role（角色表）、permission（权限表）三张核心表，通过中间表admin_role和role_permission实现关联。

2.2 核心代码实现

1. Mapper.xml查询SQL

sql 复制代码

SELECT
    a.id,
    a.username,
    r.id,
    r.role_name,
    r.role_desc,
    p.id,
    p.permission_name,
    p.url
FROM
    `admin` a
    LEFT JOIN admin_role ON a.id = admin_role.aid
    LEFT JOIN `role` r ON admin_role.rid = r.id
    LEFT JOIN role_permission ON r.id = role_permission.rid
    LEFT JOIN permission p ON role_permission.pid = p.id
WHERE
    a.id = #{aid}

直接在数据库执行该SQL，返回2条结果（对应2个权限），数据正常。

2. ResultMap配置

xml 复制代码

<resultMap id="adminMapper" type="com.lion.online.pojo.Admin">
    <id property="id" column="id"></id>
    <result property="username" column="username"></result>
    <!-- 角色列表关联 -->
    <collection property="roles" column="id" ofType="com.lion.online.pojo.Role">
        <id property="id" column="id"></id>
        <result property="roleName" column="role_name"></result>
        <result property="roleDesc" column="role_desc"></result>
        <!-- 权限列表关联 -->
        <collection property="permissions" column="id" ofType="com.lion.online.pojo.Permission">
            <id property="id" column="id"/>
            <result property="permissionName" column="permission_name"></result>
            <result property="url" column="url"></result>
        </collection>
    </collection>
</resultMap>

3. 异常结果

项目运行后，控制台打印SQL执行结果为2条，但页面仅显示1条权限数据，List集合长度异常为1。

三、BUG根源分析

3.1 核心问题：字段名冲突

MyBatis的ResultMap中，id标签用于标识实体类的主键字段，其column属性对应查询结果集中的列名（而非数据库表字段名）。本案例中：

管理员表、角色表、权限表的主键均命名为id
查询SQL未对多表中的id字段起别名，导致结果集中出现多个同名id列
MyBatis在映射数据时，无法区分主表（admin）、关联表（role、permission）的id字段，误将所有id列值当作主表主键处理，最终只保留了一条去重后的数据

3.2 关键原理

ResultMap的id标签具有"数据唯一标识"的作用，MyBatis会根据id字段的值判断是否为同一实体。当多表id字段同名且未区分时，MyBatis会认为所有关联数据属于同一个实体，从而覆盖重复数据，导致最终返回结果条数少于实际查询结果。

四、解决方案

核心思路：通过SQL别名区分多表中的同名id字段，在ResultMap中明确映射对应关系。

4.1 优化查询SQL（添加字段别名）

对角色表id起别名rid，权限表id起别名pid，避免列名冲突：

sql 复制代码

SELECT
    a.id,
    a.username,
    r.id AS rid,  -- 角色ID别名
    r.role_name,
    r.role_desc,
    p.id AS pid,  -- 权限ID别名
    p.permission_name,
    p.url
FROM
    `admin` a
    LEFT JOIN admin_role ON a.id = admin_role.aid
    LEFT JOIN `role` r ON admin_role.rid = r.id
    LEFT JOIN role_permission ON r.id = role_permission.rid
    LEFT JOIN permission p ON role_permission.pid = p.id
WHERE
    a.id = #{aid}

4.2 修正ResultMap配置（映射别名列）

更新ResultMap中collection标签的column属性，指向SQL中定义的别名：

xml 复制代码

<resultMap id="adminMapper" type="com.lion.online.pojo.Admin">
    <!-- 管理员主表映射 -->
    <id property="id" column="id"></id>
    <result property="username" column="username"></result>
    
    <!-- 角色列表关联：column指向角色ID别名rid -->
    <collection property="roles" column="rid" ofType="com.lion.online.pojo.Role">
        <id property="id" column="rid"></id>  <!-- 角色主键映射别名列 -->
        <result property="roleName" column="role_name"></result>
        <result property="roleDesc" column="role_desc"></result>
        
        <!-- 权限列表关联：column指向权限ID别名pid -->
        <collection property="permissions" column="pid" ofType="com.lion.online.pojo.Permission">
            <id property="id" column="pid"/>  <!-- 权限主键映射别名列 -->
            <result property="permissionName" column="permission_name"></result>
            <result property="url" column="url"></result>
        </collection>
    </collection>
</resultMap>

4.3 优化说明

SQL别名命名规范：建议采用"表名首字母+id"的格式（如rid=role_id、pid=permission_id），提高可读性
collection标签的column属性：需与SQL别名完全一致，确保MyBatis能正确匹配关联数据
主键映射优先级：id标签的映射优先级高于result标签，必须优先确保主键字段映射正确

五、验证结果

优化后重新运行项目，页面成功展示所有关联数据：

List集合长度与数据库查询结果一致，BUG修复完成。

六、避坑总结

多表联查必注意：只要涉及多张表，必须对同名字段起别名，尤其是主键id
ResultMap映射原则：column属性对应"查询结果集的列名"，而非数据库表字段名，别名变更需同步更新