SQLSugar简介、使用方法、核心类与 API 及示例演示
作者：张謹礧
SQLSugar以高性能、易上手、功能全为核心优势,通过简洁的API简化了.NET 项目的数据库操作,本文介绍SQLSugar简介、使用方法、核心类与 API 及示例,感兴趣的朋友跟随小编一起看看吧
一、SQLSugar 简介
SQLSugar 是一款 轻量级、高性能的 .NET ORM 框架，由国内团队开发维护，专注于简化数据库操作，同时兼顾灵活性与性能。它通过对象关系映射（ORM）将 C# 实体类与数据库表关联，允许开发者以面向对象的方式完成 CRUD、查询、事务等操作，无需编写原生 SQL（或仅需少量 SQL）。
核心特点：
- 多数据库支持：兼容 SQL Server、MySQL、Oracle、PostgreSQL、SQLite、达梦等主流数据库，切换数据库只需修改配置。
- 高性能：采用编译缓存、SQL 优化等机制，性能接近原生 ADO.NET，远超多数同类 ORM。
- 易用性：API 设计简洁，支持链式查询（如
Queryable<T>().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、查询等）。
三、关键类与作用
| 类 / 接口 | 作用说明 | 核心场景 |
|---|---|---|
SqlSugarClient | 数据库操作核心类，提供所有 ORM API | 非单例场景（如 WinForm），每次操作 new 实例 |
SqlSugarScope | 线程安全的客户端类（基于 AsyncLocal 实现） | 单例场景（如ASP.NET 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 isSuccess = db.Insertable(userList).ExecuteCommand() > 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 updateSuccess = db.Updateable(user).ExecuteCommand() > 0;
// 3.2 局部更新（只更新指定字段，性能更优）
bool partialUpdate = db.Updateable<User>()
.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<User>()
.Where(u => u.Age < 18) // 删除年龄<18的用户
.ExecuteCommand() > 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.OneToOne, 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).ExecuteCommand();
// 提交事务
db.Ado.CommitTran();
}
catch (Exception ex)
{
// 回滚事务
db.Ado.RollbackTran();
Console.WriteLine($"事务失败：{ex.Message}");
}五、两种客户端模式对比（SqlSugarClient vs SqlSugarScope）
| 特性 | SqlSugarClient | SqlSugarScope |
|---|---|---|
| 线程安全 | 非线程安全（禁止单例） | 线程安全（支持单例） |
| 性能 | 更高（每次 new 轻量对象） | 中上（内部维护上下文） |
| 适用场景 | WinForm、控制台（非单例场景） | ASP.NET Core（单例注入） |
| 使用注意 | 每次操作 new 实例或用db.CopyNew() | 全局单例，禁止重复 new（内存泄漏） |
六、总结
SQLSugar 以 “高性能、易上手、功能全” 为核心优势，通过简洁的 API 简化了 .NET 项目的数据库操作。关键在于掌握 实体类定义（特性配置）、客户端初始化 及 CRUD / 查询 API 的使用。无论是简单的单表操作还是复杂的多表关联、事务处理，SQLSugar 都能提供高效的解决方案，适合从中小型项目到大型企业系统的各类场景。
到此这篇关于SQLSugar简介、使用方法、核心类与 API 及示例演示的文章就介绍到这了,更多相关SQLSugar使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！