SQLSugar框架数据库优先

SQLSugar 框架全流程使用指南（数据库优先模式）

数据库优先模式是指先手动创建数据库和表结构，再通过 SQLSugar 进行映射和操作。以下是完整流程，包含数据库设计、实体映射、核心操作及关键 API 说明。

一、数据库与表设计（数据库优先）

1. 创建数据库及表（SQL 脚本）

-- 1. 创建数据库
CREATE DATABASE SqlSugarDB;
GO
​
-- 2. 使用数据库
USE SqlSugarDB;
GO
​
-- 3. 创建用户表
CREATE TABLE [User] (Id INT PRIMARY KEY IDENTITY(1,1),Username NVARCHAR(50) NOT NULL UNIQUE,Password NVARCHAR(100) NOT NULL,Nickname NVARCHAR(50),CreateTime DATETIME DEFAULT GETDATE(),Status TINYINT DEFAULT 1 -- 1:正常 0:禁用
);
GO
​
-- 4. 创建订单表
CREATE TABLE [Order] (Id INT PRIMARY KEY IDENTITY(1,1),OrderNo NVARCHAR(50) NOT NULL UNIQUE,UserId INT NOT NULL,TotalAmount DECIMAL(18,2) NOT NULL,CreateTime DATETIME DEFAULT GETDATE(),FOREIGN KEY (UserId) REFERENCES [User](Id)
);
GO
​
-- 插入测试数据
INSERT INTO [User](Username, Password, Nickname) VALUES
('admin', '123456', '管理员'),
('user1', '654321', '用户1');
​
INSERT INTO [Order](OrderNo, UserId, TotalAmount) VALUES
('ORD2023001', 1, 99.99),
('ORD2023002', 1, 199.99),
('ORD2023003', 2, 49.99);

二、关键类与 API 说明（表格）

类别	类 / API 名称	核心功能	常用方法 / 属性
核心配置	SqlSugarClient	数据库操作核心类	构造函数、Queryable<T>()、Ado
	ConnectionConfig	连接配置类	ConnectionString、DbType、IsAutoCloseConnection
实体映射	[SugarTable]	类与表映射特性	Name（表名）、IsDisabled（是否禁用）
	[SugarColumn]	属性与列映射特性	ColumnName（列名）、IsPrimaryKey、IsIgnore
查询操作	SugarQueryable<T>	链式查询构建器	Where()、OrderBy()、ToList()、ToPageList()
插入操作	Insertable<T>	插入操作构建器	ExecuteReturnIdentity()、ExecuteCommand()
更新操作	Updateable<T>	更新操作构建器	SetColumns()、Where()、ExecuteCommand()
删除操作	Deleteable<T>	删除操作构建器	Where()、In()、ExecuteCommand()
事务管理	db.Ado	事务与原生 SQL 操作	BeginTran()、CommitTran()、RollbackTran()

三、项目初始化与配置

1. 新建项目并安装依赖

• 创建.NET 6 控制台应用（或ASP.NET Core 项目）

• 安装 NuGet 包：

  Install-Package SqlSugar
  Install-Package Microsoft.Data.SqlClient

2. 初始化 SQLSugar 客户端

using SqlSugar;
using System;
using System.Collections.Generic;
using System.Linq;
​
// 连接配置
var connectionConfig = new ConnectionConfig
{ConnectionString = "Server=localhost;Database=SqlSugarDB;Uid=sa;Pwd=YourPassword;TrustServerCertificate=True",DbType = DbType.SqlServer, // 数据库类型IsAutoCloseConnection = true, // 自动关闭连接（推荐）InitKeyType = InitKeyType.Attribute // 通过特性识别主键
};
​
// 创建客户端实例
var db = new SqlSugarClient(connectionConfig);
​
// 测试连接
if (db.Ado.IsValidConnection())
{Console.WriteLine("数据库连接成功！");
}
else
{Console.WriteLine("数据库连接失败，请检查配置！");return;
}

四、实体类定义（映射数据库表）

根据已创建的表结构，定义对应的实体类：

/// <summary>
/// 用户表实体（映射User表）
/// </summary>
[SugarTable("User")] // 对应数据库表名
public class User
{[SugarColumn(IsPrimaryKey = true, IsIdentity = true)] // 主键+自增public int Id { get; set; }
​[SugarColumn(Length = 50, IsNullable = false)] // 对应Username列public string Username { get; set; }
​[SugarColumn(Length = 100, IsNullable = false)] // 对应Password列public string Password { get; set; }
​[SugarColumn(Length = 50)] // 对应Nickname列public string Nickname { get; set; }
​[SugarColumn] // 对应CreateTime列public DateTime CreateTime { get; set; }
​[SugarColumn] // 对应Status列public int Status { get; set; }
​// 导航属性（一对多：一个用户多个订单）[SugarColumn(IsIgnore = true)] // 不映射到数据库列public List<Order> Orders { get; set; }
}
​
/// <summary>
/// 订单表实体（映射Order表）
/// </summary>
[SugarTable("Order")]
public class Order
{[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]public int Id { get; set; }
​[SugarColumn(Length = 50, IsNullable = false)]public string OrderNo { get; set; }
​[SugarColumn]public int UserId { get; set; }
​[SugarColumn]public decimal TotalAmount { get; set; }
​[SugarColumn]public DateTime CreateTime { get; set; }
​// 导航属性（多对一：一个订单属于一个用户）[SugarColumn(IsIgnore = true)]public User User { get; set; }
}

五、完整 CRUD 操作示例

1. 查询操作

