SQLSugar 使用指南：从入门到进阶及高级特性详解

SQLSugar 是一款功能丰富的 .NET ORM 框架，它支持多种数据库、简洁的 API 和优雅的编程体验。相较于其他 ORM，SQLSugar 提供了很多开发者友好的功能，比如自动创建表结构、灵活的查询构建、支持事务、多表联查等。本文将从基础的 CRUD 操作开始，逐步深入介绍 SQLSugar 的进阶和高级功能，尤其是 CRUD、联表查询、事务处理、导航属性、并发冲突、依赖注入、读写分离等高级特性，帮助你全面掌握 SQLSugar 的使用方法。

---

一、SQLSugar 基础

1.1 安装 SQLSugar

首先，使用 NuGet 安装 SQLSugar：

Install-Package SqlSugar

在 .NET 项目中安装后，你可以通过配置数据库连接来初始化 SQLSugar 实例：

SqlSugarScope db = new SqlSugarScope(new ConnectionConfig()
{
    ConnectionString = "数据库连接字符串",
    DbType = DbType.SqlServer, // 数据库类型
    IsAutoCloseConnection = true // 自动关闭连接
});

1.2 基本的 CRUD 操作

SQLSugar 提供了丰富的 API 以实现基本的 CRUD 操作。

1.2.1 插入数据

var user = new User { Name = "张三", Age = 25 };
db.Insertable(user).ExecuteCommand();

1.2.2 查询数据

var user = db.Queryable<User>().Where(a => a.Id == 1).Single();

1.2.3 更新数据

db.Updateable(new User() { Id = 1, Age = 30 }).ExecuteCommand();

1.2.4 删除数据

db.Deleteable<User>().Where(a => a.Id == 1).ExecuteCommand();

SQLSugar 的基本 CRUD 操作非常简洁，开发者可以通过这些 API 快速操作数据库。

1.3 自动创建表结构

SQLSugar 支持自动创建表结构，这对于需要快速构建表结构的场景十分有用。通过 Code First，你可以轻松地同步表结构：

db.CodeFirst.InitTables(typeof(User));

这样，SQLSugar 会根据你的实体类自动生成或同步数据库中的表结构。

---

二、SQLSugar 进阶功能

2.1 多表联查

SQLSugar 提供了丰富的联表查询功能，可以通过 Join 进行表与表之间的关联查询。

var query = db.Queryable<User, Order>((u, o) => new JoinQueryInfos(
    JoinType.Left, u.Id == o.UserId))
    .Select((u, o) => new { u.Name, o.OrderId, o.Amount })
    .ToList();

此代码展示了如何通过联表查询用户与其订单信息。

2.2 分页查询

分页查询是 SQL 操作中非常常见的一部分，SQLSugar 提供了便捷的分页 API：

var pageIndex = 1;
var pageSize = 10;
var totalCount = 0;

var users = db.Queryable<User>()
    .Where(u => u.Age > 18)
    .ToPageList(pageIndex, pageSize, ref totalCount);

ToPageList 会根据 pageIndex 和 pageSize 返回分页数据，并通过 totalCount 得到符合条件的记录总数。

2.3 事务处理

SQLSugar 提供了简洁的事务处理机制，确保数据一致性：

db.Ado.BeginTran();
try
{
    db.Insertable(new User() { Name = "张三", Age = 25 }).ExecuteCommand();
    db.Insertable(new Order() { UserId = 1, Amount = 100 }).ExecuteCommand();
    db.Ado.CommitTran();
}
catch
{
    db.Ado.RollbackTran();
}

在事务中执行多个数据库操作，如果有任何异常发生，SQLSugar 会自动回滚事务。

---

三、SQLSugar 高级特性

3.1 导航属性

SQLSugar 支持导航属性，使得在实体类中定义关联关系变得更加简洁。当你定义了带有导航属性的实体时，SQLSugar 能够自动处理关联查询。

假设有 User 和 Order 两个实体，其中 User 可以拥有多个 Order：

