.NET Core 6集成SqlSugar：CodeFirst、CRUD到分页事务实战指南

最近又有一个 .NET Core 6 的后台接口项目要落地，数据访问层我直接在 SqlSugar 和 EF Core 之间选了前者。坦白说，之前我对国产 ORM 多少有些观望心态，但真正把 SqlSugar 集成进项目、跑通第一张表的 CRUD 之后，我才理解什么叫“开箱即用”——配置比 EF Core 简单，写起来又比 Dapper 舒服。这篇就把我这次集成的完整过程整理出来，从 NuGet 安装、核心配置、CodeFirst 建表、常用 CRUD，到分页事务和真实项目里的几个坑，尽可能帮刚接触 .NET Core 的开发者少走弯路，也能让有经验的人直接对照抄作业。

现在很多 .NET 开发者一提到 ORM，第一反应就是 EF Core 或者 Dapper，SqlSugar 在一些讨论里容易被忽略。但如果你只是想快速把一个管理后台、内部工具系统跑起来，不想折腾迁移文件，也不想手写大量 SQL 映射，SqlSugar 确实能省掉很多繁琐步骤。这篇文章的定位不是讲高深原理，而是把“最小可运行”的路径完整走一遍，顺便带你看看落地时真正需要注意的细节。

1. 为什么我在 .NET Core 里选择了 SqlSugar

1.1 常见 ORM 选型对比：EF Core、Dapper 与 SqlSugar

在选择数据访问层的时候，很多人的习惯是先考虑 EF Core，因为它毕竟是官方生态的一部分，文档、社区、扩展库都比较成熟。EF Core 确实强大，尤其是复杂模型关系、迁移管理、LINQ 查询能力都很完整，但代价是学习成本偏高。项目一旦上了规模，迁移文件、模型配置、导航属性之间的关系，会占据不少开发精力。如果你只是做一个几十张表的业务系统，用 EF Core 反而会觉得“杀鸡用了牛刀”。

Dapper 是另一个常见选项，它非常轻，性能好，执行原始 SQL 非常直接。但 Dapper 本质上是一个“微型 ORM”，实体映射、SQL 拼接、分页、批量插入这些都需要自己处理一部分。简单查询还好，稍微复杂的多条件组合、分页、动态更新，代码量会明显增加，而且很难避免手写 SQL 带来的维护成本。

SqlSugar 刚好卡在两者之间。它的 API 设计非常接近业务直觉，比如Insertable、Queryable、Updateable、Deleteable这种流式链式写法，几乎不需要额外学习就能上手。同时它的性能表现在多数业务场景下也不差，支持 SqlServer、MySQL、Sqlite、PostgreSQL、Oracle 等常见数据库。并且对国内业务场景有比较细致的支持，比如分页、批量操作、多库事务、雪花ID等，这些东西在真实项目里会经常用到。

这并不意味着 SqlSugar 全面优于 EF Core 或 Dapper，而是说在特定场景下它更合适。如果是大型企业级应用，模型关系复杂、团队又熟悉 EF Core，那 EF Core 依然是稳妥选择。但如果是中小型项目、快速原型、内部工具，或者你想把精力集中在业务上而不是 ORM 配置上，SqlSugar 会非常顺手。

1.2 SqlSugar 适合怎样的项目

根据我这段时间的使用经验，SqlSugar 特别适合下面几类场景：

• 中小型业务系统，表数量在几十张以内，不需要特别复杂的导航关系映射；
• 需要快速迭代的后台管理项目，CRUD 占了绝大多数数据操作；
• 项目需要在不同数据库之间切换，或者还在选型阶段，不想在数据访问层绑定具体数据库；
• 开发团队成员对 EF Core 不太熟悉，但又不想退回手写 SQL 的老路。

