深耕 .NET 数据操作：SqlSugar 从入门到实战的全方位指南

Ne0inhk

— 11 min read
深耕 .NET 数据操作：SqlSugar 从入门到实战的全方位指南

在 .NET 生态中，ORM（对象关系映射）框架是连接代码与数据库的核心桥梁，既能简化原生 SQL 的繁琐编写，又能兼顾开发效率与性能优化。提及 .NET ORM，EF Core、Dapper 早已广为人知，但 SqlSugar 作为一款轻量、高性能的国产框架，凭借简洁的 API、全面的功能与极低的学习成本，逐渐成为中小型项目与快速开发场景的优选。本文将从基础认知、环境搭建、核心操作到进阶技巧，带你完整解锁 SqlSugar 的实用价值。

一、初识 SqlSugar：什么是它的核心竞争力？

SqlSugar 是由国内开发者 Sunkaixuan 维护的开源 .NET ORM 框架，专注于“轻量无依赖、高性能、易上手”三大核心目标，支持 .NET Framework 4.6+ 及 .NET Core 2.0+ 全版本，兼容 SQL Server、MySQL、PostgreSQL、SQLite、Oracle 等主流数据库，甚至支持达梦等国产数据库，适配多场景开发需求。

相较于同类框架，它的核心优势尤为突出：

  • 性能出众：底层优化充分，采用编译缓存、SQL 语句优化等机制，性能接近原生 ADO.NET，远超多数同类 ORM，批量操作性能更是优于 Dapper 等框架。
  • 易用性极强：API 设计简洁直观，支持链式编程，开发者无需深入钻研复杂配置，就能快速实现数据库操作，学习成本远低于 EF Core。
  • 功能全面且灵活：兼顾基础 CRUD 与高级特性，支持事务管理、分页查询、多表联查、分表分库、缓存控制、数据库迁移（CodeFirst）等，同时允许开发者直接控制 SQL 生成，兼顾灵活性与便捷性。
  • 轻量无依赖：核心库体积仅几百 KB，无需额外依赖，可无缝集成到各类 .NET 项目中，无冗余负担。

目前，SqlSugar 在 Github 的 Star 数量仅次于 EF Core 与 Dapper，成为 .NET 生态中极具竞争力的 ORM 框架，尤其适合中小型项目、企业内部管理系统等需要快速落地的场景。

二、环境搭建：3 步完成 SqlSugar 集成

SqlSugar 提供两种核心 NuGet 包，分别适配不同 .NET 框架，安装配置过程极简，全程无需复杂操作。

2.1 选择合适的 NuGet 包

根据项目框架选择对应包，避免版本不兼容问题：

  • .NET Framework 4.6+ 项目：安装 SqlSugar 包；
  • .NET Core 2.0+、.NET 5/6/7/8/9 项目：安装 SqlSugarCore 包（推荐，轻量适配跨平台场景）；
  • 特定数据库扩展：若使用 MySQL，需额外安装 MySqlConnector 驱动包，其他数据库无需额外安装驱动。

2.2 安装方式

支持两种常用安装方式，按需选择即可：

  1. 图形化界面安装：打开 Visual Studio，右键点击项目 → 管理 NuGet 程序包 → 浏览，搜索对应包名，点击“安装”；
  2. 命令行安装：打开程序包管理器控制台，输入对应命令：
    • .NET Framework 项目：Install-Package SqlSugar；
    • .NET Core/.NET 5+ 项目：Install-Package SqlSugarCore；
    • .NET CLI 安装：dotnet add package SqlSugarCore（适配 .NET Core 及以上版本）。

2.3 初始化数据库连接

SqlSugar 的核心操作都通过 SqlSugarClient（非线程安全）或 SqlSugarScope（线程安全，适合单例/依赖注入）完成，初始化时需配置连接参数。以下是两种常见初始化方式：

方式 1：基础初始化（非 IOC 场景）
usingSqlSugar;// 1. 配置连接参数var connectionConfig =newConnectionConfig{ ConnectionString ="Server=localhost;Database=TestDB;User Id=sa;Password=your_password;",// 数据库连接字符串 DbType = DbType.SqlServer,// 数据库类型（可切换为MySql、PostgreSQL等） IsAutoCloseConnection =true,// 自动关闭连接，避免连接泄露 InitKeyType = InitKeyType.Attribute // 从实体类特性中读取主键、自增等配置};// 2. 创建客户端实例（二选一）// 非线程安全，适合WinForm等单线程场景，每次操作可new实例var db =newSqlSugarClient(connectionConfig);// 线程安全，适合ASP.NET Core等多线程场景，可全局共享// var db = new SqlSugarScope(connectionConfig);// 可选：配置SQL日志输出（调试时查看生成的SQL语句） db.Aop.OnLogExecuting =(sql, pars)=>{ Console.WriteLine($"执行SQL：{sql}"); Console.WriteLine($"参数：{string.Join(",", pars.Select(p =>$"{p.ParameterName}={p.Value}"))}");};
方式 2：IOC 注入（ASP.NET Core 场景）