Console.WriteLine("===== 查询操作 =====");
​
// 1. 查询所有用户
var allUsers = db.Queryable<User>().ToList();
Console.WriteLine("所有用户：");
allUsers.ForEach(u => Console.WriteLine($"ID:{u.Id}, 用户名:{u.Username}, 昵称:{u.Nickname}"));
​
// 2. 条件查询（查询状态正常的用户）
var activeUsers = db.Queryable<User>().Where(u => u.Status == 1).OrderBy(u => u.CreateTime, OrderByType.Desc).ToList();
Console.WriteLine("\n状态正常的用户：");
activeUsers.ForEach(u => Console.WriteLine($"{u.Username}（创建时间：{u.CreateTime:yyyy-MM-dd}）"));
​
// 3. 连表查询（查询用户及其订单）
var userWithOrders = db.Queryable<User>().LeftJoin<Order>((u, o) => u.Id == o.UserId).Where(u => u.Id == 1).Select((u, o) => new {用户名 = u.Username,订单号 = o.OrderNo,订单金额 = o.TotalAmount,下单时间 = o.CreateTime}).ToList();
Console.WriteLine("\n用户1的订单：");
userWithOrders.ForEach(item => Console.WriteLine($"{item.订单号} - 金额：{item.订单金额} - 时间：{item.下单时间:yyyy-MM-dd}"));
​
// 4. 分页查询订单（第1页，每页2条）
int pageIndex = 1;
int pageSize = 2;
var totalOrders = 0;
var orderPageData = db.Queryable<Order>().OrderBy(o => o.CreateTime, OrderByType.Desc).ToPageList(pageIndex, pageSize, ref totalOrders);
Console.WriteLine($"\n订单分页（第{pageIndex}页）：共{totalOrders}条");
orderPageData.ForEach(o => Console.WriteLine($"{o.OrderNo} - 用户ID:{o.UserId} - 金额:{o.TotalAmount}"));

2. 插入操作

Console.WriteLine("\n===== 插入操作 =====");
​
// 1. 插入新用户
var newUser = new User
{Username = "user2",Password = "abc123",Nickname = "用户2",Status = 1
};
int newUserId = db.Insertable(newUser).ExecuteReturnIdentity();
Console.WriteLine($"插入新用户成功，ID：{newUserId}");
​
// 2. 为新用户插入订单
var newOrder = new Order
{OrderNo = $"ORD{DateTime.Now:yyyyMMddHHmmss}",UserId = newUserId,TotalAmount = 299.99m
};
int newOrderId = db.Insertable(newOrder).ExecuteReturnIdentity();
Console.WriteLine($"插入新订单成功，ID：{newOrderId}");

3. 更新操作

Console.WriteLine("\n===== 更新操作 =====");
​
// 1. 更新用户昵称
var updateUser = new User { Id = newUserId, Nickname = "用户2（已更新）" };
int updateUserCount = db.Updateable(updateUser).IgnoreColumns(u => new { u.Username, u.Password }) // 只更新昵称.ExecuteCommand();
Console.WriteLine($"更新用户昵称：影响{updateUserCount}条");
​
// 2. 批量更新订单金额（用户1的订单金额增加10元）
int updateOrderCount = db.Updateable<Order>().SetColumns(o => o.TotalAmount += 10).Where(o => o.UserId == 1).ExecuteCommand();
Console.WriteLine($"批量更新订单金额：影响{updateOrderCount}条");

4. 删除操作

Console.WriteLine("\n===== 删除操作 =====");
​
// 删除用户2的订单（根据条件）
int deleteOrderCount = db.Deleteable<Order>().Where(o => o.UserId == newUserId).ExecuteCommand();
Console.WriteLine($"删除订单：影响{deleteOrderCount}条");
​
// 删除用户2（根据ID）
int deleteUserCount = db.Deleteable<User>(newUserId).ExecuteCommand();
Console.WriteLine($"删除用户：影响{deleteUserCount}条");

5. 事务操作

Console.WriteLine("\n===== 事务操作 =====");try
{db.Ado.BeginTran(); // 开始事务// 事务内操作：创建用户并创建订单var tranUser = new User { Username = "tranUser", Password = "tran123", Nickname = "事务用户" };int tranUserId = db.Insertable(tranUser).ExecuteReturnIdentity();db.Insertable(new Order { OrderNo = $"ORD{DateTime.Now:yyyyMMddHHmmss}_TRAN",UserId = tranUserId,TotalAmount = 159.99m }).ExecuteCommand();db.Ado.CommitTran(); // 提交事务Console.WriteLine("事务执行成功！");
}
catch (Exception ex)
{db.Ado.RollbackTran(); // 回滚事务Console.WriteLine($"事务失败：{ex.Message}");
}

六、数据库优先模式关键点

1. 实体映射：需确保实体类属性与数据库表字段一一对应，可通过[SugarColumn(ColumnName)]处理名称不一致的情况。

2. 导航属性：通过[SugarColumn(IsIgnore = true)]标记，不映射到数据库，用于关联查询。

3. 原生 SQL 支持

   ：数据库优先模式下可直接执行原生 SQL：

   // 执行原生查询
   var sql = "SELECT * FROM [User] WHERE Status = @Status";
   var users = db.Ado.SqlQuery<User>(sql, new { Status = 1 });

4. 性能优化：查询时使用Select()指定需要的字段，减少数据传输。

七、总结

数据库优先模式适合已有数据库结构的项目，通过 SQLSugar 可快速实现实体映射和 CRUD 操作。核心优势在于：

• 链式 API 简化查询逻辑

• 自动管理数据库连接

• 完善的事务支持

• 灵活的导航属性关联

通过上述流程，可快速上手 SQLSugar 在数据库优先场景下的使用，大幅提升数据操作开发效率。