还有一个容易被忽略的点：SqlSugar 的文档和示例在中文化场景里读起来更顺畅，很多问题是中文论坛里已经有人趟过路的。这点对于快速排查问题来说，价值非常大。我在集成的时候遇到过几个小问题，搜到的解决方案基本都能直接跑通。

1.3 我的选型决策流程

如果你也在纠结选型，我给一个简单的判断方法。先问自己三个问题：

1. 项目的表关系复杂吗？会不会有大量多对多、继承、软删除这类模型关系？
2. 团队里谁负责数据层，大家更熟悉 EF Core 还是更愿意接受新工具？
3. 项目生命周期长不长，后续会不会有大规模迁移需求？

如果答案都是“不太复杂”、“想快速启动”、“没那么长远的包袱”，那 SqlSugar 就是一个值得试的选项。至少可以先做一个小的 Demo，比如用 Sqlite 跑通 CRUD，看看手感是否合适再决定。反正集成成本不高，真不合适换掉也不亏。

2. 搭建最小可用环境：NuGet 安装与核心配置

2.1 新建项目并安装 SqlSugarCore 包

这次我用的是 .NET Core 6 的 Web API 项目作为示例，理论上 .NET Core 3.1 到 .NET 8 都适用。先建一个空项目：

dotnet new webapi -n SqlSugarDemo cd SqlSugarDemo dotnet add package SqlSugarCore

安装完成后，项目文件.csproj里会多出一个 PackageReference 节点。需要注意版本号，SqlSugar 的版本迭代比较快，不同版本在 API 上有细微差异。官方推荐使用最新的稳定版本，我建议在安装后看一眼包版本，比如 5.x 系列的某些 API 和旧版就有些不一样，别拿老博客里的代码直接贴进新项目就以为能跑。

2.2 配置 ConnectionConfig 与创建 SqlSugarClient

SqlSugar 的核心配置对象是ConnectionConfig，它需要一个DbType、一个连接字符串，以及一些行为设置。我把客户端创建逻辑封装成一个静态工厂类，这样在项目的任何地方都能拿到实例：

using SqlSugar; public static class DbFactory { public static SqlSugarClient Create() { var config = new ConnectionConfig { DbType = DbType.Sqlite, ConnectionString = "DataSource=app.db", IsAutoCloseConnection = true, InitKeyType = InitKeyType.Attribute, MoreSettings = new ConnMoreSettings { IsAutoToLower = false } }; return new SqlSugarClient(config); } }

这段配置里有几个关键点值得解释：

• DbType决定了 SqlSugar 使用哪套方言，这里先选 Sqlite 作为起步数据库。如果你想换成 SqlServer，改成DbType.SqlServer，连接字符串也同步调整即可。
• IsAutoCloseConnection设置为 true 意味着每次执行完数据库操作后连接会自动关闭。这就省去了很多using包裹和手动释放的样板代码，平时写 CRUD 的时候特别省心。
• InitKeyType.Attribute表示主键和自增列的信息从实体特性读取，而不是去数据库里推断。这与后面的 CodeFirst 建表方式是对应的。

SqlSugarClient 内部有自己的连接池和线程安全机制，所以应用内应该尽量保持单例。我在 ASP.NET Core 里是这样注册的：

builder.Services.AddSingleton<ISqlSugarClient>(DbFactory.Create());

这里我特意用AddSingleton而不是AddScoped。SqlSugar 官方说明 SqlSugarClient 是支持线程安全的，全局一个实例即可，不需要像 DbContext 那样按请求创建。实际使用下来，这种单例模式配合IsAutoCloseConnection=true非常稳定。

2.3 为什么这样配置最省心

新手容易踩的一个误区是认为 ORM 会自动管理所有数据库连接，不需要关心连接生命周期。实际上不管什么 ORM，连接资源都应该优先短连接使用，用完就释放。IsAutoCloseConnection就是帮你自动完成这一步，表面上只是开关一个属性，实际省掉的是大量try/finally代码和连接泄漏隐患。