public class User
{
    [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
    public int Id { get; set; }
    public string Name { get; set; }

    [Navigate(NavigateType.OneToMany, nameof(Order.UserId))]
    public List<Order> Orders { get; set; }
}

public class Order
{
    [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
    public int Id { get; set; }
    public int UserId { get; set; }
    public decimal Amount { get; set; }
}

使用 Include 方法，可以方便地进行导航属性查询：

var usersWithOrders = db.Queryable<User>()
    .Includes(u => u.Orders)
    .ToList();

通过这种方式，SQLSugar 会自动加载用户及其订单信息，无需手动编写复杂的 SQL。

3.2 并发冲突处理

并发冲突是数据库操作中的常见问题，SQLSugar 提供了简单的机制来处理并发冲突。你可以通过 RowVersion 或 Lock 等机制来处理更新时的冲突。

public class User
{
    [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime LastUpdateTime { get; set; }
}

在更新数据时，SQLSugar 可以确保通过时间戳或其他字段防止多个操作同时更改数据。

db.Updateable(user)
    .Where(u => u.LastUpdateTime == oldUpdateTime)
    .ExecuteCommand();

这种方式能够防止并发写入时出现的数据不一致问题。

3.3 读写分离

SQLSugar 支持读写分离，可以在多主从数据库环境下进行配置，以提升读操作的性能。通过配置多个连接字符串，你可以轻松实现主库写、从库读的分离操作。

db = new SqlSugarScope(new List<ConnectionConfig>()
{
    new ConnectionConfig()
    {
        ConnectionString = "主库连接字符串",
        DbType = DbType.SqlServer,
        IsAutoCloseConnection = true,
        ConfigId = "master"
    },
    new ConnectionConfig()
    {
        ConnectionString = "从库连接字符串",
        DbType = DbType.SqlServer,
        IsAutoCloseConnection = true,
        ConfigId = "slave"
    }
}, db =>
{
    db.Aop.CurdAfter = (sugar, info) =>
    {
        if (info.Sql.Contains("SELECT"))
            db.ChangeConfig("slave");
        else
            db.ChangeConfig("master");
    };
});

通过这个配置，SQLSugar 会自动将读操作路由到从库，将写操作路由到主库。

3.4 依赖注入

SQLSugar 支持与 ASP.NET Core 的依赖注入机制集成。你可以在项目中配置 SQLSugar 的依赖注入，简化数据库上下文的使用。

在 Startup.cs 中配置 SQLSugar 依赖注入：

public void ConfigureServices(IServiceCollection services)
{
    services.AddScoped<ISqlSugarClient>(s => new SqlSugarScope(new ConnectionConfig()
    {
        ConnectionString = "数据库连接字符串",
        DbType = DbType.SqlServer,
        IsAutoCloseConnection = true
    }));
}

在控制器或服务中通过构造函数注入 ISqlSugarClient：

public class UserService
{
    private readonly ISqlSugarClient _db;
    
    public UserService(ISqlSugarClient db)
    {
        _db = db;
    }

    public List<User> GetUsers()
    {
        return _db.Queryable<User>().ToList();
    }
}

依赖注入能够更好地管理数据库上下文的生命周期，简化使用 SQLSugar 进行数据库操作的流程。

---

四、SQLSugar 的优势与劣势

4.1 优势

1. 多数据库支持：SQLSugar 支持多种数据库，如 SQL Server、MySQL、PostgreSQL 等，切换数据库非常方便。
2. 丰富的功能：内置了丰富的功能，如 Code First、导航属性、读写分离、并发处理等，大大简化开发工作。
3. 易用的 API：SQLSugar 的 API 设计简洁明了，上手非常容易，尤其适合中小型项目。
4. 灵活的扩展性：支持自定义 SQL、自定义拦截器、扩展方法等，具有很强的扩展性。

4.2 劣势

1. 学习曲线：尽管 SQLSugar 易用，但在学习一些高级特性时可能需要投入一定时间。
2. 复杂查询性能：在面对非常复杂的查询场景时，可能需要借助原生 SQL 来提高性能。
3. 社区生态：与 Entity Framework 等主流 ORM 框架相比，SQLSugar 的社区生态和文档相对较少。

---

结语

SQLSugar 是一个功能强大且灵活的 ORM 框架，它简化了 .NET 开发中与数据库交互的流程。从基础的 CRUD 到高级的读写分离、事务管理，SQLSugar 提供了一整套完善的解决方案。对于中小型项目来说，SQLSugar 是一个非常不错的选择。如果你正在寻找一个轻量级、高效的 ORM 框架，SQLSugar 值得一试。