Dapper复杂对象映射方法解析

Dapper不支持全自动深度嵌套映射，但可通过Multi-Mapping（如Query<T1,T2,TResult>配合splitOn）实现一对一级联；一对多用QueryMultiple分步查询+内存关联；三层及以上需组合多步查询并手动组装，核心是显式控制、避免N+1、注意别名与空值处理。

Dapper 本身不支持全自动的深度嵌套对象映射（比如 User 包含 Address，Address 又包含 City），但通过组合使用 Query 的多映射（Multi-Mapping）和手动组装逻辑，完全可以优雅地实现嵌套对象填充。

用 Query<T1, T2, TResult> 做两级关联映射

这是最常用、最清晰的方式，适用于主从结构（如 Order → OrderItem，User → Profile）。关键在于 SQL 中用 JOIN 拉平数据，并用 splitOn 参数告诉 Dapper 从哪一列开始是第二个对象的字段。

示例：映射 User 及其关联的 Department

var sql = @"
    SELECT u.Id, u.Name, u.Email, 
           d.Id as DeptId, d.Name as DeptName, d.Code
    FROM Users u
    LEFT JOIN Departments d ON u.DeptId = d.Id";
var users = connection.Query<User, Department, User>(
sql,
(user, dept) =>
{
user.Department = dept; // 手动赋值
return user;
},
splitOn: "DeptId"
).ToList();

• splitOn 必须匹配第二对象的第一个非空列名（这里用 d.Id as DeptId，所以写 "DeptId"）
• 两个对象字段名可以不同，但别名要和 C# 属性名一致（或开启 SqlMapper.AddTypeMap 自定义映射）
• lambda 中返回的是最终结果类型（这里是 User），可在此完成任意组装逻辑

处理一对多（如 User → List<Post>）：用 QueryMultiple 分步查询

一对多不能靠单条 JOIN 搞定（会产生笛卡尔积），推荐用 QueryMultiple 执行多个语句，再在内存中关联。

var sql = @"
    SELECT * FROM Users WHERE IsActive = 1;
    SELECT u.Id as UserId, p.* FROM Posts p
    INNER JOIN Users u ON p.UserId = u.Id
    WHERE u.IsActive = 1;";
using var multi = connection.QueryMultiple(sql);
var users = multi.Read<User>().ToList();
var posts = multi.Read<Post>().ToList();
// 手动按 UserId 分组挂载
var lookup = posts.GroupBy(p => p.UserId).ToDictionary(g => g.Key, g => g.ToList());
foreach (var user in users)
{
user.Posts = lookup.GetValueOrDefault(user.Id, new List<Post>());
}

• SQL 用分号分隔多个查询，Dapper 按顺序执行并返回多个结果集
• 先查主表，再查子表，避免重复加载和 N+1 问题
• 用 Dictionary<int, List<T>> 做 O(1) 关联，比循环嵌套查找快得多

三层及以上嵌套（如 User → Department → Company）：组合 + 手动构建

没有内置三元映射，但可以拆解为两步：先用 Query<User, Dept, User> 得到带 Department 的用户，再单独查 Company 并批量挂载。

// 第一步：查 User + Department（同上）
var usersWithDepts = connection.Query<User, Department, User>(...).ToList();
// 第二步：提取所有 DeptId，批量查 Company
var deptIds = usersWithDepts
.Where(u => u.Department != null)
.Select(u => u.Department.Id)
.Distinct()
.ToArray();
if (deptIds.Length > 0)
{
var companies = connection.Query<Company>(
"SELECT * FROM Companies WHERE Id IN @ids", 
new { ids = deptIds }
).ToDictionary(c => c.Id);
foreach (var user in usersWithDepts)
{
    if (user.Department != null && companies.TryGetValue(user.Department.Id, out var company))
    {
        user.Department.Company = company;
    }
}
}

• 避免为每个 Department 单独查 Company（N+1）
• 利用 ToDictionary 实现快速反查，保持线性时间复杂度
• 注意空值判断，防止 NullReferenceException

小技巧：用匿名对象或 ValueTuple 简化中间步骤

当嵌套层级多、临时组装频繁时，可用匿名类型过渡，让代码更松耦合：

var result = connection.Query<User, Department, Company, (User, Department, Company)>(
    sql,
    (u, d, c) => (u, d, c),
    splitOn: "DeptId,CompanyId"
).ToList();
// 再统一组装成最终对象
var finalUsers = result.Select(x =>
{
x.Item1.Department = x.Item2;
x.Item2.Company = x.Item3;
return x.Item1;
}).ToList();

• 适合一次性复杂映射，不想提前定义中间 DTO 类
• ValueTuple（C# 7+）比匿名类更轻量，且可序列化
• 仍需明确指定 splitOn 字段名，顺序必须与泛型参数一致

基本上就这些。Dapper 的哲学是“显式优于隐式”，它不隐藏 SQL 和映射逻辑，反而让你对性能和行为有完全掌控。嵌套映射不复杂，但容易忽略 splitOn 的大小写、别名一致性、空值处理这些细节。