SQLSugar简介、使用方法、核心类与 API 及示例演示
<div id="navCategory"><h5 class="catalogue">目录</h5><ul class="first_class_ul"><li><a href="#_label0">一、SQLSugar 简介</a></li><ul class="second_class_ul"><li><a href="#_lab2_0_0">核心特点：</a></li></ul><li><a href="#_label1">二、基本使用方法</a></li><ul class="second_class_ul"><li><a href="#_lab2_1_1">2.1 安装</a></li><li><a href="#_lab2_1_2">2.2 初始化数据库连接</a></li><li><a href="#_lab2_1_3">2.3 核心操作流程</a></li></ul><li><a href="#_label2">三、关键类与作用</a></li><ul class="second_class_ul"></ul><li><a href="#_label3">四、关键 API 与示例</a></li><ul class="second_class_ul"><li><a href="#_lab2_3_4">4.1 实体类定义（基于特性）</a></li><li><a href="#_lab2_3_5">4.2 CRUD 核心 API</a></li><ul class="third_class_ul"><li><a href="#_label3_3_5_0">1. 新增（Insert）</a></li><li><a href="#_label3_3_5_1">2. 查询（Query）</a></li><li><a href="#_label3_3_5_2">3. 更新（Update）</a></li></ul><li><a href="#_lab2_3_6">4.3 高级查询 API</a></li><ul class="third_class_ul"><li><a href="#_label3_3_6_3">1. 子查询</a></li><li><a href="#_label3_3_6_4">2. 多表关联查询（导航属性）</a></li></ul><li><a href="#_lab2_3_7">4.4 事务操作</a></li><ul class="third_class_ul"></ul></ul><li><a href="#_label4">五、两种客户端模式对比（SqlSugarClient vs SqlSugarScope）</a></li><ul class="second_class_ul"></ul><li><a href="#_label5">六、总结</a></li><ul class="second_class_ul"></ul></ul></div><p class="maodian"><a name="_label0"></a></p><h2>一、SQLSugar 简介</h2><p>SQLSugar 是一款 <strong>轻量级、高性能的 .NET ORM 框架</strong>，由国内团队开发维护，专注于简化数据库操作，同时兼顾灵活性与性能。它通过对象关系映射（ORM）将 C# 实体类与数据库表关联，允许开发者以面向对象的方式完成 CRUD、查询、事务等操作，无需编写原生 SQL（或仅需少量 SQL）。</p>
<p class="maodian"><a name="_lab2_0_0"></a></p><h3>核心特点：</h3>
<ul><li><strong>多数据库支持</strong>：兼容 SQL Server、MySQL、Oracle、PostgreSQL、SQLite、达梦等主流数据库，切换数据库只需修改配置。</li><li><strong>高性能</strong>：采用编译缓存、SQL 优化等机制，性能接近原生 <a href="https://ado.net/" rel="external nofollow" title="ADO.NET">ADO.NET</a>，远超多数同类 ORM。</li><li><strong>易用性</strong>：API 设计简洁，支持链式查询（如 <code>Queryable<T>().Where().OrderBy()</code>），学习成本低。</li><li><strong>功能全面</strong>：支持分表分库、导航属性（多表关联）、批量操作、事务、数据库迁移（CodeFirst）等高级特性。</li><li><strong>轻量无依赖</strong>：核心库体积仅几百 KB，可无缝集成到 .NET Framework、.NET Core、.NET 5+ 等项目中。</li></ul>
<p class="maodian"><a name="_label1"></a></p><h2>二、基本使用方法</h2>
<p class="maodian"><a name="_lab2_1_1"></a></p><h3>2.1 安装</h3>
<p>通过 NuGet 安装核心包：</p>
<div class="jb51code"><pre class="brush:csharp;">Install-Package SqlSugarCore# .NET Core/.NET 5+
# 或针对特定数据库安装扩展包（如MySQL）
Install-Package MySqlConnector# MySQL驱动</pre></div>
<p class="maodian"><a name="_lab2_1_2"></a></p><h3>2.2 初始化数据库连接</h3>
<p>使用 <code>SqlSugarClient</code> 或 <code>SqlSugarScope</code> 初始化连接（核心是 <code>ConnectionConfig</code> 配置）：</p>
<div class="jb51code"><pre class="brush:csharp;">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);</pre></div>
<p class="maodian"><a name="_lab2_1_3"></a></p><h3>2.3 核心操作流程</h3>
<ul><li><strong>定义实体类</strong>（映射数据库表）；</li><li><strong>通过客户端对象（db）</strong> 调用 API 执行数据库操作（CRUD、查询等）。</li></ul>
<p class="maodian"><a name="_label2"></a></p><h2>三、关键类与作用</h2>
<table><thead><tr><th>类 / 接口</th><th>作用说明</th><th>核心场景</th></tr></thead><tbody><tr><td><code>SqlSugarClient</code></td><td>数据库操作核心类，提供所有 ORM API</td><td>非单例场景（如 WinForm），每次操作 new 实例</td></tr><tr><td><code>SqlSugarScope</code></td><td>线程安全的客户端类（基于 AsyncLocal 实现）</td><td>单例场景（如<a href="https://asp.net/" rel="external nofollow"rel="external nofollow" title="ASP.NET">ASP.NET</a> Core），全局共享实例</td></tr><tr><td><code>ISqlSugarClient</code></td><td>客户端接口，用于依赖注入（解耦）</td><td>项目中通过接口调用，便于测试和替换</td></tr><tr><td><code>ConnectionConfig</code></td><td>连接配置类，存储数据库连接信息</td><td>初始化客户端时必传，配置连接字符串、数据库类型等</td></tr><tr><td><code>SugarTable</code></td><td>类级别特性，指定实体对应的数据表名</td><td>实体类定义时，映射表名（如<code></code>）</td></tr><tr><td><code>SugarColumn</code></td><td>属性级别特性，配置字段属性（主键、长度等）</td><td>实体属性定义时，指定字段名、自增、默认值等</td></tr></tbody></table>
<p class="maodian"><a name="_label3"></a></p><h2>四、关键 API 与示例</h2>
<p class="maodian"><a name="_lab2_3_4"></a></p><h3>4.1 实体类定义（基于特性）</h3>
<p>先定义与数据库表映射的实体类（以 “用户表” 为例）：</p>
<div class="jb51code"><pre class="brush:csharp;">using SqlSugar;
using System;
// 映射到数据库表：Sys_User
public class User
{
// 主键（自增）
public int Id { get; set; }
// 用户名（字段名：User_Name，长度50，非空）
public string UserName { get; set; }
// 密码（字段名：User_Pwd，加密存储）
public string Password { get; set; }
// 年龄（默认值0）
public int Age { get; set; }
// 注册时间（默认值：当前时间）
public DateTime RegTime { get; set; }
// 忽略字段（不映射到数据库）
public string TempData { get; set; }
}</pre></div>
<p class="maodian"><a name="_lab2_3_5"></a></p><h3>4.2 CRUD 核心 API</h3>
<p class="maodian"><a name="_label3_3_5_0"></a></p><h4>1. 新增（Insert）</h4>
<div class="jb51code"><pre class="brush:csharp;">// 单条新增
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; // 返回影响行数</pre></div>
<p class="maodian"><a name="_label3_3_5_1"></a></p><h4>2. 查询（Query）</h4>
<div class="jb51code"><pre class="brush:csharp;">// 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); // 平均年龄</pre></div>
<p class="maodian"><a name="_label3_3_5_2"></a></p><h4>3. 更新（Update）</h4>
<div class="jb51code"><pre class="brush:csharp;">// 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;</pre></div>
<h5>4. 删除（Delete）</h5>
<div class="jb51code"><pre class="brush:csharp;">// 4.1 根据实体删除（根据主键）
bool deleteByEntity = db.Deleteable(user).ExecuteCommand() > 0;
// 4.2 根据条件删除
bool deleteByWhere = db.Deleteable<User>()
.Where(u => u.Age < 18) // 删除年龄<18的用户
.ExecuteCommand() > 0;</pre></div>
<p class="maodian"><a name="_lab2_3_6"></a></p><h3>4.3 高级查询 API</h3>
<p class="maodian"><a name="_label3_3_6_3"></a></p><h4>1. 子查询</h4>
<div class="jb51code"><pre class="brush:csharp;">// 查询“注册时间在最近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();</pre></div>
<p class="maodian"><a name="_label3_3_6_4"></a></p><h4>2. 多表关联查询（导航属性）</h4>
<p>假设有订单表（Order）与用户表（User）关联（一对多）：</p>
<div class="jb51code"><pre class="brush:csharp;">// 订单实体（含导航属性）
public class Order
{
public int Id { get; set; }
public int UserId { get; set; } // 外键（关联User.Id）
// 导航属性：关联用户（一对一）
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}");
}</pre></div>
<p class="maodian"><a name="_lab2_3_7"></a></p><h3>4.4 事务操作</h3>
<div class="jb51code"><pre class="brush:csharp;">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}");
}</pre></div>
<p class="maodian"><a name="_label4"></a></p><h2>五、两种客户端模式对比（SqlSugarClient vs SqlSugarScope）</h2>
<table><thead><tr><th>特性</th><th>SqlSugarClient</th><th>SqlSugarScope</th></tr></thead><tbody><tr><td>线程安全</td><td>非线程安全（禁止单例）</td><td>线程安全（支持单例）</td></tr><tr><td>性能</td><td>更高（每次 new 轻量对象）</td><td>中上（内部维护上下文）</td></tr><tr><td>适用场景</td><td>WinForm、控制台（非单例场景）</td><td><a href="https://asp.net/" rel="external nofollow"rel="external nofollow" title="ASP.NET">ASP.NET</a> Core（单例注入）</td></tr><tr><td>使用注意</td><td>每次操作 new 实例或用<code>db.CopyNew()</code></td><td>全局单例，禁止重复 new（内存泄漏）</td></tr></tbody></table>
<p class="maodian"><a name="_label5"></a></p><h2>六、总结</h2>
<p>SQLSugar 以 “高性能、易上手、功能全” 为核心优势，通过简洁的 API 简化了 .NET 项目的数据库操作。关键在于掌握 <strong>实体类定义（特性配置）</strong>、<strong>客户端初始化</strong> 及 <strong>CRUD / 查询 API</strong> 的使用。无论是简单的单表操作还是复杂的多表关联、事务处理，SQLSugar 都能提供高效的解决方案，适合从中小型项目到大型企业系统的各类场景。</p>
頁:
[1]