另外一个容易被忽略的点是连接字符串的写法。Sqlite 的DataSource=app.db非常简单，数据文件会在程序运行目录下创建。但 SqlServer、MySQL 的连接字符串有一堆参数，比如Server=localhost;Database=myDb;User Id=sa;Password=xxx;，你需要在切换数据库时同步换掉，并确保端口、SSL、字符集这些设置没问题。

提示：在真正写业务代码之前，先做一次最简单的连通测试，比如db.DbMaintenance.CreateDatabase()或直接执行一条Select 1，能确认配置、驱动、连接串三者都没问题，再往后写效率会高很多。

3. CodeFirst 与实体映射：从实体类到数据表的自动同步

3.1 实体类的特性标注

SqlSugar 的 CodeFirst 模式非常直观：你定义一个普通 C# 类，标上特性，然后调用InitTables，表结构就会自动创建。我的示例表是一张用户表，实体定义如下：

using SqlSugar; [SugarTable("sys_user")] public class User { [SugarColumn(IsPrimaryKey = true, IsIdentity = true)] public int Id { get; set; } [SugarColumn(IsNullable = false, Length = 50)] public string UserName { get; set; } [SugarColumn(IsNullable = false, Length = 128)] public string PasswordHash { get; set; } [SugarColumn(IsNullable = true, Length = 20)] public string Phone { get; set; } public DateTime CreateTime { get; set; } [SugarColumn(IsNullable = true)] public int? Status { get; set; } }

几个特性的含义：

• [SugarTable("sys_user")]给实体指定数据库表名。不写的话，默认会使用类名User，但表名一般建议显式指定，避免大小写和复数问题。
• [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]表示主键并且是自增列。
• Length用来指定字符串长度，默认在 SqlServer 里是 max，在 Sqlite 里没有严格长度限制，但还是建议统一标注。
• IsNullable控制字段能否为空，int?这类可空类型建议配合使用。

3.2 初始化表结构

在建表之前，先要确保数据库文件存在。如果你用的是 Sqlite，SqlSugar 提供了很方便的建库方法：

var db = DbFactory.Create(); // 如果数据库不存在，自动创建 db.DbMaintenance.CreateDatabase(); // 创建表（如果表不存在） db.CodeFirst.InitTables(typeof(User));

InitTables只会创建不存在的表，不会破坏已有表的数据。重复执行是安全的，实测在启动阶段放一次即可，我会在服务启动时调用一次，然后把建表逻辑当作系统初始化的一部分。

这里要提醒一下：InitTables负责的是“表不存在就建表”，它不会对已有表自动添加缺失的字段。如果实体增加了新列而表已经存在，InitTables不会帮你补列，需要手工写DbMaintenance.AddColumn或通过迁移脚本处理。这个在早期开发时尤其容易遇到，改实体改得很开心，结果运行报列不存在，才发现忘了同步表结构。

3.3 命名风格：驼峰与小写之间的选择

SqlSugar 默认生成的表和列名会尽量保持实体属性名，比如UserName对应列UserName。但很多数据库习惯小写下划线风格，比如user_name。在真实项目里，我建议从第一天就决定好命名风格，不然后面切换数据库时会很痛苦。

你可以通过MoreSettings配置统一处理：

MoreSettings = new ConnMoreSettings { IsAutoToLower = true }

如果打开IsAutoToLower，生成的列名会小写化，但不会有下划线转换，UserName会变成username。如果你想要user_name这种映射，最稳妥的方式还是在实体特性里手动指定列名：

[SugarColumn(ColumnName = "user_name")] public string UserName { get; set; }

手动指定虽然代码多了点，但语义最清晰，而且数据库迁移和后续维护时一眼就能看懂对应关系。

4. 开箱即用的 CRUD 实战：插入、查询、更新、删除

4.1 插入数据：单条插入与返回自增主键

SqlSugar 的插入 API 是Insertable链式写法，最简单的方式直接传实体：

