当前位置： 首页 > news >正文

SqlSugar ORM框架详解

news 来源：原创 2025/6/18 11:31:14

目录

  • 简介
  • 特性与优势
  • 安装与配置
  • 基础使用
  • 实体映射
  • 数据库操作
  • 查询操作
  • 高级功能
  • 性能优化
  • 最佳实践
  • 总结

简介

SqlSugar是一个轻量级、高性能的.NET ORM框架，由中国开发者维护，专为简化数据库操作而设计。它支持多种数据库，提供了丰富的功能和优秀的性能表现，是.NET开发中非常受欢迎的ORM选择。

为什么选择SqlSugar？

  • 轻量级：框架体积小，启动快速
  • 高性能：优化的SQL生成和执行机制
  • 易用性：简洁的API设计，学习成本低
  • 多数据库支持：支持主流数据库系统
  • 中文文档：完善的中文文档和社区支持

特性与优势

核心特性

  1. 多数据库支持

    • SQL Server
    • MySQL
    • PostgreSQL
    • Oracle
    • SQLite
    • 达梦数据库
    • 人大金仓等国产数据库

  2. 丰富的查询方式

    • Lambda表达式查询
    • SQL语句查询
    • 存储过程调用
    • 动态查询构建

  3. 代码生成功能

    • 根据数据库表生成实体类
    • 自动生成仓储层代码
    • 支持模板自定义

  4. 事务管理

    • 自动事务管理
    • 手动事务控制
    • 分布式事务支持

性能优势

// 高性能的批量操作
var users = new List<User>();
for (int i = 0; i < 10000; i++)
{users.Add(new User { Name = $"User{i}", Age = 20 + i % 50 });
}// 批量插入，性能优异
db.Insertable(users).ExecuteCommand();

安装与配置

NuGet包安装

# 核心包
Install-Package SqlSugar# 特定数据库扩展
Install-Package SqlSugar.SqlServer
Install-Package SqlSugar.MySql
Install-Package SqlSugar.PostgreSQL

基础配置

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}"))}");
};

多数据库配置

var configs = new List<ConnectionConfig>
{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("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; }
}

基本CRUD操作

// 插入
var user = new User { Name = "张三", Age = 25, CreateTime = DateTime.Now };
var id = db.Insertable(user).ExecuteReturnIdentity();// 查询
var users = db.Queryable<User>().ToList();
var user = db.Queryable<User>().Where(u => u.Id == 1).First();// 更新
db.Updateable<User>().SetColumns(u => new User { Age = 26 }).Where(u => u.Id == 1).ExecuteCommand();// 删除
db.Deleteable<User>().Where(u => u.Id == 1).ExecuteCommand();

实体映射

特性配置

[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<string> Tags { get; set; }
}

Fluent API配置

db.CodeFirst.ConfigQuery<User>().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));

枚举映射

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; }
}

数据库操作

数据库初始化

// 创建数据库
db.DbMaintenance.CreateDatabase();// 根据实体创建表
db.CodeFirst.InitTables<User, Product, Order>();// 检查表是否存在
if (!db.DbMaintenance.IsAnyTable("Users"))
{db.CodeFirst.InitTables<User>();
}

表结构管理

// 添加列
db.DbMaintenance.AddColumn("Users", new DbColumnInfo
{DbColumnName = "Email",DataType = "varchar",Length = 100,IsNullable = true
});// 删除列
db.DbMaintenance.DropColumn("Users", "TempColumn");// 重命名表
db.DbMaintenance.RenameTable("OldTableName", "NewTableName");

索引管理

// 创建索引
db.DbMaintenance.AddIndex("Users", new string[] { "Name", "Age" });// 删除索引
db.DbMaintenance.DropIndex("Users", "IX_Users_Name_Age");// 获取索引信息
var indexes = db.DbMaintenance.GetIndexList("Users");

查询操作

Lambda表达式查询

// 基础查询
var users = db.Queryable<User>().Where(u => u.Age > 18).OrderBy(u => u.CreateTime).ToList();// 复杂条件查询
var result = db.Queryable<User>().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();

分页查询

// 方式一：使用ToPageList
int pageIndex = 1, pageSize = 10;
var pageResult = db.Queryable<User>().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<User>().Where(u => u.Age > 18).OrderBy(u => u.Id).ToOffsetPage(pageIndex, pageSize);

联表查询