对于 Web 项目，推荐通过依赖注入全局管理 SqlSugarClient，提升代码可维护性：

// Program.cs 中配置var builder = WebApplication.CreateBuilder(args);// 注入 SqlSugarClient（单例模式，使用SqlSugarScope保证线程安全） builder.Services.AddSingleton<ISqlSugarClient>(sp =>{var connectionConfig =newConnectionConfig{ ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection"), DbType = DbType.SqlServer, IsAutoCloseConnection =true, InitKeyType = InitKeyType.Attribute };returnnewSqlSugarScope(connectionConfig);});var app = builder.Build();

之后在控制器中直接注入 ISqlSugarClient 即可使用，无需重复初始化。

三、核心实战：SqlSugar 基础操作（CRUD）

完成初始化后，先定义实体类与数据库表映射，再通过链式 API 实现基础 CRUD 操作，全程无需编写原生 SQL。

3.1 定义实体类（基于特性映射）

通过 SugarTable（类级别）、SugarColumn（属性级别）特性，实现实体类与数据库表的映射，支持自定义表名、字段名、主键、自增等配置：

usingSqlSugar;// 映射到数据库表：Users（若不指定，默认使用类名）[SugarTable("Users")]publicclassUser{// 主键，自增（IsIdentity=true仅适用于支持自增的数据库）[SugarColumn(IsPrimaryKey =true, IsIdentity =true)]publicint Id {get;set;}// 映射字段名：user_name，长度50，非空[SugarColumn(ColumnName ="user_name", Length =50, IsNullable =false)]publicstring UserName {get;set;}// 密码字段，长度100，允许为空[SugarColumn(ColumnName ="user_pwd", Length =100)]publicstring Password {get;set;}// 年龄，默认值0[SugarColumn(DefaultValue ="0")]publicint Age {get;set;}// 注册时间，默认值为当前时间（数据库函数）[SugarColumn(ColumnName ="reg_time", DefaultValue ="GETDATE()")]publicDateTime RegTime {get;set;}// 忽略该字段，不映射到数据库[SugarColumn(IsIgnore =true)]publicstring TempData {get;set;}}

可选：通过 CodeFirst 自动创建数据库表，无需手动建表：

// 自动创建Users表（若不存在） db.CodeFirst.InitTables<User>();

3.2 基础 CRUD 操作

SqlSugar 的 CRUD 操作均支持链式调用，语法简洁，可灵活组合条件。

（1）新增操作（Insert）
// 1. 单条新增，返回自增IDvar user =newUser{ UserName ="Alice", Password ="123456", Age =25};int newId = db.Insertable(user).ExecuteReturnIdentity();// 2. 批量新增（性能优于循环单条插入）var userList =newList<User>{newUser{ UserName ="Bob", Password ="654321", Age =30},newUser{ UserName ="Charlie", Password ="abc123", Age =28}};int affectedRows = db.Insertable(userList).ExecuteCommand();
（2）查询操作（Query）

支持单条查询、条件查询、分页查询、多表联查等多种场景，同时支持原生 SQL 查询：

// 1. 单条查询（根据主键）var user = db.Queryable<User>().In(1).First();// 或根据条件查询单条var user = db.Queryable<User>().Where(u => u.UserName =="Alice").FirstOrDefault();// 2. 条件查询（查询年龄>20的用户，按注册时间降序）var userList = db.Queryable<User>().Where(u => u.Age >20).OrderByDesc(u => u.RegTime).ToList();// 3. 分页查询（分页核心，无需手动计算页码、条数）int pageIndex =1;// 当前页码int pageSize =10;// 每页条数var pageResult = db.Queryable<User>().Where(u => u.Age >18).ToPageList(pageIndex, pageSize,outint totalCount);// totalCount：总条数，pageResult：当前页数据// 4. 多表联查（以User和Order为例，一对多关系）var result = db.Queryable<User, Order>((u, o)=> u.Id == o.UserId).Select((u, o)=>new{ UserId = u.Id, UserName = u.UserName, OrderId = o.Id, OrderName = o.OrderName }).ToList();// 5. 原生SQL查询（返回实体类或匿名对象）var sql ="SELECT * FROM Users WHERE Age > @Age";var userList = db.Ado.SqlQuery<User>(sql,new{ Age =20});
（3）修改操作（Update）

支持全量修改、局部修改、批量修改，可精准控制修改字段：

