一、SQLSugar 简介
SQLSugar 是一款 轻量级、高性能的 .*** ORM 框架，由国内团队开发维护，专注于简化数据库操作，同时兼顾灵活性与性能。它通过对象关系映射（ORM）将 C# 实体类与数据库表关联，允许开发者以面向对象的方式完成 CRUD、查询、事务等操作，无需编写原生 SQL（或仅需少量 SQL）。
核心特点：
-
多数据库支持：兼容 SQL Server、MySQL、Oracle、PostgreSQL、SQLite、达梦等主流数据库，切换数据库只需修改配置。
-
高性能：采用编译缓存、SQL 优化等机制，性能接近原生 ADO.***，远超多数同类 ORM。
-
易用性：API 设计简洁，支持链式查询（如
Queryable<T>().Where().OrderBy()），学习成本低。 -
功能全面：支持分表分库、导航属性（多表关联）、批量操作、事务、数据库迁移（CodeFirst）等高级特性。
-
轻量无依赖：核心库体积仅几百 KB，可无缝集成到 .*** Framework、.*** Core、.*** 5+ 等项目中。
二、基本使用方法
2.1 安装
通过 NuGet 安装核心包：
Install-Package SqlSugarCore # .*** Core/.*** 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.*** Core注入）
// var db = new SqlSugarScope(config);
2.3 核心操作流程
-
定义实体类（映射数据库表）；
-
通过客户端对象（db） 调用 API 执行数据库操作（CRUD、查询等）。
三、关键类与作用
| 类 / 接口 | 作用说明 | 核心场景 |
|---|---|---|
SqlSugarClient |
数据库操作核心类，提供所有 ORM API | 非单例场景（如 WinForm），每次操作 new 实例 |
SqlSugarScope |
线程安全的客户端类（基于 AsyncLocal 实现） | 单例场景（如ASP.*** Core），全局共享实例 |
ISqlSugarClient |
客户端接口，用于依赖注入（解耦） | 项目中通过接口调用，便于测试和替换 |
ConnectionConfig |
连接配置类，存储数据库连接信息 | 初始化客户端时必传，配置连接字符串、数据库类型等 |
SugarTable |
类级别特性，指定实体对应的数据表名 | 实体类定义时，映射表名（如[SugarTable("Users")]） |
SugarColumn |
属性级别特性，配置字段属性（主键、长度等） | 实体属性定义时，指定字段名、自增、默认值等 |
四、关键 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
};
// 执行新增并返回自增ID
int newId = db.Insertable(user).ExecuteReturnIdentity();
// 批量新增（性能优于循环单条插入）
var userList = new List<User>
{
new User{ UserName = "李四", Password = "654321", Age = 30 },
new User{ UserName = "王五", Password = "abc123", Age = 28 }
};
bool isSu***ess = db.Insertable(userList).Execute***mand() > 0; // 返回影响行数
2. 查询（Query）
// 2.1 单条查询（根据条件） User user = db.Queryable<User>() .Where(u => u.UserName == "张三") // 条件 .First(); // 返回第一条 // 2.2 列表查询（带排序） List<User> users = db.Queryable<User>() .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<User>() .ToPageList(pageIndex, pageSize, out int totalCount); // totalCount：总记录数（用于分页控件） // 2.4 聚合查询（统计、求和等） int total = db.Queryable<User>().Count(); // 总记录数 int maxAge = db.Queryable<User>().Max(u => u.Age); // 最大年龄 decimal avgAge = db.Queryable<User>().Average(u => u.Age); // 平均年龄
3. 更新（Update）
// 3.1 全量更新（根据主键） user.Age = 26; // 修改年龄 bool updateSu***ess = db.Updateable(user).Execute***mand() > 0; // 3.2 局部更新（只更新指定字段，性能更优） bool partialUpdate = db.Updateable<User>() .SetColumns(u => u.Age == 27) // 只更新Age字段 .Where(u => u.UserName == "张三") // 条件 .Execute***mand() > 0;
4. 删除（Delete）
// 4.1 根据实体删除（根据主键） bool deleteByEntity = db.Deleteable(user).Execute***mand() > 0; // 4.2 根据条件删除 bool deleteByWhere = db.Deleteable<User>() .Where(u => u.Age < 18) // 删除年龄<18的用户 .Execute***mand() > 0;
4.3 高级查询 API
1. 子查询
// 查询“注册时间在最近30天”且“年龄>平均年龄”的用户 var subQuery = db.Queryable<User>().Select(u => SqlFunc.AggregateAverage(u.Age)); // 子查询：平均年龄 var result = db.Queryable<User>() .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）
// 导航属性：关联用户（一对一）
[Navigate(NavigateType.O***oOne, nameof(UserId))]
public User User { get; set; }
}
// 查询订单时同时加载关联的用户信息
var orders = db.Queryable<Order>()
.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).Execute***mand();
// 提交事务
db.Ado.***mitTran();
}
catch (Exception ex)
{
// 回滚事务
db.Ado.RollbackTran();
Console.WriteLine($"事务失败：{ex.Message}");
}
五、两种客户端模式对比（SqlSugarClient vs SqlSugarScope）
| 特性 | SqlSugarClient | SqlSugarScope |
|---|---|---|
| 线程安全 | 非线程安全（禁止单例） | 线程安全（支持单例） |
| 性能 | 更高（每次 new 轻量对象） | 中上（内部维护上下文） |
| 适用场景 | WinForm、控制台（非单例场景） | ASP.*** Core（单例注入） |
| 使用注意 | 每次操作 new 实例或用db.CopyNew()
|
全局单例，禁止重复 new（内存泄漏） |
六、总结
SQLSugar 以 “高性能、易上手、功能全” 为核心优势，通过简洁的 API 简化了 .*** 项目的数据库操作。关键在于掌握 实体类定义（特性配置）、客户端初始化 及 CRUD / 查询 API 的使用。无论是简单的单表操作还是复杂的多表关联、事务处理，SQLSugar 都能提供高效的解决方案，适合从中小型项目到大型企业系统的各类场景。
