.NET 数据操作：SqlSugar 从入门到实战

方式 2：IOC 注入（ASP.NET Core 场景）

对于 Web 项目，推荐通过依赖注入全局管理 SqlSugarClient，提升代码可维护性：

// Program.cs 中配置
var builder = WebApplication.CreateBuilder(args);

// 注入 SqlSugarClient（单例模式，使用 SqlSugarScope 保证线程安全）
builder.Services.AddSingleton<ISqlSugarClient>(sp => {
    var connectionConfig = new ConnectionConfig
    {
        ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection"),
        DbType = DbType.SqlServer,
        IsAutoCloseConnection = true,
        InitKeyType = InitKeyType.Attribute
    };
    return new SqlSugarScope(connectionConfig);
});

var app = builder.Build();

之后在控制器中直接注入 ISqlSugarClient 即可使用，无需重复初始化。

三、核心实战：SqlSugar 基础操作（CRUD）

完成初始化后，先定义实体类与数据库表映射，再通过链式 API 实现基础 CRUD 操作，全程无需编写原生 SQL。

3.1 定义实体类（基于特性映射）

通过 SugarTable（类级别）、SugarColumn（属性级别）特性，实现实体类与数据库表的映射，支持自定义表名、字段名、主键、自增等配置：

using SqlSugar;

// 映射到数据库表：Users（若不指定，默认使用类名）
[SugarTable("Users")]
public class User
{
    // 主键，自增（IsIdentity=true 仅适用于支持自增的数据库）
    [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; }

    // 密码字段，长度 100，允许为空
    [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; }
}

可选：通过 CodeFirst 自动创建数据库表，无需手动建表：

// 自动创建 Users 表（若不存在）
db.CodeFirst.InitTables<User>();

3.2 基础 CRUD 操作

SqlSugar 的 CRUD 操作均支持链式调用，语法简洁，可灵活组合条件。

（1）新增操作（Insert）

// 1. 单条新增，返回自增 ID
var user = new User
{
    UserName = "Alice",
    Password = "123456",
    Age = 25
};
int newId = db.Insertable(user).ExecuteReturnIdentity();

// 2. 批量新增（性能优于循环单条插入）
var userList = new List<User>
{
    new User { UserName = "Bob", Password = "654321", Age = 30 },
    new User { UserName = "Charlie", Password = "abc123", Age = 28 }
};
int affectedRows = db.Insertable(userList).ExecuteCommand();

（2）查询操作（Query）

支持单条查询、条件查询、分页查询、多表联查等多种场景，同时支持原生 SQL 查询：

// 1. 单条查询（根据主键）
var user = db.Queryable<User>().In(1).First();
// 或根据条件查询单条
var user = db.Queryable<User>().Where(u => u.UserName == "Alice").FirstOrDefault();

// 2. 条件查询（查询年龄>20 的用户，按注册时间降序）
var userList = db.Queryable<User>().Where(u => u.Age > 20).OrderByDesc(u => u.RegTime).ToList();

// 3. 分页查询（分页核心，无需手动计算页码、条数）
int pageIndex = 1; // 当前页码
int pageSize = 10; // 每页条数
var pageResult = db.Queryable<User>().Where(u => u.Age > 18).ToPageList(pageIndex, pageSize, out int totalCount);
// totalCount：总条数，pageResult：当前页数据

// 4. 多表联查（以 User 和 Order 为例，一对多关系）
var result = db.Queryable<User, Order>((u, o) => u.Id == o.UserId)
    .Select((u, o) => new { UserId = u.Id, UserName = u.UserName, OrderId = o.Id, OrderName = o.OrderName })
    .ToList();

// 5. 原生 SQL 查询（返回实体类或匿名对象）
var sql = "SELECT * FROM Users WHERE Age > @Age";
var userList = db.Ado.SqlQuery<User>(sql, new { Age = 20 });

（3）修改操作（Update）

支持全量修改、局部修改、批量修改，可精准控制修改字段：

// 1. 局部修改（仅修改指定字段）
int affectedRows = db.Updateable<User>()
    .SetColumns(u => u.Age == 26) // 要修改的字段
    .Where(u => u.Id == 1) // 修改条件
    .ExecuteCommand();