// 内连接
var result = db.Queryable<User, Order>((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<User>().LeftJoin<Order>((u, o) => u.Id == o.UserId).Select((u, o) => new{u.Name,OrderCount = SqlFunc.IsNull(o.Id, 0)}).ToList();

子查询

// 子查询示例
var subQuery = db.Queryable<Order>().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<User>().Where(u => SqlFunc.Subqueryable(subQuery).Where(s => s.UserId == u.Id && s.TotalAmount > 1000).Any()).ToList();

聚合查询

// 分组聚合
var groupResult = db.Queryable<Order>().GroupBy(o => new { o.UserId, o.Status }).Select(o => new{o.UserId,o.Status,Count = SqlFunc.Count(o.Id),TotalAmount = SqlFunc.Sum(o.Amount),AvgAmount = SqlFunc.Avg(o.Amount),MaxAmount = SqlFunc.Max(o.Amount),MinAmount = SqlFunc.Min(o.Amount)}).ToList();// Having子句
var havingResult = db.Queryable<Order>().GroupBy(o => o.UserId).Having(o => SqlFunc.Sum(o.Amount) > 5000).Select(o => new{UserId = o.UserId,TotalAmount = SqlFunc.Sum(o.Amount)}).ToList();

高级功能

事务管理

// 自动事务
try
{db.BeginTran();// 执行多个操作db.Insertable(user).ExecuteCommand();db.Updateable(order).ExecuteCommand();db.Deleteable<Product>().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(); // 提交事务
}

批量操作

// 批量插入
var users = new List<User>();
for (int i = 0; i < 10000; i++)
{users.Add(new User { Name = $"User{i}", Age = 20 + i % 50 });
}// 高性能批量插入
db.Fastest<User>().BulkCopy(users);// 批量更新
var updateUsers = db.Queryable<User>().Where(u => u.Age < 25).ToList();
updateUsers.ForEach(u => u.Age += 1);
db.Fastest<User>().BulkUpdate(updateUsers);// 批量删除
db.Deleteable<User>().Where(u => u.Age > 60).ExecuteCommand();

缓存功能

// 查询缓存
var cachedUsers = db.Queryable<User>().Where(u => u.Status == UserStatus.Active).WithCache(60) // 缓存60秒.ToList();// 自定义缓存键
var customCachedUsers = db.Queryable<User>().Where(u => u.Age > 18).WithCache("active_users", 300) // 自定义缓存键，缓存5分钟.ToList();// 清除缓存
db.RemoveDataCache("active_users");

读写分离

var configs = new List<ConnectionConfig>
{new ConnectionConfig{ConfigId = "master",ConnectionString = "主库连接字符串",DbType = DbType.SqlServer,IsAutoCloseConnection = true},new ConnectionConfig{ConfigId = "slave1",ConnectionString = "从库1连接字符串",DbType = DbType.SqlServer,IsAutoCloseConnection = true,SlaveConnectionConfigs = new List<SlaveConnectionConfig>{new SlaveConnectionConfig { HitRate = 50 }, // 50%命中率}}
};var db = new SqlSugarScope(configs);// 查询自动使用从库
var users = db.Queryable<User>().ToList();// 强制使用主库查询
var masterUsers = db.GetConnection("master").Queryable<User>().ToList();

多租户支持

// 配置多租户
db.SetTenantTable("tenant1", "Users_Tenant1");
db.SetTenantTable("tenant2", "Users_Tenant2");// 切换租户
db.ChangeTenant("tenant1");
var tenant1Users = db.Queryable<User>().ToList(); // 查询Users_Tenant1表db.ChangeTenant("tenant2");
var tenant2Users = db.Queryable<User>().ToList(); // 查询Users_Tenant2表

性能优化

查询优化

// 1. 使用异步操作
var usersAsync = await db.Queryable<User>().Where(u => u.Age > 18).ToListAsync();// 2. 只查询需要的字段
var userNames = db.Queryable<User>().Select(u => u.Name).ToList();// 3. 使用NoLock（SQL Server）
var noLockUsers = db.Queryable<User>().With(SqlWith.NoLock).ToList();// 4. 分页查询大数据量
var largeDataPage = db.Queryable<User>().OrderBy(u => u.Id).ToOffsetPage(1, 1000);

连接池优化

var config = new ConnectionConfig
{ConnectionString = "连接字符串",DbType = DbType.SqlServer,IsAutoCloseConnection = true,// 连接池配置ConfigureExternalServices = new ConfigureExternalServices{DataInfoCacheService = new HttpRuntimeCache(), // 使用缓存SqlFuncServices = new List<SqlFuncExternal>() // 自定义SQL函数},// 性能配置MoreSettings = new ConnMoreSettings{IsAutoRemoveDataCache = true, // 自动清理缓存IsWithNoLockQuery = true, // 默认使用NoLockDefaultCacheDurationInSeconds = 600 // 默认缓存时间}
};

SQL优化建议

// 1. 避免N+1查询问题
var usersWithOrders = db.Queryable<User>().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<User>().Where(u => u.Email == "test@example.com") // 确保Email字段有索引.First();

最佳实践

1. 仓储模式实现

public interface IRepository<T> where T : class, new()
{Task<T> GetByIdAsync(object id);Task<List<T>> GetAllAsync();Task<bool> InsertAsync(T entity);Task<bool> UpdateAsync(T entity);Task<bool> DeleteAsync(object id);
}public class Repository<T> : IRepository<T> where T : class, new()
{private readonly ISqlSugarClient _db;public Repository(ISqlSugarClient db){_db = db;}public async Task<T> GetByIdAsync(object id){return await _db.Queryable<T>().InSingleAsync(id);}public async Task<List<T>> GetAllAsync(){return await _db.Queryable<T>().ToListAsync();}public async Task<bool> InsertAsync(T entity){return await _db.Insertable(entity).ExecuteCommandAsync() > 0;}public async Task<bool> UpdateAsync(T entity){return await _db.Updateable(entity).ExecuteCommandAsync() > 0;}public async Task<bool> DeleteAsync(object id){return await _db.Deleteable<T>().In(id).ExecuteCommandAsync() > 0;}
}

2. 依赖注入配置

// Startup.cs 或 Program.cs
services.AddSingleton<ISqlSugarClient>(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<ILogger<SqlSugarClient>>();logger.LogInformation($"SQL: {sql}");};return db;
});services.AddScoped(typeof(IRepository<>), typeof(Repository<>));

3. 配置管理

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<DatabaseOptions>(Configuration.GetSection("Database"));

4. 异常处理

public class DatabaseExceptionHandler
{private readonly ILogger<DatabaseExceptionHandler> _logger;public DatabaseExceptionHandler(ILogger<DatabaseExceptionHandler> logger){_logger = logger;}public async Task<T> ExecuteWithRetryAsync<T>(Func<Task<T>> 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. 单元测试

[TestClass]
public class UserRepositoryTests
{private ISqlSugarClient _db;private IRepository<User> _userRepository;[TestInitialize]public void Setup(){var config = new ConnectionConfig{ConnectionString = "测试数据库连接字符串",DbType = DbType.Sqlite,IsAutoCloseConnection = true};_db = new SqlSugarClient(config);_db.CodeFirst.InitTables<User>();_userRepository = new Repository<User>(_db);}[TestMethod]public async Task InsertUser_ShouldReturnTrue(){// Arrangevar user = new User { Name = "测试用户", Age = 25 };// Actvar result = await _userRepository.InsertAsync(user);// AssertAssert.IsTrue(result);Assert.IsTrue(user.Id > 0);}[TestCleanup]public void Cleanup(){_db?.Dispose();}
}

总结

SqlSugar是一个功能强大、性能优异的.NET ORM框架，具有以下优势：

主要优点

  1. 易于学习：简洁的API设计，完善的中文文档
  2. 高性能：优化的SQL生成和执行机制
  3. 功能丰富：支持多种数据库操作和高级功能
  4. 灵活配置：支持多种配置方式和扩展点
  5. 活跃社区：持续更新和维护，社区支持良好

适用场景

  • 中小型项目：快速开发，简单易用
  • 高性能要求：批量操作，缓存支持
  • 多数据库环境：跨数据库平台开发
  • 国产化项目：支持国产数据库

注意事项

  1. 版本选择：根据项目需求选择合适的版本
  2. 性能监控：合理使用日志和监控功能
  3. 安全考虑：注意SQL注入防护和权限控制
  4. 测试覆盖：编写充分的单元测试和集成测试

SqlSugar为.NET开发者提供了一个优秀的数据访问解决方案，通过合理使用其功能特性，可以大大提高开发效率和应用性能。在实际项目中，建议结合具体业务需求，选择合适的功能和配置，以达到最佳的开发体验和运行效果。

相关文章：

  • QT学习一
  • set和map简单模拟实现
  • Ansible常用模块
  • 如何做好一份网络安全技术文档？
  • java中的线程安全的集合
  • 航空航天领域对滚珠丝杆的精度要求有多高？
  • 汉诺集团CDN+富氢水机全球发布：科技赋能健康，革新饮水革命
  • Java大师成长计划之第31天：Docker与Java应用容器化
  • 消防营区管理升级：豪越科技智能仓储与装备管理的力量
  • 解锁webpack：处理跨域devserver、摇树treeshaking、图片压缩sharp
  • xhr、fetch和axios
  • 第Y1周打卡——调用官方权重进行检测
  • O2OA服务器配置与管理-自定义消息提醒
  • 【Java学习笔记】单例设计模式
  • Netty应用：从零搭建Java游戏服务器网络框架
  • 进程通信(管道，共享内存实现)
  • Java设计模式之责任链模式：从基础到高级的全面解析
  • AutoKeras的模型保存与加载
  • 广东省省考备考（第二十一天5.26）—言语（第八节课）
  • 《软件工程》第 5 章 - 需求分析模型的表示
  • 网站推广软文选择天天软文/电商网站入口
  • 游族网络公司最新消息/seo按照搜索引擎的什么对网站
  • 如何将网站和域名绑定/网上销售培训课程
  • 南阳网站推广方案/网站优化分析
  • 做网站的必备软件/百度排行
  • java做的是网站还是系统/搜索seo优化托管