var db = DbFactory.Create(); var user = new User { UserName = "test001", PasswordHash = "abc123", Phone = "13800000000", CreateTime = DateTime.Now, Status = 1 }; // 插入并返回影响行数 int rows = db.Insertable(user).ExecuteCommand(); // 插入并返回自增主键 int newId = db.Insertable(user).ExecuteReturnIdentity();

在实际业务里，我几乎总是用ExecuteReturnIdentity()，因为插入后立刻拿主键是高频需求，比如生成订单之后要带出订单号去写关联表。ExecuteCommand()返回的受影响行数通常为 1，但意义不大。

批量插入就更方便了：

var list = new List<User> { user1, user2, user3 }; db.Insertable(list).ExecuteCommand();

SqlSugar 对批量插入会自动拆分或合并 SQL，不需要自己做循环。数据量特别大时，可以用后面提到的BulkCopy进一步提升性能。

4.2 查询：按主键、按条件、组合查询

查询是最常用到的能力。Queryable提供的链式方法几乎能满足日常所有需求：

// 按主键查询 var user1 = db.Queryable<User>().InSingle(1); // 按单条件查询，返回第一条 var user2 = db.Queryable<User>() .Where(u => u.UserName == "test001") .First(); // 按多条件查询，返回列表 var userList = db.Queryable<User>() .Where(u => u.Status == 1 && u.CreateTime >= DateTime.Today) .OrderBy(u => u.CreateTime, OrderByType.Desc) .ToList(); // 判断是否存在 bool exists = db.Queryable<User>() .Any(u => u.Phone == "13800000000");

这里的Where直接使用 Lambda 表达式，跟 EF Core 很类似，但有几点不一样。SqlSugar 的.Where()支持多种重载，比如字符串式的"status=@status"，甚至可以传一个List<IConditionalModel>做动态条件组合。

如果查询条件不确定，我更推荐用动态条件模型的方式，这样可以避免拼字符串的麻烦：

var conditions = new List<IConditionalModel>(); if (!string.IsNullOrEmpty(keyword)) { conditions.Add(new ConditionalModel { FieldName = "user_name", ConditionalType = ConditionalType.Like, FieldValue = keyword }); } var result = db.Queryable<User>() .Where(conditions) .ToList();

这种写法在写高级筛选、报表查询时非常有用，条件拼装完全是由业务动态决定的。

4.3 更新与删除的正确姿势

更新操作有两种常见写法，各有用处。直接传实体：

var user = db.Queryable<User>().InSingle(1); user.Phone = "13900000000"; db.Updateable(user).ExecuteCommand();

这种写法会更新实体的所有字段，如果实体里的PasswordHash等字段已经被加载，就会一并更新。另一种方式是指定字段更新，适合只改某几个列的轻量操作：

db.Updateable<User>() .SetColumns(u => new User { Phone = "13900000000", Status = 0 }) .Where(u => u.Id == 1) .ExecuteCommand();

删除同样简单：

// 按主键删除 db.Deleteable<User>().In(1).ExecuteCommand(); // 按条件删除 db.Deleteable<User>() .Where(u => u.Status == 0) .ExecuteCommand();

注意：真实项目里业务数据建议优先使用逻辑删除，也就是给表加一个IsDeleted字段，查询时默认过滤IsDeleted == false。SqlSugar 也提供了全局过滤器，可以在客户端配置里设置QueryFilter，统一处理软删除，避免每个查询都手动加条件。

db.QueryFilter.Add(new TableFilterItem<User>(it => it.Status != -1));

判断一个 ORM 是否顺手，往往不在基本 CRUD，而在这些细小的便利功能上。SqlSugar 的全局过滤、逻辑删除、雪花ID等设计都贴近真实业务，这才是它“开箱即用”的真正含义。

5. 真实项目绕不开的进阶操作：分页、事务与批量写

5.1 分页查询：ToPageList 最实用

