SQLSugar简介、使用方法、核心类与API及示例演示

一、SQLSugar 简介

先说几个关键点——SQLSugar 是 .NET 生态里一个相当轻量、性能也很能打的 ORM 框架，由国内团队持续维护。它的核心思路很清晰：把 C# 里的实体类跟数据库表对上号，开发者就能用面向对象的方式去操作数据库，做增删改查、写查询、搞事务，基本不用碰原生 SQL——当然，真需要写 SQL 的时候，它也给你留了口子。

它到底凭什么值得关注？

• 多数据库支持：SQL Server、MySQL、Oracle、PostgreSQL、SQLite，甚至达梦这样的国产数据库，都支持。切换数据库？改个配置就行。
• 高性能：编译缓存、SQL 优化这些手段都用上了，性能接近原生 ADO.NET，比很多同类 ORM 快得多。
• 易用性：API 设计得挺简洁，链式查询写起来很顺手，比如 Queryable().Where().OrderBy()，新手学起来也不费劲。
• 功能全面：分表分库、导航属性（多表关联）、批量操作、事务、数据库迁移（CodeFirst），这些高级特性一个不少。
• 轻量无依赖：核心库只有几百 KB，集成到 .NET Framework、.NET Core、.NET 5+ 项目里都很轻松。

二、基本使用方法

2.1 安装

通过 NuGet 安装核心包：

Install-Package SqlSugarCore  # .NET Core/.NET 5+# 或针对特定数据库安装扩展包（如MySQL）Install-Package MySqlConnector  # MySQL驱动

2.2 初始化数据库连接

初始化连接用的是 SqlSugarClient 或 SqlSugarScope，核心是那个 ConnectionConfig 配置对象：

using SqlSugar;using System;​// 1. 定义连接配置var config = new ConnectionConfig{    ConnectionString = "Server=.;Database=TestDB;Uid=sa;Pwd=123456;", // 连接字符串    DbType = DbType.SqlServer, // 数据库类型（如DbType.MySql）    IsAutoCloseConnection = true, // 自动关闭连接（推荐开启）    InitKeyType = InitKeyType.Attribute // 从实体特性读取主键/自增配置};​// 2. 初始化客户端（二选一）// 方式1：SqlSugarClient（非线程安全，每次操作new实例或通过IOC注入Scope）var db = new SqlSugarClient(config);​// 方式2：SqlSugarScope（线程安全，适合单例模式，如ASP.NET Core注入）// var db = new SqlSugarScope(config);

2.3 核心操作流程

• 定义实体类（映射数据库表）；
• 通过客户端对象（db） 调用 API 执行数据库操作（CRUD、查询等）。

三、关键类与作用

四、关键 API 与示例

4.1 实体类定义（基于特性）

先定义与数据库表映射的实体类，以“用户表”为例：

using SqlSugar;using System;​// 映射到数据库表：Sys_User[SugarTable("Sys_User")]public class User{    // 主键（自增）    [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]    public int Id { get; set; }​    // 用户名（字段名：User_Name，长度50，非空）    [SugarColumn(ColumnName = "User_Name", Length = 50, IsNullable = false)]    public string UserName { get; set; }​    // 密码（字段名：User_Pwd，加密存储）    [SugarColumn(ColumnName = "User_Pwd", Length = 100)]    public string Password { get; set; }​    // 年龄（默认值0）    [SugarColumn(DefaultValue = "0")]    public int Age { get; set; }​    // 注册时间（默认值：当前时间）    [SugarColumn(ColumnName = "Reg_Time", DefaultValue = "GETDATE()")]    public DateTime RegTime { get; set; }​    // 忽略字段（不映射到数据库）    [SugarColumn(IsIgnore = true)]    public string TempData { get; set; }}

4.2 CRUD 核心 API

1. 新增（Insert）

// 单条新增var user = new User {     UserName = "张三",     Password = "123456",     Age = 25 };// 执行新增并返回自增IDint newId = db.Insertable(user).ExecuteReturnIdentity(); ​// 批量新增（性能优于循环单条插入）var userList = new List{    new User{ UserName = "李四", Password = "654321", Age = 30 },    new User{ UserName = "王五", Password = "abc123", Age = 28 }};bool isSuccess = db.Insertable(userList).ExecuteCommand() > 0; // 返回影响行数

