1. 从“能用”到“会用”：为什么基础查询值得深究？
在.NET生态里，ORM框架的选择不少，Entity Framework Core、Dapper、FreeSQL…… 而SqlSugar以其轻量、高性能和国人开发带来的友好中文文档，成为了很多项目，尤其是中小型项目的首选。很多朋友上手SqlSugar，第一步就是照着文档写一个db.Queryable<T>().ToList()，看到数据出来了，就觉得“基础查询”这部分已经掌握了，可以直奔“联表查询”、“分页”、“事务”这些“高级”主题去了。
但在我带团队和实际项目踩坑的经历里，恰恰是这种对“基础”的轻视，埋下了最多的隐患。你可能遇到过：一个简单的列表查询，数据量稍大就慢得离谱；一个Where条件，明明看着没问题，生成的SQL却不是你想要的；或者更隐蔽的，在循环里不小心触发了N+1查询，自己还浑然不觉。这些问题，追根溯源，往往不是框架的“高级特性”用错了，而是对最基础的查询构建方式理解不透彻。
所以，这篇内容我们不聊花哨的，就扎扎实实地把SqlSugar的“基础查询”掰开揉碎了讲。我会结合真实的报错案例（比如网络热词里提到的sqlsugar报错）和性能陷阱，告诉你那些官方文档可能一笔带过，但在生产环境里至关重要的细节。目标是让你写的每一行基础查询代码，都清晰、高效、可控，真正理解IQueryable<T>背后的故事，为后续所有复杂操作打下坚实的基础。无论你是刚接触SqlSugar，还是已经用过一阵子但感觉有些地方“雾里看花”，这篇文章都值得你花时间细读。
2. 核心入口：SqlSugarClient与Queryable<T>的创建与配置
一切查询的起点，都是SqlSugarClient（或SqlSugarScope，这是更新的推荐用法，支持多租户和更优雅的生命周期管理）。但创建客户端不仅仅是连接字符串那么简单，初始配置直接影响着后续所有查询的行为和性能。
2.1 连接配置：不仅仅是连接字符串
创建SqlSugarClient时，我们通常会传入一个ConnectionConfig对象。除了最基础的ConnectionString、DbType，有几个关键配置项在基础查询阶段就必须明确：
var config = new ConnectionConfig() { ConnectionString = “Server=.;Database=TestDB;Uid=sa;Pwd=123456;”, DbType = DbType.SqlServer, // 明确指定数据库类型 IsAutoCloseConnection = true, // 是否自动关闭连接 InitKeyType = InitKeyType.Attribute, // 实体主键如何识别 MoreSettings = new ConnMoreSettings() { IsAutoRemoveDataCache = true, // 查询后是否自动清理缓存 IsWithNoLockQuery = false, // 默认查询是否加 WITH(NOLOCK) } }; using var db = new SqlSugarClient(config);关键配置解析：
DbType: 必须准确。SqlSugar会根据这个类型生成不同数据库的SQL方言。虽然它支持像DbType.MySql连接MariaDB这类兼容情况，但明确指定能避免一些边缘语法问题。IsAutoCloseConnection: 建议设为true。这意味着在查询执行完毕（如调用ToList()）后，框架会自动将数据库连接归还到连接池。如果你设为false，则需要手动调用db.Close()或db.Dispose()，否则连接会一直占用，在高并发下容易耗尽连接池。这是新手常忽略的性能坑点。InitKeyType: 这个配置决定了SqlSugar如何识别你的实体类主键。Attribute表示通过[SugarColumn(IsPrimaryKey = true)]特性标识；SystemTable表示从数据库系统表读取；Attribute是最常用且性能最好的方式，因为它不需要额外的数据库查询。MoreSettings.IsWithNoLockQuery: 这是一个需要谨慎对待的配置。如果设为true，那么所有查询生成的SQL都会在表名后加上WITH(NOLOCK)。这在某些对脏读不敏感、追求极高查询并发度的读库场景可能有用，但绝大多数业务场景下，不建议全局开启。脏读可能导致你看到未提交的、甚至会被回滚的数据，引发严重的业务逻辑错误。正确的做法是在需要时，在具体的查询语句中通过.With(SqlWith.NoLock)来局部应用。
2.2 理解Queryable<T>：它是什么，不是什么？
通过db.Queryable<T>()，我们得到了一个ISugarQueryable<T>对象。这里有一个至关重要的概念：Queryable<T>本身并不执行任何数据库操作，它只是一个查询描述符（Query Descriptor）。
// 这行代码没有访问数据库！ var query = db.Queryable<Order>(); // 只有当你调用“终结方法”时，查询才会真正执行 var list = query.ToList(); // 执行，生成 SELECT * FROM [Order] var first = query.First(); // 执行，生成 SELECT TOP 1 * FROM [Order] var count = query.Count(); // 执行，生成 SELECT COUNT(1) FROM [Order]这种“延迟执行（Deferred Execution）”特性是理解SqlSugar（以及很多LINQ框架）的核心。它意味着你可以分步、有条件地构建你的查询逻辑，而框架会在最终执行的那一刻，将你所有的Where、OrderBy、Select等操作，组合成一条最优（或接近最优）的SQL语句发送给数据库。
一个常见的误区与性能陷阱：
// 错误示范：在循环中执行查询 var orderIds = new List<long> { 1, 2, 3 }; foreach (var id in orderIds) { var order = db.Queryable<Order>().Where(o => o.Id == id).First(); // ... 处理 order } // 这会生成3条独立的SQL： SELECT TOP 1 * FROM [Order] WHERE Id = 1 ... // 产生了N+1查询问题，性能极差。 // 正确做法：利用 Queryable 的延迟执行，一次性查询 var query = db.Queryable<Order>().Where(o => orderIds.Contains(o.Id)); var orderList = query.ToList(); // 生成一条SQL： SELECT * FROM [Order] WHERE Id IN (1,2,3) // 然后在内存中处理 orderList理解Queryable<T>是“描述”而非“执行”，是写出高效查询代码的第一步。
3. 条件筛选（Where）的“正确姿势”与深度避坑
Where是查询中最频繁使用的操作，也是坑最多的地方。SqlSugar的Where方法非常灵活，支持Lambda表达式、动态条件拼接，但灵活也意味着容易用错。
3.1 Lambda表达式：强类型与编译时检查
这是最推荐的方式，利用了C#的强类型和编译时检查，安全又直观。
// 简单相等判断 var list = db.Queryable<Order>().Where(o => o.Status == 1).ToList(); // 复杂条件组合 var list2 = db.Queryable<Order>() .Where(o => o.CreateTime >= DateTime.Now.AddDays(-7) && (o.Amount > 100 || o.UserId == currentUserId)) .ToList();生成的SQL清晰可预测：
SELECT * FROM [Order] WHERE Status = 1 SELECT * FROM [Order] WHERE CreateTime >= @CreateTime0 AND (Amount > @Amount1 OR UserId = @UserId2)注意：SqlSugar会对参数进行化，避免SQL注入，同时利于数据库缓存执行计划。
3.2 动态条件拼接：应对复杂业务场景
当查询条件来自前端表单，且字段可选填时，就需要动态构建Where条件。SqlSugar提供了Expressionable<T>这个强大工具。
错误做法（字符串拼接，易引发SQL注入或错误）：
string sqlWhere = “1=1”; if (!string.IsNullOrEmpty(name)) sqlWhere += $“ AND Name LIKE ‘%{name}%'”; // 危险！ var list = db.Ado.SqlQuery<Order>($“SELECT * FROM Order WHERE {sqlWhere}”);正确做法（使用Expressionable<T>）：
var exp = Expressionable.Create<Order>(); if (!string.IsNullOrEmpty(name)) exp.And(o => o.Name.Contains(name)); // 安全，参数化 if (status.HasValue) exp.And(o => o.Status == status.Value); if (minAmount.HasValue) exp.And(o => o.Amount >= minAmount.Value); var list = db.Queryable<Order>().Where(exp.ToExpression()).ToList();Expressionable会将所有条件用AND连接。如果需要OR逻辑，可以在单个And或Or方法内用Lambda完成，或者使用多个Expressionable组合。
3.3 高频“报错”与疑难排查
结合网络热词sqlsugar报错，这里总结几个Where环节的典型错误：
空值（null）处理不当：
// 假设某些记录的 Name 字段为 NULL var list = db.Queryable<Order>().Where(o => o.Name.Contains(“abc”)).ToList(); // 如果某行 o.Name 为 NULL，o.Name.Contains 在C#表达式树中可能被翻译成有问题的SQL，或直接抛出异常。 // 更安全的写法： var list = db.Queryable<Order>().Where(o => o.Name != null && o.Name.Contains(“abc”)).ToList();与数据库NULL比较的陷阱：
int? nullableStatus = null; var list = db.Queryable<Order>().Where(o => o.Status == nullableStatus).ToList(); // 当 nullableStatus 为 null 时，生成的SQL是 `WHERE Status = NULL`，这永远返回假。 // 正确做法是使用 SqlFunc 或 IsNullOrEmpty 处理： var list = db.Queryable<Order>() .WhereIF(nullableStatus.HasValue, o => o.Status == nullableStatus.Value) .ToList(); // 或者，如果你想查询 Status 为 NULL 的记录，应使用： // .Where(o => o.Status == null) // 框架会正确生成 `WHERE Status IS NULL`在
Where中使用C#方法/属性：// 错误：ToString() 无法被转换为SQL var list = db.Queryable<Order>().Where(o => o.Id.ToString().StartsWith(“100”)).ToList(); // 正确：使用 SqlSugar 提供的 SqlFunc 方法 var list = db.Queryable<Order>().Where(o => SqlFunc.ToString(o.Id).StartsWith(“100”)).ToList(); // 或者，如果逻辑不复杂，尽量在内存中过滤（先查询，后处理），但这可能影响性能。SqlSugar通过
SqlFunc静态类提供了大量可转换为SQL的函数，如SqlFunc.ToString、SqlFunc.Substring、SqlFunc.DateAdd等。务必在Where、OrderBy、Select等表达式树中使用这些方法，而不是直接的C#方法。
4. 排序、分页与字段选择：不仅仅是功能实现
基础查询的另外几个核心操作是OrderBy、Select和ToPageList。用对它们，能极大提升查询效率和代码可维护性。
4.1 排序（OrderBy）的细节与动态排序
// 单字段排序 var list = db.Queryable<Order>().OrderBy(o => o.CreateTime, OrderByType.Desc).ToList(); // 多字段排序 var list2 = db.Queryable<Order>() .OrderBy(o => o.Status) .OrderBy(o => o.CreateTime, OrderByType.Desc) .ToList(); // 注意：多个 OrderBy 是叠加的，不是覆盖。上述代码会先按 Status 升序，再按 CreateTime 降序排。动态排序（常用于列表页面）：
string sortField = “Amount”; // 可能来自前端 string sortOrder = “desc”; var query = db.Queryable<Order>(); // 使用反射或条件判断来动态设置 OrderBy（略繁琐但安全） if (!string.IsNullOrEmpty(sortField)) { if (sortField == “Amount”) query = sortOrder == “desc” ? query.OrderBy(o => o.Amount, OrderByType.Desc) : query.OrderBy(o => o.Amount); else if (sortField == “CreateTime”) query = sortOrder == “desc” ? query.OrderBy(o => o.CreateTime, OrderByType.Desc) : query.OrderBy(o => o.CreateTime); // ... 其他字段 } var list = query.ToList();对于更复杂的动态排序，可以考虑使用OrderBy($“{sortField} {sortOrder}”)的字符串方式，但必须严格校验sortField参数，防止SQL注入，确保它只能是合法的实体属性名。
4.2 分页查询：性能的关键
分页是Web应用中最常见的需求。SqlSugar提供了非常便捷的ToPageList方法。
int pageIndex = 1; int pageSize = 20; RefAsync<int> totalCount = 0; // 用于接收总记录数 var pageList = await db.Queryable<Order>() .Where(o => o.Status == 1) .OrderBy(o => o.Id, OrderByType.Desc) .ToPageListAsync(pageIndex, pageSize, totalCount); // 此时，pageList 是第1页的20条数据，totalCount 是所有 Status=1 的订单总数。分页性能的核心：
OrderBy是必须的：没有明确的排序，数据库每次分页返回的结果集顺序可能不一致，这是分页的大忌。通常使用唯一或高区分度的字段（如自增主键、创建时间）进行排序。- 避免
COUNT(*)在大表上的性能问题：ToPageList会执行两条SQL：一条COUNT(1)获取总数，一条SELECT ... OFFSET ... FETCH ...（或数据库等效语法）获取分页数据。如果WHERE条件很复杂或表非常大，COUNT操作可能很慢。对于不需要精确总数的场景（如“下一页”模式），可以考虑其他方案，比如只判断“是否有下一页”。 - 覆盖索引：确保你的
WHERE条件和ORDER BY字段能被索引覆盖，这是提升分页查询速度最有效的手段。
4.3 字段选择（Select）：告别SELECT *
使用Select来指定返回的字段，是优化查询最重要的习惯之一。
// 不推荐：查询所有字段 var list = db.Queryable<Order>().ToList(); // SELECT * FROM [Order] // 推荐：只查询需要的字段 var list = db.Queryable<Order>() .Select(o => new { o.Id, o.OrderNo, o.Amount, o.CreateTime }) // 匿名对象 .ToList(); // 或者映射到指定DTO var list = db.Queryable<Order>() .Select(o => new OrderDto { Id = o.Id, OrderNo = o.OrderNo }) .ToList();为什么一定要用Select？
- 减少网络传输和内存占用：表中可能有几十个字段，但列表页可能只需要显示5个。
SELECT *会传输所有数据，包括你不需要的TEXT、NVARCHAR(MAX)等大字段，浪费带宽和内存。 - 更利于索引覆盖：如果你只查询
Id, Name, Status，而这三个字段正好在一个复合索引中，数据库可能直接从索引中获取数据（索引覆盖），而无需回表查询数据行，速度极快。 - 明确数据契约：使用DTO或匿名对象，迫使你思考这个查询到底需要什么数据，代码意图更清晰。
注意：使用
Select后，返回的对象类型就变了。如果你后续还想基于这个查询结果进行Where或OrderBy，需要注意Lambda表达式中的字段必须在新对象中存在。
5. 聚合查询、分组与执行统计
除了获取列表，基础查询还常包含统计操作。
5.1 常用聚合函数
SqlSugar通过Select和SqlFunc支持聚合查询。
// 统计总数 var count = db.Queryable<Order>().Count(); // 求和 var totalAmount = db.Queryable<Order>().Sum(o => o.Amount); // 平均值 var avgAmount = db.Queryable<Order>().Avg(o => o.Amount); // 最大值、最小值 var maxId = db.Queryable<Order>().Max(o => o.Id); var minTime = db.Queryable<Order>().Min(o => o.CreateTime); // 复杂聚合：结合 GroupBy var list = db.Queryable<Order>() .GroupBy(o => o.Status) .Select(o => new { Status = o.Status, Count = SqlFunc.AggregateCount(), // 注意这里用法 TotalAmount = SqlFunc.AggregateSum(o.Amount) }) .ToList(); // 生成 SQL: SELECT Status, COUNT(1) AS Count, SUM(Amount) AS TotalAmount FROM [Order] GROUP BY Status注意SqlFunc.AggregateCount()和SqlFunc.Count()的区别：前者用在GroupBy后的Select中，表示分组的计数；后者可以直接作为查询的终结方法，如.Count()。
5.2 查询执行统计与调试
当你发现某个查询很慢时，如何定位？SqlSugar提供了方便的调试和统计功能。
开启SQL监控：
// 在创建 SqlSugarClient 时配置 var db = new SqlSugarClient(new ConnectionConfig{ /* ... */ }, db => { // 输出SQL语句和参数到日志 db.Aop.OnLogExecuting = (sql, pars) => { Console.WriteLine(sql); foreach (var param in pars) { Console.WriteLine($“{param.ParameterName}: {param.Value}”); } }; // 执行时间统计 db.Aop.OnLogExecuted = (sql, pars) => { // 这里可以获取到执行耗时（需要自己计算） }; // 错误监听 db.Aop.OnError = (exp) => { // 记录异常 }; });通过OnLogExecuting，你可以清晰地看到最终发送到数据库的SQL语句及其参数，这是排查SQL语法错误、性能问题（如缺失索引、全表扫描）的最直接手段。
手动获取SQL字符串：有时你想先看看生成的SQL，而不执行它。
var query = db.Queryable<Order>().Where(o => o.Id > 100).OrderBy(o => o.Id); var sqlString = query.ToSql().Key; // 获取生成的SQL字符串 var sqlParams = query.ToSql().Value; // 获取参数列表 Console.WriteLine(sqlString);这个功能在调试复杂动态查询时非常有用。
6. 实战中的“多数据库连接”场景处理
网络热词提到了.net10支持sqlsugar多个数据库连接，这反映了真实项目中的一个常见需求：一个应用需要同时操作多个数据库（可能是不同业务库、读写分离、分库等）。在.NET 6/7/8及更高版本中，结合SqlSugar的多数据库支持，可以优雅地处理。
6.1 使用SqlSugarScope管理多连接
SqlSugarScope是官方推荐的新方式，它内部维护了一个连接池，并且是线程安全的。
// 在 Program.cs 或 Startup 中配置 builder.Services.AddSingleton<ISqlSugarClient>(provider => { var configs = new List<ConnectionConfig> { new ConnectionConfig { ConfigId = “DB1”, DbType = DbType.SqlServer, ConnectionString = “connStr1”, IsAutoCloseConnection = true }, new ConnectionConfig { ConfigId = “DB2”, DbType = DbType.MySql, ConnectionString = “connStr2”, IsAutoCloseConnection = true }, }; return new SqlSugarScope(configs, db => { /* AOP配置 */ }); }); // 在业务层使用 public class OrderService { private readonly ISqlSugarClient _db; public OrderService(ISqlSugarClient db) { _db = db; } public void QueryFromMultipleDB() { // 使用默认连接（ConfigId为“DB1”的连接） var listFromDB1 = _db.Queryable<OrderFromDB1>().ToList(); // 切换到“DB2”连接 var db2 = _db.GetConnection(“DB2”); var listFromDB2 = db2.Queryable<UserFromDB2>().ToList(); // 甚至可以跨库查询（如果数据库支持链接服务器或联邦查询，但SqlSugar本身不直接支持跨库JOIN） // 通常做法是分别查询，在内存中关联。 } }6.2 读写分离配置
对于读写分离场景，可以配置一个主库（写）和多个从库（读）。
var config = new ConnectionConfig { ConnectionString = “主库连接字符串”, DbType = DbType.MySql, IsAutoCloseConnection = true, SlaveConnectionConfigs = new List<SlaveConnectionConfig> { new SlaveConnectionConfig { ConnectionString = “从库1连接字符串” }, new SlaveConnectionConfig { ConnectionString = “从库2连接字符串” }, } }; var db = new SqlSugarClient(config);配置后，默认情况下，所有的查询操作（Queryable）会随机分配到从库执行，而写操作（Insertable，Updateable，Deleteable）会在主库执行。这在一定程度上实现了读写分离和负载均衡。你需要确保主从数据库之间的数据同步。
6.3 多数据库操作的注意事项
- 事务处理：跨多个
SqlSugarClient实例（对应不同物理数据库）的事务是分布式事务，复杂度高，通常需要引入如TransactionScope（需确保MSDTC服务开启）或基于消息队列的最终一致性方案。同一个SqlSugarClient实例内跨不同ConfigId的连接，默认不支持统一事务。 - 实体与数据库映射：不同数据库的表结构可能不同。你需要为每个数据库定义对应的实体类（即使表名相同，也可能在不同数据库），或者使用
[SugarTable(“TableName”, “SchemaName”)]等特性来精确映射。 - 连接池管理：确保每个
ConnectionConfig的IsAutoCloseConnection设置为true，让SqlSugar自动管理连接生命周期，避免连接泄露。
7. 性能优化心智模型与常见误区
最后，我想分享几个在编写基础查询时应当时刻牢记的心智模型，这能帮你从“写出能跑的代码”进阶到“写出高效的代码”。
“数据库工作”与“内存工作”的边界：始终思考，这个操作是让数据库做更高效，还是拉取到内存后用C#处理更合适？原则是：过滤、排序、分页、聚合（COUNT， SUM， GROUP BY）尽量让数据库做；复杂的业务逻辑计算、多次循环判断，可以在内存中做。因为数据库是为批量数据操作优化的，而网络I/O是昂贵的。
“N+1查询”是性能杀手：这是ORM中最常见的性能问题。时刻警惕在循环中执行查询。解决方案永远是：变多次查询为一次查询，使用
IN语句或先查询出所有ID再内存关联。理解“延迟执行”的副作用：因为
Queryable延迟执行，如果你在构建查询后，修改了用于构建条件的变量，可能会得到意想不到的结果。int threshold = 100; var query = db.Queryable<Order>().Where(o => o.Amount > threshold); threshold = 200; // 修改了阈值 var list = query.ToList(); // 这里生成的SQL WHERE Amount > 100 还是 > 200？ // 答案是 > 100。因为表达式树在创建时捕获的是变量 threshold 当时的值（100）。 // 对于引用类型，情况更复杂，可能捕获的是引用，这需要特别注意。善用索引，但不要滥用：
Where和OrderBy中的字段应考虑加索引。但索引不是免费的，它会降低写操作（INSERT， UPDATE， DELETE）的速度并占用空间。通常针对高频、高选择性的查询条件建立索引。监控与分析：不要凭感觉优化。使用数据库自带的性能工具（如SQL Server的Profiler、执行计划，MySQL的慢查询日志）或APM工具，找到真正的慢查询，然后有针对性地优化。
基础查询是SqlSugar的基石，也是所有数据操作的起点。花时间深入理解这些概念和细节，看似“慢”，实则是通往编写高效、健壮数据访问层最快的路径。当你对Queryable的每一个操作都了如指掌，都能预见到它生成的SQL时，你就能真正地掌控你的数据层，避免绝大多数性能问题和运行时错误。