Web API 接口基本绕不开分页。SqlSugar 的.ToPageList是我用得最多的一个方法，它自己会去统计总数，不需要你额外执行一条 count：

int pageIndex = 1; int pageSize = 20; int total = 0; var pageList = db.Queryable<User>() .Where(u => u.Status == 1) .OrderBy(u => u.Id, OrderByType.Desc) .ToPageList(pageIndex, pageSize, ref total);

执行完后，total就是符合条件的数据总量，pageList就是当前页数据。业务层可以直接把这两个值返回给前端，非常好用。如果是异步接口，使用.ToPageListAsync即可。

分页背后的 SQL 会根据数据库类型做适配。SqlServer 会生成OFFSET/FETCH或ROW_NUMBER语句，Sqlite 则使用LIMIT/OFFSET，你不必关心具体方言。

5.2 事务控制：UseTran 与代码风格

后端项目中经常遇到多步操作需要保证原子性的场景，比如创建订单时同时更新库存和写流水表。SqlSugar 的事务用起来很轻量：

try { db.Ado.BeginTran(); var orderId = db.Insertable(order).ExecuteReturnIdentity(); db.Updateable<Product>() .SetColumns(p => new Product { Stock = p.Stock - 1 }) .Where(p => p.Id == productId) .ExecuteCommand(); db.Ado.CommitTran(); } catch (Exception ex) { db.Ado.RollbackTran(); throw; }

如果你的操作都在一个链接风格里，也可以用UseTran这种更简明的写法：

