SqlSugar国产轻量级ORM框架，支持SQLServer、MySQL、达梦等主流数据库。提供Lambda表达式查询、自动代码生成、事务管理、实体映射等功能。安装配置简便，支持CRUD操作、分页查询、多数据库同时连接，轻松实现数据增删改查及复杂查询，性能高效。
# SqlSugar：一款让.NET开发者爱不释手的国产ORM框架
在.NET生态圈里，ORM框架的选择其实不少，但要说哪款最接地气、最懂中国开发者，SqlSugar绝对能排进前三。它由国内开发者维护，轻量、高效，而且对多数据库的支持做得相当扎实——从SQL Server到MySQL，从PostgreSQL到Oracle，甚至连达梦、人大金仓这些国产数据库也一并覆盖。说白了，它就是那种“拿来就能用，用了就回不去”的工具。
## 为什么选择SqlSugar？
先说说它最吸引人的几个点：
- **轻量级**：框架体积小，启动速度快，不像某些“重型武器”那样拖泥带水。
- **高性能**：SQL生成和执行机制经过多次优化，批量操作时优势尤其明显。
- **易用性**：API设计简洁，学习成本很低，有经验的开发者几乎可以零障碍上手。
- **多数据库支持**：主流数据库全覆盖，国产数据库也位列其中。
- **中文文档**：这一点太重要了——完善的官方文档和活跃的社区，遇到问题翻翻文档或者群里问一句，基本都能解决。
## 特性与优势
### 核心特性
**多数据库支持**
SqlSugar内置了对多种数据库的支持，而且切换起来非常方便。除了常见的SQL Server、MySQL、PostgreSQL、Oracle、SQLite，还专门适配了达梦、人大金仓等国产数据库。对于需要在不同数据库间切换的项目来说，这简直是救命的功能。
**丰富的查询方式**
Lambda表达式查询、原生SQL、存储过程调用、动态查询构建……基本上你能想到的查询方式，它都提供了。而且Lambda表达式的写法非常直观，写起来比拼接字符串舒服太多了。
**代码生成功能**
根据数据库表自动生成实体类、仓储层代码，还能自定义模板。对于快速搭建项目骨架来说，效率提升不是一点半点。
**事务管理**
自动事务、手动控制、分布式事务支持，该有的都有。而且事务的API设计得很顺手，不容易出错。
### 性能优势
说到性能，直接上代码感受一下：
```csharp
// 高性能的批量操作
var users = new List
();
for (int i = 0; i < 10000; i++)
{
users.Add(new User { Name = $"User{i}", Age = 20 + i % 50 });
}
// 批量插入，性能优异
db.Insertable(users).ExecuteCommand();
```
一万条数据，一秒钟搞定，这在传统逐条插入的场景下简直是降维打击。
## 安装与配置
### NuGet包安装
安装核心包和对应的数据库扩展包，命令很简单：
```csharp
# 核心包
Install-Package SqlSugar
# 特定数据库扩展
Install-Package SqlSugar.SqlServer
Install-Package SqlSugar.MySql
Install-Package SqlSugar.PostgreSQL
```
### 基础配置
配置一个数据库连接，几行代码足矣：
```csharp
using SqlSugar;
// 数据库连接配置
var db = new SqlSugarClient(new ConnectionConfig()
{
ConnectionString = "Server=.;Database=TestDB;Trusted_Connection=true;",
DbType = DbType.SqlServer,
IsAutoCloseConnection = true, // 自动关闭连接
InitKeyType = InitKeyType.Attribute // 使用特性初始化
});
// 日志配置
db.Aop.OnLogExecuting = (sql, pars) =>
{
Console.WriteLine($"SQL: {sql}");
Console.WriteLine($"Parameters: {string.Join(",", pars?.Select(p => $"{p.ParameterName}:{p.Value}"))}");
};
```
`IsAutoCloseConnection` 这个配置很实用，每次查询完自动关闭连接，省去了手动管理的麻烦。日志功能也方便调试，能直接看到生成的SQL语句和参数。
### 多数据库配置
如果项目需要同时连接多个数据库，使用 `SqlSugarScope` 搭配 `ConfigId` 来管理：
```csharp
var configs = new List
{
new ConnectionConfig
{
ConfigId = "db1",
ConnectionString = "SqlServer连接字符串",
DbType = DbType.SqlServer,
IsAutoCloseConnection = true
},
new ConnectionConfig
{
ConfigId = "db2",
ConnectionString = "MySQL连接字符串",
DbType = DbType.MySql,
IsAutoCloseConnection = true
}
};
var db = new SqlSugarScope(configs);
// 切换数据库
var sqlServerDb = db.GetConnection("db1");
var mysqlDb = db.GetConnection("db2");
```
## 基础使用
### 实体类定义
实体类通过 `[SugarTable]` 和 `[SugarColumn]` 特性来映射数据库表：
```csharp
[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; }
[SugarColumn(IsNullable = true)]
public int? Age { get; set; }
[SugarColumn(IsNullable = true)]
public DateTime? CreateTime { get; set; }
[SugarColumn(IsIgnore = true)] // 忽略该字段
public string TempProperty { get; set; }
}
```
这里的 `IsIgnore` 很实用——有些实体属性不需要映射到数据库，加个特性就搞定了。
### 基本CRUD操作
增删改查的操作非常直观，几乎不需要额外学习：
```csharp
// 插入
var user = new User { Name = "张三", Age = 25, CreateTime = DateTime.Now };
var id = db.Insertable(user).ExecuteReturnIdentity();
// 查询
var users = db.Queryable().ToList();
var user = db.Queryable().Where(u => u.Id == 1).First();
// 更新
db.Updateable()
.SetColumns(u => new User { Age = 26 })
.Where(u => u.Id == 1)
.ExecuteCommand();
// 删除
db.Deleteable().Where(u => u.Id == 1).ExecuteCommand();
```
## 实体映射
### 特性配置
除了基础的字段映射，SqlSugar还支持更精细的控制，比如字段名映射、精度、JSON字段等：
```csharp
[SugarTable("tb_product")]
public class Product
{
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
public int ProductId { get; set; }
[SugarColumn(ColumnName = "product_name", Length = 100)]
public string Name { get; set; }
[SugarColumn(ColumnName = "unit_price", DecimalDigits = 2)]
public decimal Price { get; set; }
[SugarColumn(ColumnName = "create_date", IsNullable = true)]
public DateTime? CreateDate { get; set; }
[SugarColumn(IsJson = true)] // JSON字段映射
public List Tags { get; set; }
}
```
`IsJson = true` 这个特性很惊艳——可以直接把 `List` 这样的复杂类型映射到数据库的JSON字段，读写时自动序列化/反序列化，省去了手写转换的麻烦。
### Fluent API配置
如果不想用特性，也可以使用Fluent API来配置，两种方式任选：
```csharp
db.CodeFirst.ConfigQuery()
.HasKey(u => u.Id)
.HasIndex(u => u.Name, true) // 唯一索引
.HasColumn(u => u.Name, col => col.IsNullable(false).HasMaxLength(50))
.HasColumn(u => u.Age, col => col.IsNullable(true));
```
### 枚举映射
枚举类型可以直接映射到数据库，配合 `IsEnableUpdateVersionValidation` 还能实现乐观锁：
```csharp
public enum UserStatus
{
Active = 1,
Inactive = 0,
Deleted = -1
}
public class User
{
public int Id { get; set; }
public string Name { get; set; }
[SugarColumn(IsEnableUpdateVersionValidation = true)]
public UserStatus Status { get; set; }
}
```
## 数据库操作
### 数据库初始化
用代码来创建数据库和表，开发环境一键初始化：
```csharp
// 创建数据库
db.DbMaintenance.CreateDatabase();
// 根据实体创建表
db.CodeFirst.InitTables();
// 检查表是否存在
if (!db.DbMaintenance.IsAnyTable("Users"))
{
db.CodeFirst.InitTables();
}
```
### 表结构管理
动态添加列、删除列、重命名表，这些操作同样支持：
```csharp
// 添加列
db.DbMaintenance.AddColumn("Users", new DbColumnInfo
{
DbColumnName = "Email",
DataType = "varchar",
Length = 100,
IsNullable = true
});
// 删除列
db.DbMaintenance.DropColumn("Users", "TempColumn");
// 重命名表
db.DbMaintenance.RenameTable("OldTableName", "NewTableName");
```
### 索引管理
创建、删除、查询索引，API一致且简洁：
```csharp
// 创建索引
db.DbMaintenance.AddIndex("Users", new string[] { "Name", "Age" });
// 删除索引
db.DbMaintenance.DropIndex("Users", "IX_Users_Name_Age");
// 获取索引信息
var indexes = db.DbMaintenance.GetIndexList("Users");
```
## 查询操作
### Lambda表达式查询
查询是ORM的核心，SqlSugar的Lambda查询写得非常顺手：
```csharp
// 基础查询
var users = db.Queryable()
.Where(u => u.Age > 18)
.OrderBy(u => u.CreateTime)
.ToList();
// 复杂条件查询
var result = db.Queryable()
.Where(u => u.Name.Contains("张") && u.Age.HasValue)
.WhereIF(!string.IsNullOrEmpty(searchName), u => u.Name == searchName)
.Select(u => new
{
u.Id,
u.Name,
Age = u.Age ?? 0,
AgeGroup = u.Age > 30 ? "成年" : "青年"
})
.ToList();
```
`WhereIF` 这个扩展方法很实用——条件满足时才加入查询条件，代码干净很多。
### 分页查询
分页有两种方式：`ToPageList` 和 `ToOffsetPage`，前者返回总记录数，后者适合与前端分页组件对接：
```csharp
// 方式一：使用ToPageList
int pageIndex = 1, pageSize = 10;
var pageResult = db.Queryable()
.Where(u => u.Age > 18)
.OrderBy(u => u.Id)
.ToPageList(pageIndex, pageSize);
Console.WriteLine($"总记录数: {pageResult.TotalCount}");
Console.WriteLine($"总页数: {pageResult.TotalPages}");
// 方式二：使用ToOffsetPage
var offsetResult = db.Queryable()
.Where(u => u.Age > 18)
.OrderBy(u => u.Id)
.ToOffsetPage(pageIndex, pageSize);
```
### 联表查询
内连接、左连接，写法都很直观：
```csharp
// 内连接
var result = db.Queryable((u, o) => new JoinQueryInfos(
JoinType.Inner, u.Id == o.UserId))
.Select((u, o) => new
{
UserName = u.Name,
OrderId = o.Id,
OrderAmount = o.Amount
})
.ToList();
// 左连接
var leftJoinResult = db.Queryable()
.LeftJoin((u, o) => u.Id == o.UserId)
.Select((u, o) => new
{
u.Name,
OrderCount = SqlFunc.IsNull(o.Id, 0)
})
.ToList();
```
### 子查询
子查询的支持也很完善，比如找出订单总额超过1000的用户：
```csharp
var subQuery = db.Queryable()
.Where(o => o.Status == OrderStatus.Completed)
.GroupBy(o => o.UserId)
.Select(o => new { UserId = o.UserId, TotalAmount = SqlFunc.Sum(o.Amount) });
var result = db.Queryable()
.Where(u => SqlFunc.Subqueryable(subQuery)
.Where(s => s.UserId == u.Id && s.TotalAmount > 1000)
.Any())
.ToList();
```
### 聚合查询
分组聚合、Ha ving子句，一个不少：
```csharp
// 分组聚合
var groupResult = db.Queryable()
.GroupBy(o => new { o.UserId, o.Status })
.Select(o => new
{
o.UserId,
o.Status,
Count = SqlFunc.Count(o.Id),
TotalAmount = SqlFunc.Sum(o.Amount),
A vgAmount = SqlFunc.A vg(o.Amount),
MaxAmount = SqlFunc.Max(o.Amount),
MinAmount = SqlFunc.Min(o.Amount)
})
.ToList();
// Ha ving子句
var ha vingResult = db.Queryable()
.GroupBy(o => o.UserId)
.Ha ving(o => SqlFunc.Sum(o.Amount) > 5000)
.Select(o => new
{
UserId = o.UserId,
TotalAmount = SqlFunc.Sum(o.Amount)
})
.ToList();
```
## 高级功能
### 事务管理
事务有两种风格：手动控制和使用 `using` 语句自动管理：
```csharp
// 自动事务
try
{
db.BeginTran();
// 执行多个操作
db.Insertable(user).ExecuteCommand();
db.Updateable(order).ExecuteCommand();
db.Deleteable().Where(p => p.Id == 1).ExecuteCommand();
db.CommitTran();
}
catch (Exception ex)
{
db.RollbackTran();
throw;
}
// 使用using语句
using (var tran = db.UseTran())
{
db.Insertable(user).ExecuteCommand();
db.Updateable(order).ExecuteCommand();
tran.Complete(); // 提交事务
}
```
### 批量操作
批量插入、批量更新，用 `Fastest` 方法实现极致性能：
```csharp
// 批量插入
var users = new List();
for (int i = 0; i < 10000; i++)
{
users.Add(new User { Name = $"User{i}", Age = 20 + i % 50 });
}
// 高性能批量插入
db.Fastest().BulkCopy(users);
// 批量更新
var updateUsers = db.Queryable().Where(u => u.Age < 25).ToList();
updateUsers.ForEach(u => u.Age += 1);
db.Fastest().BulkUpdate(updateUsers);
// 批量删除
db.Deleteable().Where(u => u.Age > 60).ExecuteCommand();
```
### 缓存功能
查询结果可以缓存，支持自定义缓存键和过期时间：
```csharp
// 查询缓存
var cachedUsers = db.Queryable()
.Where(u => u.Status == UserStatus.Active)
.WithCache(60) // 缓存60秒
.ToList();
// 自定义缓存键
var customCachedUsers = db.Queryable()
.Where(u => u.Age > 18)
.WithCache("active_users", 300) // 自定义缓存键，缓存5分钟
.ToList();
// 清除缓存
db.RemoveDataCache("active_users");
```
### 读写分离
配置主从库后，查询自动路由到从库，写操作走主库：
```csharp
var configs = new List
{
new ConnectionConfig
{
ConfigId = "master",
ConnectionString = "主库连接字符串",
DbType = DbType.SqlServer,
IsAutoCloseConnection = true
},
new ConnectionConfig
{
ConfigId = "sla ve1",
ConnectionString = "从库1连接字符串",
DbType = DbType.SqlServer,
IsAutoCloseConnection = true,
Sla veConnectionConfigs = new List
{
new Sla veConnectionConfig { HitRate = 50 }, // 50%命中率
}
}
};
var db = new SqlSugarScope(configs);
// 查询自动使用从库
var users = db.Queryable().ToList();
// 强制使用主库查询
var masterUsers = db.GetConnection("master").Queryable().ToList();
```
### 多租户支持
通过表名映射实现多租户，切换租户后自动查询对应的分表：
```csharp
// 配置多租户
db.SetTenantTable("tenant1", "Users_Tenant1");
db.SetTenantTable("tenant2", "Users_Tenant2");
// 切换租户
db.ChangeTenant("tenant1");
var tenant1Users = db.Queryable().ToList(); // 查询Users_Tenant1表
db.ChangeTenant("tenant2");
var tenant2Users = db.Queryable().ToList(); // 查询Users_Tenant2表
```
## 性能优化
### 查询优化
几个实用的优化技巧：
```csharp
// 1. 使用异步操作
var usersAsync = await db.Queryable()
.Where(u => u.Age > 18)
.ToListAsync();
// 2. 只查询需要的字段
var userNames = db.Queryable()
.Select(u => u.Name)
.ToList();
// 3. 使用NoLock（SQL Server）
var noLockUsers = db.Queryable()
.With(SqlWith.NoLock)
.ToList();
// 4. 分页查询大数据量
var largeDataPage = db.Queryable()
.OrderBy(u => u.Id)
.ToOffsetPage(1, 1000);
```
### 连接池优化
通过 `MoreSettings` 配置缓存、Nolock默认行为等：
```csharp
var config = new ConnectionConfig
{
ConnectionString = "连接字符串",
DbType = DbType.SqlServer,
IsAutoCloseConnection = true,
// 连接池配置
ConfigureExternalServices = new ConfigureExternalServices
{
DataInfoCacheService = new HttpRuntimeCache(), // 使用缓存
SqlFuncServices = new List() // 自定义SQL函数
},
// 性能配置
MoreSettings = new ConnMoreSettings
{
IsAutoRemoveDataCache = true, // 自动清理缓存
IsWithNoLockQuery = true, // 默认使用NoLock
DefaultCacheDurationInSeconds = 600 // 默认缓存时间
}
};
```
### SQL优化建议
常见的性能坑，SqlSugar都帮你想好了：
```csharp
// 1. 避免N+1查询问题
var usersWithOrders = db.Queryable()
.Includes(u => u.Orders) // 一次性加载关联数据
.ToList();
// 2. 使用批量操作代替循环
// 错误方式
foreach (var user in users)
{
db.Updateable(user).ExecuteCommand(); // N次数据库访问
}
// 正确方式
db.Updateable(users).ExecuteCommand(); // 1次数据库访问
// 3. 合理使用索引
var indexedQuery = db.Queryable()
.Where(u => u.Email == "test@example.com") // 确保Email字段有索引
.First();
```
## 最佳实践
### 1. 仓储模式实现
定义一个通用的仓储接口和实现，方便依赖注入：
```csharp
public interface IRepository where T : class, new()
{
Task GetByIdAsync(object id);
Task> GetAllAsync();
Task InsertAsync(T entity);
Task UpdateAsync(T entity);
Task DeleteAsync(object id);
}
public class Repository : IRepository where T : class, new()
{
private readonly ISqlSugarClient _db;
public Repository(ISqlSugarClient db)
{
_db = db;
}
public async Task GetByIdAsync(object id)
{
return await _db.Queryable().InSingleAsync(id);
}
public async Task> GetAllAsync()
{
return await _db.Queryable().ToListAsync();
}
public async Task InsertAsync(T entity)
{
return await _db.Insertable(entity).ExecuteCommandAsync() > 0;
}
public async Task UpdateAsync(T entity)
{
return await _db.Updateable(entity).ExecuteCommandAsync() > 0;
}
public async Task DeleteAsync(object id)
{
return await _db.Deleteable().In(id).ExecuteCommandAsync() > 0;
}
}
```
### 2. 依赖注入配置
在Startup或Program中注册SqlSugarClient和仓储：
```csharp
services.AddSingleton(provider =>
{
var config = new ConnectionConfig
{
ConnectionString = Configuration.GetConnectionString("DefaultConnection"),
DbType = DbType.SqlServer,
IsAutoCloseConnection = true,
InitKeyType = InitKeyType.Attribute
};
var db = new SqlSugarClient(config);
// 配置日志
db.Aop.OnLogExecuting = (sql, pars) =>
{
var logger = provider.GetService>();
logger.LogInformation($"SQL: {sql}");
};
return db;
});
services.AddScoped(typeof(IRepository<>), typeof(Repository<>));
```
### 3. 配置管理
将数据库配置抽取到 `appsettings.json` 中，方便不同环境切换：
```csharp
public class DatabaseOptions
{
public string ConnectionString { get; set; }
public string DbType { get; set; }
public bool EnableLogging { get; set; }
public int CommandTimeout { get; set; } = 30;
}
// appsettings.json
{
"Database": {
"ConnectionString": "Server=.;Database=TestDB;Trusted_Connection=true;",
"DbType": "SqlServer",
"EnableLogging": true,
"CommandTimeout": 60
}
}
// 配置使用
services.Configure(Configuration.GetSection("Database"));
```
### 4. 异常处理
实现一个带重试机制的异常处理类，避免临时性数据库故障导致程序崩溃：
```csharp
public class DatabaseExceptionHandler
{
private readonly ILogger _logger;
public DatabaseExceptionHandler(ILogger logger)
{
_logger = logger;
}
public async Task ExecuteWithRetryAsync(Func> operation, int maxRetries = 3)
{
for (int i = 0; i < maxRetries; i++)
{
try
{
return await operation();
}
catch (Exception ex) when (i < maxRetries - 1)
{
_logger.LogWarning($"数据库操作失败，正在重试... 第{i + 1}次，异常: {ex.Message}");
await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, i))); // 指数退避
}
}
return await operation(); // 最后一次尝试，如果失败则抛出异常
}
}
```
### 5. 单元测试
使用SQLite内存数据库进行单元测试，速度快且隔离性好：
```csharp
[TestClass]
public class UserRepositoryTests
{
private ISqlSugarClient _db;
private IRepository _userRepository;
[TestInitialize]
public void Setup()
{
var config = new ConnectionConfig
{
ConnectionString = "测试数据库连接字符串",
DbType = DbType.Sqlite,
IsAutoCloseConnection = true
};
_db = new SqlSugarClient(config);
_db.CodeFirst.InitTables();
_userRepository = new Repository(_db);
}
[TestMethod]
public async Task InsertUser_ShouldReturnTrue()
{
// Arrange
var user = new User { Name = "测试用户", Age = 25 };
// Act
var result = await _userRepository.InsertAsync(user);
// Assert
Assert.IsTrue(result);
Assert.IsTrue(user.Id > 0);
}
[TestCleanup]
public void Cleanup()
{
_db?.Dispose();
}
}
```
## 总结
SqlSugar 是一个功能全面、性能出色的国产ORM框架，它的优势可以归纳为以下几点：
**主要优点**
1. **易于学习**：API设计简洁，中文文档完善，新手也能快速上手。
2. **高性能**：SQL生成机制经过精心优化，批量操作速度惊人。
3. **功能丰富**：从基本的CRUD到事务、缓存、读写分离、多租户，几乎覆盖了所有常见需求。
4. **灵活配置**：支持特性、Fluent API、配置文件等多种方式，扩展点丰富。
5. **活跃社区**：持续更新维护，遇到问题在社区里很容易找到答案。
**适用场景**
- **中小型项目**：快速开发，简单易用，不需要复杂配置。
- **高性能要求**：批量操作、缓存支持，能应对高并发场景。
- **多数据库环境**：跨数据库平台开发，切换成本极低。
- **国产化项目**：对达梦、人大金仓等国产数据库的深度支持，是替代国外ORM的绝佳选择。
**注意事项**
1. **版本选择**：根据项目需求选择合适的版本，LTS版本更稳定。
2. **性能监控**：合理使用日志和监控功能，避免生产环境日志过多影响性能。
3. **安全考虑**：注意SQL注入防护（虽然ORM本身已经做了处理，但原生SQL查询仍需谨慎），以及权限控制。
4. **测试覆盖**：编写充分的单元测试和集成测试，尤其是数据库迁移和批量操作部分。
总的来说，SqlSugar 为.NET开发者提供了一套非常顺手的数据访问解决方案。它不像某些大型框架那样“重”，也不像微ORM那样功能缺失，而是在易用性和功能丰富度之间找到了很好的平衡。在实际项目中，结合具体业务需求，选择合适的特性和配置，开发效率和运行效果都能得到显著提升。
