SqlSugar是一款由国内开发者维护的开源ORM框架，它的定位很明确：轻量、易用、性能好。相比Dapper这类需要手写大量SQL的微型ORM，SqlSugar提供了完整的强类型API；相比Entity Framework，它的学习曲线更平缓，SQL的可控性也更强。本文将通过完整的代码示例，带你快速掌握SqlSugar的核心用法。
一、安装与初始化SqlSugarClient
SqlSugar通过NuGet分发，包名随目标框架不同而有所区别。如果你使用的是.NET Core或.NET 5以上版本，直接安装SqlSugarCore即可；如果项目还停留在.NET Framework，则需要安装SqlSugar这个包。在包管理器控制台执行安装命令：
Install-Package SqlSugarCore
安装完成后，第一步是创建数据库连接对象。SqlSugar的核心入口是SqlSugarClient，所有操作都围绕它展开。下面的代码演示了标准的初始化方式：
// 创建 SqlSugarClient 实例
SqlSugarClient db = new SqlSugarClient(new ConnectionConfig()
{
ConnectionString = "server=localhost;port=3306;user=root;password=123456;database=testdb;",
DbType = DbType.MySql, // 支持 MySql、SqlServer、Sqlite、PostgreSQL、Oracle 等
IsAutoCloseConnection = true, // 自动释放连接，推荐开启
InitKeyType = InitKeyType.Attribute // 通过特性读取主键和自增信息
});
// 简单测试连接：执行一条原生 SQL
var version = db.Ado.SqlQuery<string>("select version()").First();
Console.WriteLine($"数据库版本: {version}");实际项目中不建议到处new一个SqlSugarClient，更好的做法是注册成单例服务或封装一个DbContext基类。在ASP.NET Core项目里，可以在Program.cs中把它注册到依赖注入容器，配合ISqlSugarClient接口使用，既方便单元测试Mock，也避免连接泄漏。
二、实体映射与建表
SqlSugar通过C#特性（Attribute）来描述实体与表之间的映射关系。[SugarTable]指定表名，[SugarColumn]描述列的属性，比如是否主键、是否自增、列名、长度等。这种声明式写法非常直观，看一眼实体类就知道表结构长什么样。
[SugarTable("t_user")]
public class SysUser
{
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
public int Id { get; set; }
[SugarColumn(ColumnName = "user_name", Length = 50, Nullable = false)]
public string Name { get; set; }
[SugarColumn(Length = 100)]
public string Email { get; set; }
[SugarColumn(IsNullable = true)]
public DateTime? CreateTime { get; set; }
[SugarColumn(ColumnDataType = "decimal(10,2)")]
public decimal Balance { get; set; }
}SqlSugar支持代码优先（Code First），也就是先写实体类再生成表。调用db.CodeFirst.InitTables<SysUser>()，框架会自动在数据库中创建对应的表，已存在的表则会同步结构变更（新增列）。这在开发阶段特别省事，不用来回切换数据库工具手写DDL语句。
// 根据实体自动建表或更新表结构
db.CodeFirst.InitTables<SysUser>();
Console.WriteLine("表结构同步完成");有一点需要注意：自动同步结构默认只新增列，不会删除数据库中已有的列，这是为了防止误删数据。如果确实要删除列，可以配置EntityService并设置EnableDiffLogEvent相关选项，但生产环境建议谨慎使用，结构变更最好还是走SQL脚本管理。
三、增删改查与分页查询
增删改查是ORM最核心的能力。SqlSugar的API设计采用链式调用风格，可读性很高。插入数据时，自增主键会自动回填到实体对象中：
// 插入单条，返回自增Id
var user = new SysUser
{
Name = "张三",
Email = "zhangsan@ipipp.com",
CreateTime = DateTime.Now,
Balance = 100.50m
};
int userId = db.Insertable(user).ExecuteReturnIdentity();
// 批量插入，性能远优于循环单条插入
db.Insertable(new List<SysUser>
{
new SysUser { Name = "李四", Balance = 200 },
new SysUser { Name = "王五", Balance = 300 }
}).ExecuteCommand();查询方面，SqlSugar提供了函数级别的强类型条件写法，表达式中的it.Name会被自动翻译成对应的SQL列名，避免手写字符串列名带来的拼写错误：
// 单条查询
var u = db.Queryable<SysUser>().First(it => it.Id == 1);
// 条件查询 + 排序
var list = db.Queryable<SysUser>()
.Where(it => it.Balance >= 100)
.WhereIF(!string.IsNullOrEmpty(keyword), it => it.Name.Contains(keyword))
.OrderBy(it => it.CreateTime, OrderByType.Desc)
.ToList();
// 分页查询：Skip.take 风格
int pageIndex = 1, pageSize = 10;
RefAsync<int> total = new RefAsync<int>();
var pageList = db.Queryable<SysUser>()
.OrderBy(it => it.Id)
.ToPageListAsync(pageIndex, pageSize, total).Result;
Console.WriteLine($"总记录数: {total.Value}");上面出现的WhereIF是一个非常实用的方法：当第一个参数为false时该条件自动跳过，省去了拼接查询条件的if判断，代码整洁不少。更新和删除的写法同样简单，但务必记得带上Where条件，否则会全表生效：
// 更新指定列
db.Updateable<SysUser>()
.SetColumns(it => it.Balance == it.Balance + 50)
.Where(it => it.Id == userId)
.ExecuteCommand();
// 带条件删除
db.Deleteable<SysUser>().Where(it => it.Id == userId).ExecuteCommand();四、事务与多库操作
涉及多表写入时必须使用事务保证一致性。SqlSugar提供了UseTran方法，把多个操作包在一个事务里，任何一步失败都会自动回滚，不需要手动提交或回滚：
var result = db.Ado.UseTran(() =>
{
db.Insertable(new SysUser { Name = "赵六", Balance = 0 }).ExecuteCommand();
db.Updateable<SysUser>()
.SetColumns(it => it.Balance == it.Balance - 10)
.Where(it => it.Id == 1)
.ExecuteCommand();
// 中间抛出异常会整体回滚
});
Console.WriteLine(result.IsSuccess ? "事务提交成功" : $"事务失败: {result.ErrorMessage}");对于需要同时连接多个数据库的场景，可以用SqlSugarScope或者在同一个SqlSugarClient上配置多个连接，再通过db.GetConnectionScope("库名")切换。常见的做法是主库存业务数据、从库存日志和报表，读写分离也可以借助SugarReadOnly属性实现，查询走从库、写入走主库。
SqlSugarClient db = new SqlSugarClient(new List<ConnectionConfig>
{
new ConnectionConfig { ConfigId = "main", ConnectionString = "主库连接串", DbType = DbType.MySql },
new ConnectionConfig { ConfigId = "log", ConnectionString = "从库连接串", DbType = DbType.MySql }
});
// 使用主库
db.GetConnectionScope("main").Insertable(user).ExecuteCommand();
// 使用日志库
db.GetConnectionScope("log").Queryable<SysLog>().ToList();总体来看，SqlSugar非常适合中小型项目以及对SQL可控性有要求的团队。它的中文文档齐全，遇到问题排查成本也低。如果你的项目正在技术选型阶段，不妨用一个小模块先试用一下，体验一下链式查询带来的开发效率提升。掌握本文介绍的初始化、实体映射、增删改查、事务这几个核心点，日常开发中的大部分数据访问需求都能轻松应对了。