项目地址: https://github.com/DotNetNext/SqlSugar
官方文档: https://www.donet5.com/Home/Doc
NuGet:
SqlSugar/SqlSugarCore最新版本: SqlSugarCore 5.1.4.221(.NET)/ SqlSugar 5.1.4.207(.NET Framework)(截至 2026-10,NuGet 实测)
许可证: MIT
概述
SqlSugar 主要特性:
- 多数据库:SQL Server / MySQL / Oracle / PostgreSQL / SQLite / 达梦 / 人大金仓 / 神舟通用 / GBase / Highgo / Oscar / Tdengine / ClickHouse / OceanBase / MariaDB / Access / 行云数据库
- Code First / DB First 双模式
- 链式查询:
Queryable<T>().Where(...).Select(...).ToList() - Lambda 表达式 → SQL
- 批量操作:
Insertable / Updateable / Deleteable.ExecuteCommand() - 多种主键策略:自增、Guid、雪花 ID
- 读写分离 / 分库分表
- AOT 友好(高级版)
- 事务:
UseTran自动管理
安装
方式一:dotnet CLI
dotnet add package SqlSugarCore # .NET 6+
# 或
dotnet add package SqlSugar # .NET Framework
方式二:PackageReference
<ItemGroup>
<PackageReference Include="SqlSugarCore" Version="5.1.4.221" />
</ItemGroup>
方式三:包管理器控制台
Install-Package SqlSugarCore -Version 5.1.4.221
验证安装
dotnet list package | grep -i sqlsugar
创建客户端
using SqlSugar;
var db = new SqlSugarClient(new ConnectionConfig {
DbType = DbType.MySql,
ConnectionString = "server=127.0.0.1;uid=root;pwd=...;database=demo",
IsAutoCloseConnection = true,
InitKeyType = InitKeyType.Attribute // 通过特性识别主键
});
db.Aop.OnLogExecuting = (sql, p) => Console.WriteLine(sql);
多数据库:使用
SqlSugarClient(List<ConnectionConfig>)或SqlSugarScope(推荐 DI 注入)。
在 ASP.NET Core 中注册
builder.Services.AddSingleton<ISqlSugarClient>(sp =>
new SqlSugarScope(new ConnectionConfig {
DbType = DbType.SqlServer,
ConnectionString = builder.Configuration.GetConnectionString("Default"),
IsAutoCloseConnection = true
}));
实体定义
[SugarTable("users")]
public class User
{
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
public int Id { get; set; }
[SugarColumn(Length = 50, IsNullable = false)]
public string Name { get; set; } = "";
public int Age { get; set; }
[SugarColumn(IsNullable = true, ColumnDataType = "datetime")]
public DateTime? CreateTime { get; set; }
[SugarColumn(IsIgnore = true)]
public string Computed { get; set; } = "";
}
CRUD
// 插入(自增主键回填)
int id = db.Insertable(new User { Name = "Tom", Age = 18 })
.ExecuteReturnIdentity();
// 批量
db.Insertable(list).ExecuteCommand();
// 更新
db.Updateable(new User { Id = 1, Name = "Tom2" }).ExecuteCommand();
db.Updateable<User>().SetColumns(u => new User { Age = u.Age + 1 })
.Where(u => u.Id == 1).ExecuteCommand();
// 删除
db.Deleteable<User>().Where(u => u.Id == 1).ExecuteCommand();
db.Deleteable<User>(new[] { 1, 2, 3 }).ExecuteCommand();
查询
var u = db.Queryable<User>().First(u => u.Id == 1);
var ls = db.Queryable<User>()
.Where(u => u.Age > 18 && u.Name.Contains("T"))
.OrderBy(u => u.Id, OrderByType.Desc)
.Select(u => new { u.Id, u.Name })
.ToList();
// 分页(签名:ToPageList(pageIndex, pageSize, ref totalNumber))
int total = 0;
var page = db.Queryable<User>()
.Where(u => u.Age > 18)
.ToPageList(1, 20, ref total);
// JOIN
var join = db.Queryable<User, Order>((u, o) => new JoinQueryInfos(
JoinType.Left, u.Id == o.UserId))
.Where((u, o) => u.Age > 18)
.Select((u, o) => new { u.Name, o.Amount })
.ToList();
异步 API
var ls = await db.Queryable<User>().ToListAsync();
await db.Insertable(u).ExecuteCommandAsync();
事务
var result = await db.Ado.UseTranAsync(async () => {
await db.Insertable(a).ExecuteCommandAsync();
await db.Updateable(b).ExecuteCommandAsync();
});
if (!result.IsSuccess) Console.WriteLine(result.ErrorMessage);
Code First(自动建库/建表)
db.DbMaintenance.CreateDatabase(); // 创建库
db.CodeFirst.InitTables(typeof(User), typeof(Order)); // 创建/更新表
db.CodeFirst.InitTables<User>();
雪花 ID
public class Order {
[SugarColumn(IsPrimaryKey = true)]
public long Id { get; set; } // 不要 IsIdentity
}
SnowFlakeSingle.WorkId = 1; // 设置工作机器号
var o = new Order { Id = SnowFlakeSingle.Instance.NextId() };
读写分离
new ConnectionConfig {
ConnectionString = "主库",
SlaveConnectionConfigs = new() {
new SlaveConnectionConfig { HitRate = 10, ConnectionString = "从库1" },
new SlaveConnectionConfig { HitRate = 10, ConnectionString = "从库2" }
}
};
写走主库,读自动负载到从库。
分表(按时间)
[SplitTable(SplitType.Month)] // 月分表
[SugarTable("Logs_{year}{month}")]
public class Log { ... }
db.Insertable(log).SplitTable().ExecuteCommand();
db.Queryable<Log>().SplitTable(new DateTime(2024, 1, 1), new DateTime(2024, 12, 31)).ToList();
AOP(日志 / 拦截)
db.Aop.OnLogExecuting = (sql, p) => log.Info(sql);
db.Aop.OnError = ex => log.Error(ex);
db.Aop.OnLogExecuted = (sql,p) => /* 监控 */;
db.Aop.DataExecuting = (val, e) => /* 自动填充 CreateTime */;
性能与最佳实践
- 批量 Insert 用
Insertable(list).UseSqlBulkCopy()或PageSize - 大查询用
ToPageList,不要 ToList 全量 - 复杂表达式 抽成方法,避免反射开销
- Aop 异步日志,避免影响主流程
- 使用 SqlSugarScope 在 DI 中替代直接
SqlSugarClient
典型工作流
工作流一:新项目从建库到查询
- 建客户端:Web/DI 场景注入
SqlSugarScope,脚本类单次使用可用SqlSugarClient(配IsAutoCloseConnection = true) - 定义实体:
[SugarTable("表名")]+[SugarColumn(IsPrimaryKey = true)](自增加IsIdentity = true,雪花 ID 则不要设) db.CodeFirst.InitTables<T>()建表/更新结构- 增删改查用链式 API:
Insertable/Updateable/Deleteable/Queryable - 列表查询用
ToPageList(pageIndex, pageSize, ref total)分页
工作流二:接数据库现成表(DB First)
- 用
db.DbFirst系列方法按表生成实体类 - 需要改映射时在生成结果上加
[SugarColumn(ColumnName=...)]调整 - 查询照常走链式 API,不写 SQL
工作流三:上生产前的高可用配置
- 读写分离:配
SlaveConnectionConfigs,写主读从 - 大表按时间分表:标
[SplitTable],查询时用分表 API - 打开 AOP:
db.Aop.OnLogExecuting异步落日志,接慢 SQL 监控 - 百万级导入改用
Insertable(list).UseSqlBulkCopy(),并确认目标库支持批量协议
常见问题
| 问题 | 解决 |
|---|---|
| 表名映射不对 | [SugarTable("name")] 显式指定实体对应的表名 |
| 导航属性查不到数据 | Includes 需要配合 Mapper 显式配置映射关系,否则不会自动联表 |
| 并发下报连接已关闭 / 数据错乱 | SqlSugarClient 非线程安全,多线程与 DI 场景改用 SqlSugarScope |
| 中文乱码 | MySQL 用 utf8mb4,连接字符串加 Charset=utf8mb4,列与库排序规则一并设为 utf8mb4 |
| 时间精度丢失 | 列改 datetime(3)(MySQL)或 datetime2(SQL Server) |
Code First 报 InitTables 无效 |
数据库未建或用错库:先 DbMaintenance.CreateDatabase(),再 CodeFirst.InitTables<T>() |
AI 使用建议
推荐工作流
- 创建客户端:DI 注入用
SqlSugarScope(线程安全),单次使用用SqlSugarClient(记得IsAutoCloseConnection = true) - 定义实体:
[SugarTable("表名")]+[SugarColumn(IsPrimaryKey = true)]标注特性 - Code First 建表:
db.CodeFirst.InitTables<T>()自动创建/更新表结构 - CRUD:
Insertable/Updateable/Deleteable/Queryable链式 API - 高级特性:读写分离(
SlaveConnectionConfigs)、分表([SplitTable])、AOP 日志(db.Aop.OnLogExecuting)
关键模式与常见陷阱
- 线程安全:多线程场景务必用
SqlSugarScope(内部连接池),SqlSugarClient非线程安全 - 实体特性:主键用
[SugarColumn(IsPrimaryKey = true)],自增用IsIdentity = true,雪花 ID 不要设IsIdentity - 批量操作:大批量插入用
Insertable(list).UseSqlBulkCopy()比逐条快 10-100 倍 - 分页查询:用
ToPageList(pageIndex, pageSize, ref total)而不是ToList()后手动分页 - 中文乱码:MySQL 连接字符串加
Charset=utf8mb4,列类型用utf8mb4 - AOP 最佳实践:
OnLogExecuting异步写日志,避免阻塞主查询流程
如何选择正确方案
| 场景 | 推荐方案 |
|---|---|
| 新项目快速开发 | SqlSugar(Code First + 链式查询) |
| 政企项目(达梦/金仓) | SqlSugar 或 SOD(两者都支持国产库) |
| 已有数据库(DB First) | SqlSugar(自动生成实体) |
| 高性能批量处理 | SqlSugar + SqlBulkCopy |
| MyBatis 风格 XML | SOD SQL-MAP |
相关技能
- furion — .NET Web 框架,默认集成 SqlSugar:../furion/SKILL.md
- admin-net-backend — 基于 Furion + SqlSugar 的完整后台框架:../admin-net-backend/SKILL.md
- sod — 同为国产 .NET ORM,多数据库适配见长:../sod/SKILL.md
- npoi — Excel 读写库,配合 SqlSugar 实现数据库→Excel 导出:../npoi/SKILL.md