SqlSugar 导航查询实战：从实体配置到性能调优的完整指南

做 .NET 后端这几年，我大部分时间都跟多表关联打交道。订单要带明细，用户要带角色，文章要带标签，几乎每个接口背后都是“主表+子表”的组合。早期项目里，这类需求我基本都是手动 JOIN + 手动 DTO 映射。直到有一次，一个报表接口要一次查 7 张表，SELECT 出来的字段接近 40 个，改一个过滤条件要顺着 SQL 的关联顺序捋半天，当时是真后悔没早点把 SqlSugar 的导航查询研究透。这篇文章，我想以一个用了两年 SqlSugar 实战的开发者身份，把导航查询的实体配置、调用写法、条件筛选、性能取舍和常见坑位一次性讲清楚。

先明确一件事：导航查询并不是 SqlSugar 的独门绝技，但它确实是让我从“手动拼表”切换回“面向对象编程”最舒服的一个入口。你不需要在业务代码里维护一大坨 JOIN，只需要在实体上把关系声明出来，查询时告诉 ORM“把关联数据一起取回来”，剩下的事框架会完成。这篇文章适合刚接触 ORM 导航功能的同学，也适合准备从老式 SqlSugar 写法升级到导航写法的老手。

1. 从手动拼多表说起：导航查询要干掉的三件事

1.1 新手期最常见的三种关联数据处理法

先说一段我刚工作时的真实代码。当时要做一个订单列表接口，要求返回订单号、下单时间、商品明细行数、联系人电话。第一版做法是：先查订单主表，得到 50 条订单，然后在一个 for 循环里再每条查询一次订单明细表，统计数量。功能倒是很快就通了，但 50 条订单就要发 51 次查询。上了测试环境，数据量稍微多点，接口就出现明显的等待感。这就是最经典的“循环读子表”：

