SqlSugar ORM 基础使用教程

1. 简介

SqlSugar 是一款轻量级、高性能的国产 ORM 框架，支持主流数据库（MySQL/SQL Server/Oracle/PostgreSQL等），具有以下特点：

• 简单易用的 Lambda 表达式查询

• 强大的分库分表支持

• 完善的 Code First 开发体验

• 高性能（官方基准测试优于大部分主流ORM）

• 支持 .NET Framework 4.6+ 和 .NET Core 2.0+

  2. 环境准备

  2.1 安装

  通过 NuGet 包管理器安装：

  Install-Package SqlSugar

  2.2 数据库准备

  以 MySQL 为例，创建示例数据库：

  CREATE DATABASE SampleDB;
  USE SampleDB;
  CREATE TABLE Users (
      Id INT PRIMARY KEY AUTO_INCREMENT,
      Name VARCHAR(50) NOT NULL,
      Age INT,
      CreateTime DATETIME DEFAULT CURRENT_TIMESTAMP
  );

  3. 基础配置

  3.1 创建实体类

  [SugarTable("Users")]
  public class User
  {
      [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
      public int Id { get; set; }
      
      [SugarColumn(Length = 50)]
      public string Name { get; set; }
      
      public int? Age { get; set; }
      
      [SugarColumn(IsNullable = true)]
      public DateTime CreateTime { get; set; }
  }

  3.2 实体配置-配置SugarColumn属性

  在 SqlSugar 中，SugarColumn 属性用于配置列的元数据信息，这对于 ORM 映射非常重要。下面是一些常见的 SugarColumn 属性及其用途：

  1、ColumnName-指定数据库表中对应的列名。

  2、IsNullable-指定列是否可以为 NULL。

  3、IsIdentity-指定列是否为自增列。

  4、IsPrimaryKey-指定列是否为主键。

  5、DbType-指定列的数据类型。

  6、Length-指定列的最大长度。

  7、CSharpType-指定 C# 中的类型

  
  （图片来源网络，侵删）

  8、IsIgnore-指定是否忽略此属性

  9、DefaultValue-指定默认值

  
  （图片来源网络，侵删）

  3.3 初始化SqlSugarClient

  public class DbContext
  {
      public static SqlSugarClient GetInstance()
      {
          return new SqlSugarClient(new ConnectionConfig()
          {
              ConnectionString = "Server=localhost;Database=SampleDB;Uid=root;Pwd=123456;",
              DbType = DbType.MySql,
              IsAutoCloseConnection = true,
              InitKeyType = InitKeyType.Attribute
          });
      }
  }

  4. 基础CRUD操作

  4.1 插入数据

  using var db = DbContext.GetInstance();
  // 插入单条
  var user = new User { Name = "张三", Age = 25 };
  int id = db.Insertable(user).ExecuteReturnIdentity();
  // 批量插入
  var users = new List
  {
      new User { Name = "李四", Age = 30 },
      new User { Name = "王五", Age = 28 }
  };
  db.Insertable(users).ExecuteCommand();

  4.2 查询数据

  // 查询所有
  var list = db.Queryable().ToList();
  // 条件查询
  var user = db.Queryable()
              .Where(u => u.Age > 25)
              .First();
  // 分页查询
  var pageList = db.Queryable()
                  .Where(u => u.Age > 20)
                  .ToPageList(1, 10, ref totalCount);

  4.3 更新数据

  // 更新整个实体
  user.Name = "修改后的名字";
  db.Updateable(user).ExecuteCommand();
  // 条件更新
  db.Updateable()
    .SetColumns(u => u.Age == 30)
    .Where(u => u.Id == 1)
    .ExecuteCommand();

  4.4 删除数据

  // 根据主键删除
  db.Deleteable(1).ExecuteCommand();
  // 条件删除
  db.Deleteable()
    .Where(u => u.Age  
   
  5. 事务处理
   
   
  try
  {
      db.Ado.BeginTran();
      
      // 业务操作1
      db.Insertable(user1).ExecuteCommand();
      
      // 业务操作2
      db.Updateable(user2).ExecuteCommand();
      
      db.Ado.CommitTran();
  }
  catch(Exception ex)
  {
      db.Ado.RollbackTran();
      throw;
  }
   
   
  6. 高级功能示例
   
  6.1 联表查询
   
   
  var query = db.Queryable((u, o) => u.Id == o.UserId)
              .Where((u, o) => u.Age > 25)
              .Select((u, o) => new
              {
                  UserName = u.Name,
                  OrderNo = o.OrderNumber
              })
              .ToList();
   
   
   
  7. 最佳实践
   
  7.1 性能优化
   
  

  • 批量操作使用Insertable(list).ExecuteCommand()代替循环插入

  • 频繁查询的字段添加索引

    
    （图片来源网络，侵删）

  • 使用AsQueryable()延迟查询

    7.2 代码规范

    • 实体类使用[SugarTable]和[SugarColumn]显式配置

    • 复杂查询使用Lambda表达式保持强类型

    • 事务范围尽量缩小

      7.3 常见问题

      1. 日期格式问题：

         配置MySql全局日期格式：

         db.Ado.ExecuteCommand("SET GLOBAL sql_mode='STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION';");

      2. 导航属性加载：

         使用Mapper方法实现：

         var user = db.Queryable()
                     .Mapper(u => u.Orders, u => u.Id)
                     .First();

      8. 扩展阅读

      • 官方文档：SqlSugar .Net ORM 5.X 官网 、文档、教程 - SqlSugar 5x - .NET果糖网

      • GitHub仓库：https://github.com/donet5/SqlSugar