Dapper不支持全自动深度嵌套映射，但可通过Multi-Mapping（如Query配合splitOn）实现一对一级联；一对多用QueryMultiple分步查询+内存关联；三层及以上需组合多步查询并手动组装，核心是显式控制、避免N+1、注意别名与空值处理。
Dapper 本身不支持全自动的深度嵌套对象映射（比如 User 包含 Address，Address 又包含 City），但通过组合使用 Query 的多映射（Multi-Mapping）和手动组装逻辑，完全可以优雅地实现嵌套对象填充。
用 Query 做两级关联映射
这是最常用、最清晰的方式，适用于主从结构（如 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";
<p>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）：用 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;";
<p>using var multi = connection.QueryMultiple(sql);
var users = multi.Read<User>().ToList();
var posts = multi.Read<Post>().ToList();</p><p>// 手动按 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>></int>做 O(1) 关联，比循环嵌套查找快得多
三层及以上嵌套（如 User → Department → Company）：组合 + 手动构建
没有内置三元映射，但可以拆解为两步：先用 Query<user dept user></user> 得到带 Department 的用户，再单独查 Company 并批量挂载。
// 第一步：查 User + Department（同上）
var usersWithDepts = connection.Query<User, Department, User>(...).ToList();
<p>// 第二步：提取所有 DeptId，批量查 Company
var deptIds = usersWithDepts
.Where(u => u.Department != null)
.Select(u => u.Department.Id)
.Distinct()
.ToArray();</p><p>if (deptIds.Length > 0)
{
var companies = connection.Query<Company>(
"SELECT * FROM Companies WHERE Id IN @ids",
new { ids = deptIds }
).ToDictionary(c => c.Id);</p><pre class="brush:php;toolbar:false;">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();
<p>// 再统一组装成最终对象
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 的大小写、别名一致性、空值处理这些细节。