// 2. 全量修改（根据实体）
var user = db.Queryable<User>().In(1).First();
user.UserName = "Alice_Update";
affectedRows = db.Updateable(user).ExecuteCommand();

// 3. 批量修改
affectedRows = db.Updateable<User>()
    .SetColumns(u => u.Password == "new_pwd")
    .Where(u => u.Age > 30)
    .ExecuteCommand();

（4）删除操作（Delete）

// 1. 根据主键删除
int affectedRows = db.Deleteable<User>().In(1).ExecuteCommand();

// 2. 根据条件删除
affectedRows = db.Deleteable<User>().Where(u => u.UserName == "Bob").ExecuteCommand();

// 3. 批量删除
affectedRows = db.Deleteable<User>().In(new List<int> { 2, 3 }).ExecuteCommand();

四、进阶特性：解锁 SqlSugar 高级能力

除基础操作外，SqlSugar 还提供了诸多实用高级特性，覆盖复杂业务场景需求。

4.1 事务管理

支持手动事务与自动事务，确保多步数据库操作的原子性，需注意：事务操作必须使用同一个 SqlSugarClient 实例：

// 手动事务（推荐，灵活控制）
try
{
    db.Ado.BeginTran(); // 开启事务
    
    // 执行多步操作
    db.Insertable(new User { UserName = "David", Age = 22 }).ExecuteReturnIdentity();
    db.Updateable<User>().SetColumns(u => u.Age == 23).Where(u => u.Id == 4).ExecuteCommand();
    
    db.Ado.CommitTran(); // 提交事务
}
catch (Exception ex)
{
    db.Ado.RollbackTran(); // 回滚事务
    Console.WriteLine($"事务执行失败：{ex.Message}");
}

4.2 缓存控制

内置内存缓存，支持自定义 Redis 缓存，减少数据库查询压力，提升接口性能：

// 基础内存缓存（缓存 10 分钟）
var userList = db.Queryable<User>().WithCache(10 * 60) // 缓存时间（秒）.ToList();

// 自定义缓存键，便于后续删除缓存
var cacheKey = "user_list_age_20";
var userList = db.Queryable<User>().Where(u => u.Age > 20).WithCache(10 * 60, cacheKey).ToList();

// 删除指定缓存
db.RemoveCache(cacheKey);

// 集成 Redis 缓存（需额外配置 Redis 连接）
// 此处省略 Redis 配置，可参考 SqlSugar 官方文档

4.3 分表分库

支持水平分表、垂直分表与分库操作，适配大数据量场景，无需修改核心业务代码：

// 水平分表（按时间分表，如 Users_2024、Users_2025）
var user = new User { UserName = "Eve", Age = 24 };
db.Insertable(user).AS("Users_" + DateTime.Now.Year) // 动态指定表名
.ExecuteReturnIdentity();

// 分库操作（需配置多数据库连接，通过 ConfigId 区分）
// 此处省略多库配置，可通过 ConnectionConfig 的 ConfigId 实现

五、框架对比：SqlSugar 适合哪些场景？

在 .NET 生态中，EF Core、Dapper、SqlSugar 是最常用的三款 ORM 框架，三者定位不同，适配场景各有侧重，以下是核心维度对比：

六、总结与注意事项

SqlSugar 作为一款国产 ORM 框架，完美平衡了易用性、性能与功能全面性，无需复杂配置就能快速上手，既能满足基础 CRUD 需求，又能支撑分表分库、事务管理、缓存控制等高级场景，尤其适合中小型 .NET 项目与快速开发场景。

使用过程中需注意以下几点：

• 确保 SqlSugarClient 实例的线程安全，Web 项目优先使用 SqlSugarScope 与依赖注入；
• 事务操作需使用同一个客户端实例，否则事务会失效；
• 切换数据库时，只需修改 ConnectionConfig 的 DbType 与连接字符串，无需修改业务代码；
• 调试时可开启 SQL 日志输出，便于排查 SQL 生成问题。

总体而言，SqlSugar 是 .NET 开发者提升数据操作效率的得力工具，兼顾'快开发'与'高性能'，值得深入学习与应用。后续可结合官方文档，探索更多高级特性，适配更复杂的业务场景。