// 1. 局部修改（仅修改指定字段）int affectedRows = db.Updateable<User>().SetColumns(u => u.Age ==26)// 要修改的字段.Where(u => u.Id ==1)// 修改条件.ExecuteCommand();// 2. 全量修改（根据实体）var user = db.Queryable<User>().In(1).First(); user.UserName ="Alice_Update"; affectedRows = db.Updateable(user).ExecuteCommand();// 3. 批量修改 affectedRows = db.Updateable<User>().SetColumns(u => u.Password =="new_pwd").Where(u => u.Age >30).ExecuteCommand();
（4）删除操作（Delete）
// 1. 根据主键删除int affectedRows = db.Deleteable<User>().In(1).ExecuteCommand();// 2. 根据条件删除 affectedRows = db.Deleteable<User>().Where(u => u.UserName =="Bob").ExecuteCommand();// 3. 批量删除 affectedRows = db.Deleteable<User>().In(newList<int>{2,3}).ExecuteCommand();

四、进阶特性：解锁 SqlSugar 高级能力

除基础操作外，SqlSugar 还提供了诸多实用高级特性，覆盖复杂业务场景需求。

4.1 事务管理

支持手动事务与自动事务，确保多步数据库操作的原子性，需注意：事务操作必须使用同一个 SqlSugarClient 实例：

// 手动事务（推荐，灵活控制）try{ db.Ado.BeginTran();// 开启事务// 执行多步操作 db.Insertable(newUser{ UserName ="David", Age =22}).ExecuteReturnIdentity(); db.Updateable<User>().SetColumns(u => u.Age ==23).Where(u => u.Id ==4).ExecuteCommand(); db.Ado.CommitTran();// 提交事务}catch(Exception ex){ db.Ado.RollbackTran();// 回滚事务 Console.WriteLine($"事务执行失败：{ex.Message}");}

4.2 缓存控制

内置内存缓存，支持自定义 Redis 缓存，减少数据库查询压力，提升接口性能：

// 基础内存缓存（缓存10分钟）var userList = db.Queryable<User>().WithCache(10*60)// 缓存时间（秒）.ToList();// 自定义缓存键，便于后续删除缓存var cacheKey ="user_list_age_20";var userList = db.Queryable<User>().Where(u => u.Age >20).WithCache(10*60, cacheKey).ToList();// 删除指定缓存 db.RemoveCache(cacheKey);// 集成Redis缓存（需额外配置Redis连接）// 此处省略Redis配置，可参考SqlSugar官方文档

4.3 分表分库

支持水平分表、垂直分表与分库操作，适配大数据量场景，无需修改核心业务代码：

// 水平分表（按时间分表，如Users_2024、Users_2025）var user =newUser{ UserName ="Eve", Age =24}; db.Insertable(user).AS("Users_"+ DateTime.Now.Year)// 动态指定表名.ExecuteReturnIdentity();// 分库操作（需配置多数据库连接，通过ConfigId区分）// 此处省略多库配置，可通过ConnectionConfig的ConfigId实现

五、框架对比：SqlSugar 适合哪些场景？

在 .NET 生态中，EF Core、Dapper、SqlSugar 是最常用的三款 ORM 框架，三者定位不同，适配场景各有侧重，以下是核心维度对比：

对比维度EF CoreDapperSqlSugar
定位重量级全功能 ORM，适配 DDD 复杂场景轻量级，极致性能，需手动写 SQL中轻量，兼顾易用性与性能
性能中等，复杂查询性能较差极高，接近原生 ADO.NET优秀，批量操作优于 Dapper
易用性学习曲线陡，配置复杂需熟悉 SQL，灵活但繁琐学习成本低，链式 API 简洁
核心优势生态完善，支持复杂关系映射、数据库迁移性能极致，轻量无依赖功能全面，兼顾便捷性与灵活性
适配场景大型企业级应用、复杂业务系统对性能极致要求，需灵活控制 SQL 的场景中小型项目、快速开发、企业内部系统
总结：若项目追求快速落地、无需复杂配置，同时需要兼顾性能与功能全面性，SqlSugar 是最优选择；若需构建 DDD 架构的复杂系统，可选择 EF Core；若对性能有极致要求且愿意手动编写 SQL，Dapper 更合适。

六、总结与注意事项

SqlSugar 作为一款国产 ORM 框架，完美平衡了易用性、性能与功能全面性，无需复杂配置就能快速上手，既能满足基础 CRUD 需求，又能支撑分表分库、事务管理、缓存控制等高级场景，尤其适合中小型 .NET 项目与快速开发场景。

使用过程中需注意以下几点：

  • 确保 SqlSugarClient 实例的线程安全，Web 项目优先使用 SqlSugarScope 与依赖注入；
  • 事务操作需使用同一个客户端实例，否则事务会失效；
  • 切换数据库时，只需修改 ConnectionConfig 的 DbType 与连接字符串，无需修改业务代码；
  • 调试时可开启 SQL 日志输出，便于排查 SQL 生成问题。

总体而言，SqlSugar 是 .NET 开发者提升数据操作效率的得力工具，兼顾“快开发”与“高性能”，值得深入学习与应用。后续可结合官方文档，探索更多高级特性，适配更复杂的业务场景。

Could not load content