var result = db.UseTran(() => { var orderId = db.Insertable(order).ExecuteReturnIdentity(); db.Updateable<Product>() .SetColumns(p => new Product { Stock = p.Stock - 1 }) .Where(p => p.Id == productId) .ExecuteCommand(); }); if (!result.IsSuccess) { // 处理失败 }

事务的粒度不能太大，尽量控制在一个业务操作的范围内，否则会带来锁等待和性能问题。

5.3 批量写入与性能优化

在导入、初始化、日志写入等场景下，几千条数据的插入如果逐条执行会非常慢。SqlSugar 提供了BulkCopy：

db.Fastest<User>().BulkCopy(userList);

这个方法在 SqlServer、MySQL 等数据库上性能提升很显著。不过 Sqlite 对BulkCopy的支持有限，如果你用 Sqlite 做演示或单机应用，可能有版本或驱动上的限制。稳妥起见，在快速开发阶段可以直接用Insertable(list)，等数据量真的大起来再切到正式数据库。

5.4 异步 API 与性能注意事项

SqlSugar 的异步 API 是真正的异步，例如ExecuteCommandAsync、ToListAsync、ToPageListAsync。在 Web API 中使用异步能避免线程阻塞，提升整体吞吐。我实际测试过，高并发场景下同步和异步的差异很明显，特别是在数据库响应较慢时。

但要注意：异步和事务混用时需要小心，尽量保证同一事务内的操作都在同一个线程上下文中流转，避免在async/await时因为上下文切换导致事务状态判断异常。如果是复杂事务逻辑，我倾向于同步写法，简单又直观。

6. 集成过程中踩过的一些坑与避坑建议

6.1 数据库类型与连接字符串不匹配

这算是最常见的起步问题。Sqlite、SqlServer、MySQL 的连接字符串差异很大，一旦DbType和实际字符串不匹配，跑起来就会报奇怪的错误。比如用了DbType.SqlServer却传了DataSource=app.db，这样启动时就能看到连接失败。

建议把连接字符串统一放到配置中心或appsettings.json里，不要写死在代码中。同时项目里准备一个小工具或启动时自检方法，快速检查数据库连通性。

6.2 CodeFirst 扫描不到实体

使用CodeFirst.InitTables时，如果实体定义在另一个程序集里，你需要通过反射把类型传进去：

db.CodeFirst.InitTables(typeof(User), typeof(Order));

如果实体特别多，可以扫描整个程序集：

var entityTypes = typeof(BaseEntity).Assembly.GetTypes() .Where(t => t.IsClass && !t.IsAbstract && t.GetCustomAttribute<SugarTable>() != null) .ToArray(); db.CodeFirst.InitTables(entityTypes);

很多“表没有创建”的问题其实都是这个原因，不是 SqlSugar 没生效，而是类型没有扫描到。

6.3 线程安全与连接管理

SqlSugarClient 是线程安全的，这一点官方有说明，我实测在多线程并发调用下没有出现问题。但前提是你没有在代码里干一些自己破坏线程安全的事情，比如多个线程同时修改同一个客户端的配置项，或者在执行过程中改变ConnectionConfig的属性。

还有一个常见的连接泄漏场景：如果IsAutoCloseConnection设置为 false，并且你不小心漏掉了手动释放连接，那么高并发情况下连接数会迅速占满。所以尽量保持IsAutoCloseConnection=true，这是最省心的做法。

6.4 跨数据库切换时的“隐形差异”

SqlSugar 帮你统一了大部分 API，但数据库本身的差异还是存在的。比如日期函数、字符串函数、大小写敏感规则，在不同数据库上执行效果可能不同。写业务代码时尽量避免依赖特定数据库的 SQL 特性，如果一定要用复杂函数，建议使用 SqlSugar 的SqlFunc内置函数，这样切换数据库时能自动翻译。

我之前在一个模块里直接用了 SqlServer 的GETDATE()，换成 Sqlite 的时候就报错。后来改用SqlFunc.GetDate()才解决。这类小差异在开发初期不容易暴露，往往是切换数据库时才突然冒出来，所以从第一天起就要有跨库意识地写代码。

6.5 实体扩展字段与不存在的列

CodeFirst 模式下，如果实体有一个属性比如int? TempValue，你没有标[SugarColumn(IsIgnore=true)]，那么建表时它会尝试创建对应列。若表已存在但缺少这个列，查询时也可能会报“列不存在”的错误。

解决方法是明确标注忽略字段：

[SugarColumn(IsIgnore = true)] public string TempValue { get; set; }

这个坑在团队协作开发时尤其容易出现某位同事加了一个计算属性，然后全组数据访问都崩了。建议在实体设计约定里写清楚：非表字段必须标注IsIgnore。

7. 从零到跑通的流程心得与后续建议

按照我的经验，一个新项目里集成 SqlSugar 的完整流程可以这样安排。第一步，搭建项目结构，添加SqlSugarCore包；第二步，在appsettings.json里配置连接字符串和DbType；第三步，定义实体类并标注特性；第四步，编写DbFactory，启动时执行数据库和表初始化；第五步，写一个最小 Controller 或服务验证 CRUD；第六步，再逐步加入分页、事务、批量操作等进阶能力。

整个流程熟练之后，从零到跑通一张表的 CRUD 通常不超过半个小时。这也是我喜欢 SqlSugar 的原因，它把“能用”和“好用”之间的距离拉得很近。

如果你也想在 .NET Core 项目里选它，我还有几个实操层面的建议。首先，开发阶段强烈建议打开 Aop 日志，在 SqlSugarClient 上挂一个OnLogExecuting事件，把生成的 SQL 输出到控制台，这样排查问题效率会非常高：

db.Aop.OnLogExecuting = (sql, pars) => { Console.WriteLine(sql); };

其次，建议从 Sqlite 起步，因为它零部署、零配置，很适合做功能验证。等到业务逻辑稳定后，再根据生产环境切换到 SqlServer 或 MySQL，SqlSugar 的跨库支持能让切换成本尽量降低。最后，不要因为写起来简单就忽略数据库设计，表和索引的合理性、是否用软删除、字段命名是否统一，这些依然决定项目的长期维护成本。快只是手段，稳才是目标。