var orders = db.Queryable<OrderEntity>().Take(50).ToList(); foreach (var order in orders) { var items = db.Queryable<OrderItemEntity>() .Where(i => i.OrderId == order.Id) .ToList(); order.ItemCount = items.Count; // 假设有这么一个扩展字段 }

第二种常见写法，是把所有表一次性 JOIN 出来，得到一个扁平结果集。JOIN 本身没问题，问题是这种写法把领域对象强行拍扁了：查回来的每一行都是“订单+单条明细”的拼接，同一个订单会重复出现 N 行。如果你还要处理一对多关系，就不得不再写一层“去重 + 分组”的代码。表少的时候还能忍，表一多，SQL 语义就开始变得难以维护。

第三种方式是通过内存字典做二次匹配。先把主表查出来，再把所有子表查出来，然后在内存里GroupBy和ToDictionary，手动补关系。这种方式查询次数可控，代码也不难，但重复性极高，几乎每个接口都要写一套类似的“聚合+赋值”逻辑，属于很典型的体力活。

这三种做法各有利弊，但它们都有一个共同点：把“表与表的关系”这笔账，摊在了业务代码头上。只要关联层级深一点，代码量就会以很可怕的速度膨胀。

1.2 为什么最终绕回“对象导航”这条路

关系型数据库本身用外键来描述实体之间的关联，但到了面向对象的代码里，这种关联却没有直接体现。导航查询要做的事情，就是让 ORM 把数据库的“表关联”翻译成对象的“属性引用”。你在OrderEntity上声明一个List<OrderItemEntity> Items，查询时告诉框架“把明细一起加载”，SqlSugar 就会把对应订单的所有明细放进去。

这样做的好处不只是少写几行代码。更重要的是，业务代码的阅读顺序变得和需求描述一致了：“查订单，带上明细，嵌套查出商品”——比拼接一段 20 行 JOIN 更容易维护。这也是我后来把不少老接口重写为导航查询的原因。不过导航查询也不是万能药，它要求你先正确表达实体关系，这块没配好，后面查询再简单也会翻车，所以下一章先讲配置。

2. 实体关系怎么声明才可靠：导航属性配置的完整姿势

2.1 集合导航和对象导航：两种形态的取舍

在 SqlSugar 里，导航属性通常以两种形态出现：一种是集合形态，比如List<OrderItemEntity> Items，对应数据库里的一对多关系；另一种是对象形态，比如OrderExtendEntity Extend，对应一对一关系，或者“多对一”时子表里引用主表那条记录。

这里有个容易混淆的点：子表也可以反过来导航到主表。

public class OrderItemEntity { public int Id { get; set; } public int OrderId { get; set; } public int ProductId { get; set; } public int Quantity { get; set; } [Navigate(NavigateType.ManyToOne, nameof(OrderId))] public OrderEntity Order { get; set; } }

OrderEntity里有List<OrderItemEntity> Items，OrderItemEntity里又可以有一个OrderEntity Order。两者并不冲突，它们表达的是同一个关系从不同方向看过去的投影。实际项目中，如果只需要“订单带明细”，可以只配主表侧；如果还需要从明细推回订单，就顺手把两边的导航属性都配上。多配置一个属性本身不会产生额外查询，只有你在查询中显式使用它时才生效。

2.2 [Navigate] 的三种写法对应三种关系

SqlSugar 的导航属性依赖[Navigate]特性来声明。写法看着简单，但外键方向一定要捋清楚。

一对一，典型场景是订单主表加一张订单扩展表，保存收货地址、发票信息等低频字段：

[Navigate(NavigateType.OneToOne, nameof(OrderExtendEntity.OrderId))] public OrderExtendEntity Extend { get; set; }

一对多，典型场景是订单和订单明细：

[Navigate(NavigateType.OneToMany, nameof(OrderItemEntity.OrderId))] public List<OrderItemEntity> Items { get; set; }

多对多，典型场景是用户和角色。多对多不能直接在两张主表之间建立外键，必须借助中间表，所以Navigate要接收两个参数：中间表里的两个关联字段。

[Navigate(NavigateType.ManyToMany, nameof(UserRoleEntity.RoleId), nameof(UserRoleEntity.UserId))] public List<UserEntity> Users { get; set; }

这里额外说明一下参数含义：第一个参数是“当前实体在中间表里的外键”，第二个参数是“目标实体在中间表里的外键”。以RoleEntity上的Users属性为例，意思是：当前是角色，中间表里RoleId等于当前角色 Id 的那些记录，再通过UserId关联到目标用户。有人会把两个参数写反，查询结果就变成完全不相干的集合，排查起来很费劲。建议用nameof()而不是直接写字符串，这样至少可以提前拿到编译期提示。

2.3 不建外键也能导航：先搞清楚边界

一个很常见的疑问是：我数据库里没建外键，能不能用导航查询？可以。[Navigate]是映射层的声明，它只是告诉 SqlSugar 实体之间应该怎么关联，并不要求在数据库层面真实存在外键约束。这一点在老旧系统和分库场景下特别有用：你没法轻易改表结构，但可以在实体层模拟出关系。

不过也有边界：既然没有数据库约束，数据的完整性就要靠业务逻辑保证。如果子表里存在孤儿数据（外键指向不存在的父记录），导航查询的结果里对应集合会是空值或缺失项。也就是说，不建外键让导航更“自由”，但数据质量需要自己兜底。

还有一点值得注意：同一张表出现多次关联时（比如订单表里既有买家也有卖家，都指向用户表），单纯一个导航属性没法区分应该返回哪个角色下的用户。这种场景建议拆成多个明确属性，并结合外键条件逐个声明，不要企图一个属性表达两层含义。

3. 查询主菜：预加载、级联加载与条件加载的写法拆解

3.1 单层预加载：Includes 的经典形态

实体配置完成后，查询就很直接了：

var orderList = db.Queryable<OrderEntity>() .Includes(x => x.Items) .Includes(x => x.Extend) .Where(o => o.CreateTime >= startTime && o.CreateTime <= endTime) .ToList();

这句话的意思是：我要查订单，并且希望每条订单的Items和Extend也一起查出来。SqlSugar 会在查询时自动根据[Navigate]配置拼接关联条件，最终得到的结果是：每个OrderEntity.Items已经是填充好的List<OrderItemEntity>，不需要再手工循环赋值。这也是导航查询最常用的形态——单层预加载。

为什么推荐这种方式？因为绝大多数详情报读场景，加载顺序是明确的：主表数据是主体，子表数据是附属信息。Includes把“主查询 + 关联加载”两件事合并成了一个查询描述，代码里不再出现“先查主表、再按主键查子表”这类业务噪音。

3.2 多级联查：从订单到明细再到商品

实际业务里，一层经常会不够。订单下面有明细，明细里还关联商品，用户打开页面想看的是“订单 → 明细 → 商品名”，这就是多级联查。SqlSugar 的Includes支持继续往后扩展：

var orderList = db.Queryable<OrderEntity>() .Includes(x => x.Items.Select(i => i.Product)) .ToList();

这里要先确认明细实体上确实配了ProductEntity Product这个导航属性。没配的话，代码在这里就会报错或者查不出数据。多级联查特别适合树形结构的页面展示，比如分类下面有文章，文章下面有评论。我见过最深的导航层级是五层：区域 → 仓库 → 货架 → 商品 → 批次，虽然也能跑，但生成的 SQL 会比较复杂，后续维护时排查问题的工作量也会翻倍。所以我的建议是，层级超过三层时，认真想想是否应该拆接口或做冗余字段，而不是一直往深处嵌套。

3.3 只加载符合条件的子集合

有些需求并非要把子表全量数据带出来，比如订单列表只关心“数量大于 1 的明细”。这时可以在Includes内部挂过滤条件：

var orderList = db.Queryable<OrderEntity>() .Includes(x => x.Items.Where(i => i.Quantity > 1)) .ToList();

这种写法，查询到的每条订单只带着符合条件的那部分明细。它非常实用，但要小心一个隐含语义：加载出来的Items不再代表数据库里的全部明细，而是“过滤后的明细”。如果你后续对这个集合执行求和或统计，得到的只是部分数量，不是全量数据。

如果是列表页展示，你甚至可能看到一条订单带着零条明细——这不见得是数据问题，而是条件把明细过滤空了。对这种场景，我通常会额外增加一个统计字段，比如用另一条聚合查询来拿全量数量，保证“展示用子集”和“统计用全量”各归其位。

3.4 不预加载时集合变量里到底是什么

一个让我在项目初期吃过亏的点，需要单独提醒：如果你查询时没有Includes，导航属性Items会是null，并不是一个空集合的初始值。

var order = db.Queryable<OrderEntity>().First(); // 没有 Includes(x => x.Items) if (order.Items.Count > 0) // 空引用风险

所以，第一，在业务代码里访问导航集合前要养成空判断的习惯；第二，在用 AutoMapper 或者手写 DTO 转换时，要注意Items为 null 会不会影响默认值。避免空引用最简单的方式，是在实体定义时就给它一个默认值：

public List<OrderItemEntity> Items { get; set; } = new List<OrderItemEntity>();

但注意，设了默认值后，同样不能以为它代表“已经查过数据库”。它只是避免空引用，真正的数据仍然要通过Includes加载。

4. 性能关键点：一条导航查询背后到底执行了几条 SQL

4.1 用 ToSql 观察导航查询发出去的 SQL

很多人在学习导航查询时，只关心代码怎么写，完全不看 SqlSugar 到底生成了什么样的 SQL。等线上出现慢查询，又反过来怀疑框架效率。我的工作习惯是，任何一段第一次写的导航查询，都要先调用.ToSql()看一眼：

var sql = db.Queryable<OrderEntity>() .Includes(x => x.Items) .ToSql(); Console.WriteLine(JsonConvert.SerializeObject(sql));

ToSql会把这段查询真正会执行的 SQL 返回出来，有可能是多段。借助它，你能立刻判断出 SqlSugar 在当前版本里走的是 JOIN 合并成一条 SQL，还是先查主表再用IN查子表。这两种策略适应不同数据分布，没有绝对好坏。重要的是，你知道了它实际执行了几次数据库往返，心里有数，后续调优才有方向。

4.2 N+1 的危险信号：最常见于循环里查子表

N+1 问题最典型的触发方式，就是循环内部查数据库。哪怕你已经用上了导航查询，也不代表不会踩。比如下面这种写法，本质上是把导航查询当作“补数据工具”，循环交叉调用：

var orders = db.Queryable<OrderEntity>().Take(20).ToList(); foreach (var order in orders) { var detail = db.Queryable<OrderItemEntity>() .Where(i => i.OrderId == order.Id) .ToList(); order.Items = detail; }

一眼看去代码没毛病，实际上发了 21 次 SQL。更隐蔽的版本是在Select表达式里访问导航属性，比如对每个订单去读order.Items.Count，如果下层没有正确的Includes，就很容易触发补偿式的多段查询。排查方法也很简单：打开数据库日志，或者用ToSql抓取查询列表，看到同一类 SQL 在循环里反复出现，基本就是 N+1。

4.3 读取优化、分页关联与批量加载的经验值

处理 N+1，核心思路就两条：把“循环查子表”改成“一次性批量查”，以及把“事后补查”改成“查询时预加载”。前者适合主表数量不可控的场景，后者适合已知只读页面。

var orderIds = orders.Select(o => o.Id).ToList(); var items = db.Queryable<OrderItemEntity>() .Where(i => orderIds.Contains(i.OrderId)) .ToList(); var itemMap = items.GroupBy(i => i.OrderId).ToDictionary(g => g.Key, g => g.ToList());

分页场景要特别留意。如果你先对订单做Skip/Take分页，再在这个分页结果上Includes明细，SqlSugar 处理起来通常没有大问题。但如果你反过来，先把整个订单表Includes成超大对象集合再分页，内存和 SQL 复杂度都会失控。正确姿势永远是“先分页主表，再加载子集集合”。我在项目里甚至见过有人为了省事，把订单、明细、商品一次性全加载到内存再分页，数据量小时还好，一旦明细膨胀，页面直接卡死。这类问题不属于框架缺陷，属于使用姿势错误。

还有只读查询建议开启无跟踪模式（不同版本接口略有差异，老版本常见写法是AsNoTracking，较新版本可能有等价方法）。导航查询产生的对象图通常很庞大，如果框架还要再维护一份变更跟踪的缓存，内存压力会明显上升。只读页面没必要付出这个代价。

5. 高频坑位实录：循环引用、条件筛选和聚合场景

5.1 序列化时的父子循环引用怎么解

实体上加了双向导航后，最常见的连锁反应是序列化时报“循环引用”。比如订单引用明细，明细又反向引用订单，JSON 序列化时就会无限递归。这里优先推荐一层思路：接口返回给前端时不要直接序列化实体，而是转成 DTO。

var result = orderList.Select(o => new OrderInfoDto { Id = o.Id, OrderNo = o.OrderNo, Items = o.Items?.Select(i => new OrderItemDto { Id = i.Id, Quantity = i.Quantity }).ToList() }).ToList();

DTO 转换的另一个好处是能顺手裁剪字段，把不需要的内层导航（比如明细回指订单的Order）直接忽略，从根上避免循环引用。如果项目里已经大量使用实体直出，也可以在相关属性上标记[JsonIgnore]，但这样会让属性在其它序列化场景也失效，所以还是 DTO 更稳妥。

5.2 条件加载子集合后，筛选结果比你想象的小

上一章讲过条件加载，这里再补一个具体坑：条件写错方向。有人想查“过去一周订单以及其中金额大于 100 的明细”，于是把时间条件加到明细的Includes里：

.Includes(x => x.Items.Where(i => i.Amount > 100 && i.Order.CreateTime >= 某时间))

这个写法的问题在于，i.Order.CreateTime是主表字段，在主表已经被Where筛过一次后，把它塞进子表条件里容易让人觉得“两个条件都生效了”，但实际出来的集合是“主表满足条件且明细金额大于 100”的交叉结果，部分满足主表条件的订单如果没有任何满足条件的明细，会在列表里消失。更稳妥的写法是：主表条件继续留在Where，子表条件只放明细自身字段。列表需要展示订单时，即使某订单没有满足条件的明细，也应该保留订单本身，再用全量统计字段去补。

5.3 导航属性碰上 GroupBy / 聚合时的替代方案

不少人在“按商品统计订单总数”这类需求里硬套导航查询，写法就会变得别扭。因为导航查询的核心是“按主表返回对象图”，而聚合查询的核心是“按分组返回统计值”，两者目标完全不同。

我的推荐做法是：聚合统计就老老实实用普通查询 +GroupBy，得到统计结果后，如果需要再回填到嵌入式对象，可以用前面说到的内存分组方式，或在Select投影里完成一次按主键分组的组装。SqlSugar 里的Mapper也可以承担部分组装，但它的定位更多是“手动指定映射关系”，和导航查询并不冲突。我一般把导航查询用在“查询详情 + 级联对象”的场景，把GroupBy用在“出报表 + 出统计数据”的场景，两者各司其职，代码会清晰很多。

5.4 别指望导航自动帮你做级联删除和更新

[Navigate]只管查询时怎么加载，它和数据库外键的ON DELETE CASCADE是两码事。在 SqlSugar 里，你配置了导航属性，不等于删除订单时会自动删除它下面的明细。实际项目中，级联删除我建议显式写清楚：要么在同一事务里先删明细再删主表，要么利用数据库约束处理。

try { db.Ado.BeginTran(); db.Deleteable<OrderItemEntity>().Where(i => i.OrderId == orderId).ExecuteCommand(); db.Deleteable<OrderEntity>().Where(o => o.Id == orderId).ExecuteCommand(); db.Ado.CommitTran(); } catch { db.Ado.RollbackTran(); throw; }

如果你在项目里遇到“删了主表，子表还有残留”的线上问题，别急着怀疑框架，先去查业务代码和数据库约束。

6. 给你的取舍建议：哪些场景用导航查询，哪些场景老实写 JOIN

6.1 适合用导航查询的典型场景

详情页/列表页的级联展示，是导航查询最舒服的场合。比如查询订单带明细，再带每个明细的商品名，一个Includes链条就能把对象树填充完整，返回给前端也天然是 JSON 结构。树形结构读取同样推荐，像分类树、权限菜单这类“父子层级”模型，导航查询配合递归遍历，代码量能压到很小。一对多、多对多的读写分离项目，如果查询需求稳定、关联层级不超过三层，导航查询可以大幅减少重复样板代码。

6.2 不建议硬套导航的场景

需要大面积GroupBy + 聚合出图表报表的场景，不建议用导航。导航返回的是完整对象图，不是统计结果，强行使用只会让框架做无谓的对象拼装。需要精确控制每一条 SQL 的团队，如果线上 DBA 不允许 JOIN、或者要求所有 SQL 必须走某种索引结构，导航查询反而会成为限制，此时普通查询 + 投影更可控。超大表关联也要谨慎，导航查询在子表行数巨大时，生成的 SQL 复杂度会明显上升，不如用分页 + 预加载主键的方式更稳定。

6.3 我的兜底策略与工作习惯

我的兜底策略其实就一句话：默认用导航查询表达“对象关系”，遇到统计和性能瓶颈时，回退到“普通查询 + 内存组装 + 手工 SQL”。

在接手一个新项目时，我会把ToSql作为调试阶段的固定动作，尤其第一次写某个复杂导航时，一定先看一眼 SqlSugar 到底发了什么 SQL。线上遇到慢查询，也先不要急着骂框架，而是去抓实际执行计划，看是不是条件没走索引，或者是不是导航嵌套过深导致的大查询。

经过几次重构，回头看，真正给项目带来收益的不只是导航查询这个功能本身，而是它逼着我重新梳理了实体关系边界。实体之间的关联，本来就应该由实体层表达，业务代码不该天天重复这些业务无关的关联映射。只要关系边界理清楚了，用导航查询也好，用普通 JOIN 也好，写起来都会顺很多。如果你现在正准备在新项目里引入 SqlSugar，我建议从第一天就把导航查询考虑进去，别等代码写满了再回填——那是成本最高的姿势。