2. 查询（Query）

// 2.1 单条查询（根据条件）User user = db.Queryable()              .Where(u => u.UserName == "张三") // 条件              .First(); // 返回第一条​// 2.2 列表查询（带排序）List users = db.Queryable()                     .Where(u => u.Age > 25) // 年龄>25                     .OrderBy(u => u.RegTime, OrderByType.Desc) // 按注册时间倒序                     .ToList(); // 返回列表​// 2.3 分页查询（第2页，每页10条）int pageIndex = 2;int pageSize = 10;var pageResult = db.Queryable()                   .ToPageList(pageIndex, pageSize, out int totalCount); // totalCount：总记录数（用于分页控件）​// 2.4 聚合查询（统计、求和等）int total = db.Queryable().Count(); // 总记录数int maxAge = db.Queryable().Max(u => u.Age); // 最大年龄decimal a vgAge = db.Queryable().A verage(u => u.Age); // 平均年龄

3. 更新（Update）

// 3.1 全量更新（根据主键）user.Age = 26; // 修改年龄bool updateSuccess = db.Updateable(user).ExecuteCommand() > 0;​// 3.2 局部更新（只更新指定字段，性能更优）bool partialUpdate = db.Updateable()                       .SetColumns(u => u.Age == 27) // 只更新Age字段                       .Where(u => u.UserName == "张三") // 条件                       .ExecuteCommand() > 0;

4. 删除（Delete）

// 4.1 根据实体删除（根据主键）bool deleteByEntity = db.Deleteable(user).ExecuteCommand() > 0;​// 4.2 根据条件删除bool deleteByWhere = db.Deleteable()                       .Where(u => u.Age < 18) // 删除年龄<18的用户                       .ExecuteCommand() > 0;

4.3 高级查询 API

1. 子查询

// 查询“注册时间在最近30天”且“年龄>平均年龄”的用户var subQuery = db.Queryable().Select(u => SqlFunc.AggregateA verage(u.Age)); // 子查询：平均年龄​var result = db.Queryable()               .Where(u => u.RegTime >= DateTime.Now.AddDays(-30)                         && u.Age > subQuery) // 关联子查询               .ToList();

2. 多表关联查询（导航属性）

假设有订单表（Order）与用户表（User）关联（一对多）：

// 订单实体（含导航属性）[SugarTable("Orders")]public class Order{    [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]    public int Id { get; set; }    public int UserId { get; set; } // 外键（关联User.Id）    // 导航属性：关联用户（一对一）    [Na vigate(Na vigateType.OneToOne, nameof(UserId))]     public User User { get; set; } }// 查询订单时同时加载关联的用户信息var orders = db.Queryable()               .Includes(o => o.User) // 加载导航属性               .Where(o => o.Id > 100)               .ToList();// 使用关联数据foreach (var order in orders){    Console.WriteLine($"订单ID：{order.Id}，用户名：{order.User.UserName}");}

4.4 事务操作

try{    // 开启事务    db.Ado.BeginTran();    // 执行多个操作（新增用户+新增订单）    var newUser = new User { UserName = "赵六", Password = "111", Age = 35 };    int userId = db.Insertable(newUser).ExecuteReturnIdentity();    var newOrder = new Order { UserId = userId, OrderNo = "ORD_123" };    db.Insertable(newOrder).ExecuteCommand();    // 提交事务    db.Ado.CommitTran();}catch (Exception ex){    // 回滚事务    db.Ado.RollbackTran();    Console.WriteLine($"事务失败：{ex.Message}");}

五、两种客户端模式对比（SqlSugarClient vs SqlSugarScope）

六、总结

SQLSugar 的核心优势可以概括为三句话：高性能、易上手、功能全。它通过简洁的 API，大大简化了 .NET 项目里的数据库操作。实际用起来，最重要的是掌握三个环节：实体类定义（特性配置）、客户端初始化，以及 CRUD / 查询 API 的使用。不管你是做简单的单表操作，还是搞复杂的多表关联、事务处理，SQLSugar 都能提供高效的解决方案，从小项目到大企业系统，都能用得上。