RuoVea.ExSugar 10.0.0.8

🍬 RuoVea.ExSugar

SqlSugar ORM 一站式扩展库 — 集成 DI 注册、DbContext/Repository 模式、审计字段自动填充、全局查询过滤器、工作单元事务、差异日志记录、SM2 连接字符串加密，覆盖从 DataExecuting AOP 到分页查询的完整数据访问层抽象。

📖 目录

• 📋 概览
• 📦 安装
• ⚡ 30 秒快速开始
• 🧩 核心场景
  • 场景一：DbContext 模式
  • 场景二：Repository 仓储模式
  • 场景三：审计字段自动填充
  • 场景四：全局查询过滤器
  • 场景五：工作单元事务
  • 场景六：差异日志记录
  • 场景七：连接字符串 SM2 加密
• ⚙️ 配置选项详解
• 🏗️ 实体基类体系
• 📐 SQL 扩展方法
• 📄 分页查询
• 🧵 线程安全与生命周期
• ⚠️ 已知问题与注意事项
• 🗺️ 版本迁移指南

📋 概览

RuoVea.ExSugar 为 .NET 开发者提供 SqlSugar ORM 的开箱即用增强封装，通过 DI 容器统一管理数据库连接、审计字段、查询过滤器和事务边界。

 ┌─────────────────────────────────────────────────────────┐
 │                    RuoVea.ExSugar                        │
 ├─────────────────────────────────────────────────────────┤
 │  DI 注册              实体基类            仓储模式       │
 │  ├─ AddSqlSugarSetup   ├─ EntityBase      ├─ SugarRepository<T>
 │  ├─ AddDbContextSetup   ├─ EntityTenant    └─ SimpleClient<T>
 │  └─ AddInjectServiceSetup├─ AutoKeyBase                  │
 │                          └─ AutoKeyEntityBase             │
 │                                                           │
 │  审计 AOP             全局过滤器           工作单元       │
 │  ├─ DataExecuting      ├─ 软删除过滤器     ├─ UnitOfWorkAttribute
 │  ├─ 创建时间自动填充    ├─ 用户Id过滤器     └─ UnitOfWorkFilter
 │  ├─ 修改时间自动填充    ├─ 租户Id过滤器                    │
 │  ├─ 雪花Id自动生成      └─ moreFilter                     │
 │  └─ 租户Id自动设置                                        │
 │                                                           │
 │  差异日志             连接安全             扩展方法       │
 │  ├─ OnDiffLogEvent     ├─ SM2 加密解密     ├─ SqlSugarClient
 │  ├─ UpdateWithDiffLog  └─ IsEncrypt        │   扩展 (40+ 方法)
 │  └─ InsertWithDiffLog                       └─ ISugarQueryable
 │                                               分页扩展     │
 ├─────────────────────────────────────────────────────────┤
 │  国际化: zh-CN                                         │
 └─────────────────────────────────────────────────────────┘

设计原则

📦 安装

.NET CLI

# .NET 8.0
dotnet add package RuoVea.ExSugar --version 8.0.0.33

# .NET 10.0
dotnet add package RuoVea.ExSugar --version 10.0.0.7

Package Manager

Install-Package RuoVea.ExSugar -Version 8.0.0.33

PackageReference

<PackageReference Include="RuoVea.ExSugar" Version="8.0.0.33" />

框架引用要求

RuoVea.ExSugar 需要 Microsoft.AspNetCore.App 框架引用（自动包含在 ASP.NET Core 项目中）：

<FrameworkReference Include="Microsoft.AspNetCore.App" />

支持的 Target Framework

传递依赖

⚡ 30 秒快速开始

1. 配置 appsettings.json

{
  "ConnectionConfigs": [
    {
      "ConfigId": "1300000000001",
      "DbType": "MySql",
      "ConnectionString": "Server=127.0.0.1;Database=MyDb;Uid=root;Pwd=123456;",
      "IsAutoCloseConnection": true,
      "EnableDiffLog": false,
      "EnableUnderLine": true,
      "IsEncrypt": false,
      "IsDeleteFilter": true,
      "IsUserIdFilter": false,
      "IsTenantIdFilter": false,
      "CommandTimeOut": 30
    }
  ],
  "DataAuditing": {
    "CreateTime": "CreateTime",
    "ModifyTime": "ModifyTime",
    "Creator": "Creator",
    "Modifier": "Modifier",
    "TenantId": "TenantId",
    "IsDelete": "IsDelete"
  }
}

⚠️ 注意: DataAuditing.TenantId 的默认值是 "CreateTime"（疑似 Bug），务必在配置文件中显式覆写为 "TenantId"。

2. 注册服务

// Program.cs / Startup.cs
using RuoVea.ExSugar;

// <inheritdoc cref="SqlSugarSetup.AddSqlSugarSetup(IServiceCollection, bool, ICacheService, ServiceLifetime, Action{SqlSugarScopeProvider})"/>
// 方式一：从 appsettings.json 自动读取（最简）
builder.Services.AddSqlSugarSetup();

// 方式二：显式传入 IConfiguration
builder.Services.AddSqlSugarSetup(builder.Configuration);

// 方式三：代码构建配置
builder.Services.AddSqlSugarSetup(configs =>
{
    configs.Add(new DbConnectionConfig
    {
        ConfigId = "1300000000001",
        DbType = SqlSugar.DbType.MySql,
        ConnectionString = "Server=127.0.0.1;Database=MyDb;Uid=root;Pwd=123456;",
        EnableUnderLine = true
    });
});

3. 使用 SugarRepository

// <inheritdoc cref="SugarRepository{T}"/>
public class UserService
{
    private readonly SugarRepository<MyUser> _userRepo;

    public UserService(SugarRepository<MyUser> userRepo)
    {
        _userRepo = userRepo;
    }

    public async Task<List<MyUser>> GetAllAsync()
    {
        return await _userRepo.GetListAsync(u => u.IsDelete == IsDelete.N, u => u.Id);
    }

    public async Task<MyUser?> GetByIdAsync(long id)
    {
        return await _userRepo.GetFirstAsync(u => u.Id == id, u => u.Id);
    }
}

30 秒内你完成了: 配置文件编写 → DI 注册 → 使用泛型仓储查询数据。审计字段自动填充、软删除过滤、连接池管理全部由底层 AOP 接管。

🧩 核心场景

场景一：DbContext 模式

┌──────────────────┐
│  自定义 DbContext  │   继承 abstract class DbContext
│  (e.g. MyDbCtx)  │   实现 IDbContext, IDisposable
└────────┬─────────┘
         │ 注入
         ▼
┌──────────────────┐
│  services.       │   AddDbContextSetup<MyDbCtx>(sp => new MyDbCtx(config))
│  AddDbContextSetup│
└──────────────────┘

// <inheritdoc cref="DbContext.DbContext(DbConnectionConfig, int, ICurrentUser, IRestFulLog, bool, bool, bool, Action{SqlSugarScopeProvider})"/>
/// <summary>
/// 自定义数据库上下文，继承抽象基类 DbContext
/// </summary>
public class MyDbContext : DbContext
{
    public MyDbContext(DbConnectionConfig config,
        ICurrentUser currentUser = null,
        IRestFulLog restFulLog = null)
        : base(config, commandTimeOut: 30,
              currentUser: currentUser,
              restFulLog: restFulLog,
              userIdFilter: false,
              tenantIdFilter: false,
              deleteFilter: true)
    {
    }

    // 使用 db 字段访问 SqlSugarClient
    public List<MyUser> GetActiveUsers() =>
        db.ToList<MyUser>(u => u.IsDelete == IsDelete.N);
}

// 注册
builder.Services.AddDbContextSetup(sp =>
{
    var config = new DbConnectionConfig
    {
        ConfigId = "1300000000001",
        DbType = SqlSugar.DbType.MySql,
        ConnectionString = "Server=127.0.0.1;Database=MyDb;Uid=root;Pwd=123456;"
    };
    return new MyDbContext(config,
        sp.GetService<ICurrentUser>(),
        sp.GetService<IRestFulLog>());
});

⚠️ 注意: DbContext 构造函数内有两个重载 —— 一个接收 DbConnectionConfig，另一个接收基类 ConnectionConfig。推荐使用 DbConnectionConfig 重载以启用完整功能（差异日志、过滤器等）。第一个重载中存在 Bug：SugarUtil.SqlSugarClientUtil(db, ...) 的 db 参数传入了未初始化的字段而非局部变量 _db。

场景二：Repository 仓储模式

┌─────────────────────────┐
│  SugarRepository<T>      │   继承 SimpleClient<T>
│  ─────────────────────  │   自动排除 SystemTable 实体
│  ├─ GetPageResultAsync   │
│  ├─ GetFirstAsync        │
│  ├─ GetListAsync         │
│  ├─ SumAsync             │
│  ├─ Insert / InsertAsync │
│  └─ Update / UpdateAsync │
└─────────────────────────┘

// <inheritdoc cref="SugarRepository{T}.GetPageResultAsync"/>
// 分页查询
var (list, total, totalPage) = await _repo.GetPageResultAsync(
    where: u => u.IsDelete == IsDelete.N,
    pageNo: 1,
    pageSize: 20,
    order: u => u.CreateTime,
    orderEnum: SordEnum.Desc
);

// <inheritdoc cref="SugarRepository{T}.GetFirstAsync"/>
// 获取最新一条
var latest = await _repo.GetFirstAsync(
    where: u => u.Status == 1,
    order: u => u.CreateTime,
    orderEnum: SordEnum.Desc
);

// <inheritdoc cref="SugarRepository{T}.GetListAsync"/>
// 条件列表查询
var list = await _repo.GetListAsync(
    where: u => u.Creator == userId,
    order: u => u.Id
);

// <inheritdoc cref="SugarRepository{T}.SumAsync"/>
// 求和
var totalAmount = await _repo.SumAsync(
    where: u => u.IsDelete == IsDelete.N,
    expression: u => u.Amount
);

// <inheritdoc cref="SugarRepository{T}.Insert(T, bool, bool, object)"/>
// 插入（可选差异日志）
_repo.Insert(entity, ignoreNullValues: true, enableDiffLog: true);

// <inheritdoc cref="SugarRepository{T}.Update(T, bool, bool, object)"/>
// 更新（可选差异日志）
_repo.Update(entity, ignoreNullValues: true, enableDiffLog: true);

❗ 性能提示: SugarRepository<T> 构造函数中会检查 SystemTableAttribute，如果实体标记了该特性则跳过特殊初始化。对于不需要租户/分库逻辑的简单实体，建议添加 [SystemTable] 特性以加速构造。

场景三：审计字段自动填充

┌──────────────────────────────────────────────────────────┐
│                    DataExecuting AOP                      │
├──────────────────────────────────────────────────────────┤
│  InsertByObject:                                          │
│    ├─ long Id == 0 → IdGenerator.Id (雪花Id)              │
│    ├─ CreateTime == null → DateTime.Now                   │
│    ├─ IsDelete == null → IsDelete.N                       │
│    ├─ TenantId == null/0 → currentUser.TenantId           │
│    └─ Creator == null/0 → currentUser.UserId              │
│                                                           │
│  UpdateByObject:                                          │
│    ├─ ModifyTime == null → DateTime.Now                   │
│    └─ Modifier == null/0 → currentUser.UserId             │
└──────────────────────────────────────────────────────────┘

// 实体定义
public class Order : EntityBase  // 继承后自动获得审计能力
{
    [SugarColumn(ColumnDescription = "订单编号")]
    public string OrderNo { get; set; }

    [SugarColumn(ColumnDescription = "订单金额")]
    public decimal Amount { get; set; }
}

// 业务代码 —— 无需手动设置审计字段
var order = new Order
{
    OrderNo = "ORD-20240623-001",
    Amount = 1280.00m
    // CreateTime / Creator / IsDelete / TenantId 由 AOP 自动填充
};

_sqlSugarClient.Insert(order);  // AOP 自动注入审计值

order.Amount = 2560.00m;
_sqlSugarClient.Update(order);  // ModifyTime / Modifier 自动更新

❗ 性能提示: DataExecuting 事件每次数据库操作都会触发。对于批量插入/更新的高性能场景，建议使用集合重载（Insert(List<T>) / Update(List<T>)）以减少 AOP 回调次数，而非逐条调用。

场景四：全局查询过滤器

┌──────────────────────────────────────────┐
│           QueryFilter 自动注入             │
├──────────────────────────────────────────┤
│  IsDeleteFilter = true (默认)              │
│    → WHERE IsDelete = N                   │
│                                           │
│  IsUserIdFilter = true (默认关闭)          │
│    → WHERE Creator = currentUser.UserId   │
│                                           │
│  IsTenantIdFilter = true (默认关闭)        │
│    → WHERE TenantId = currentUser.TenantId│
│                                           │
│  ⚠️ 超级管理员 (IsSuperAdmin = true) 跳过   │
│     所有过滤器                             │
└──────────────────────────────────────────┘

// 配置每个连接的过滤器
var config = new DbConnectionConfig
{
    ConfigId = "1300000000001",
    DbType = SqlSugar.DbType.MySql,
    ConnectionString = "...",
    IsDeleteFilter = true,       // 开启软删除过滤
    IsUserIdFilter = false,      // 关闭用户隔离
    IsTenantIdFilter = true      // 开启租户隔离
};

// 业务代码 —— 无感知过滤
var users = await _sqlSugarClient.ToListAsync<User>();
// 实际 SQL 自动追加: WHERE IsDelete = 0 AND TenantId = @tenantId

// 超级管理员查全量数据
if (currentUser.IsSuperAdmin)
{
    // 所有过滤器被跳过，可查询所有 IsDelete=Y 的记录
}

⚠️ 超级管理员判断: 过滤器在 SugarUtil.ApplyQueryFilters 中通过 currentUser == null || currentUser.IsSuperAdmin 判断是否跳过。确保 ICurrentUser 实现正确返回 IsSuperAdmin，否则所有用户的过滤器都不会生效。

场景五：工作单元事务

┌──────────────────────────────────────────────┐
│  [UnitOfWork(IsolationLevel.ReadCommitted)]   │
│  ┌─────────────────────────────────────────┐ │
│  │  Controller Action                       │ │
│  │  ├─ repo1.Insert(order)                 │ │
│  │  ├─ repo2.Update(inventory)             │ │
│  │  └─ repo3.Insert(log)                   │ │
│  │       ↓                                 │ │
│  │  无异常 → CommitTran()                   │ │
│  │  有异常 → RollbackTran() → Dispose()    │ │
│  └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

方式一：特性标注（推荐）

// <inheritdoc cref="UnitOfWorkAttribute"/>
[ApiController]
[Route("api/[controller]")]
public class OrderController : ControllerBase
{
    private readonly SugarRepository<Order> _orderRepo;
    private readonly SugarRepository<Inventory> _inventoryRepo;

    public OrderController(
        SugarRepository<Order> orderRepo,
        SugarRepository<Inventory> inventoryRepo)
    {
        _orderRepo = orderRepo;
        _inventoryRepo = inventoryRepo;
    }

    /// <summary>
    /// 创建订单并扣减库存 —— 事务保证原子性
    /// </summary>
    [HttpPost]
    [UnitOfWork(IsolationLevel.ReadCommitted)]  // 标注即启用事务
    public async Task<IActionResult> CreateOrder(OrderDto dto)
    {
        var order = new Order { /* ... */ };
        await _orderRepo.InsertAsync(order);

        var inventory = await _inventoryRepo.GetFirstAsync(
            i => i.ProductId == dto.ProductId, i => i.Id);

        inventory.Stock -= dto.Quantity;
        await _inventoryRepo.UpdateAsync(inventory);

        return Ok();
        // 方法正常返回 → 自动 CommitTran
        // 任意异常   → 自动 RollbackTran + Dispose
    }
}

方式二：全局启用

// <inheritdoc cref="SqlSugarSetup.AddSqlSugarSetup(IServiceCollection, bool, ICacheService, ServiceLifetime, Action{SqlSugarScopeProvider})"/>
// isAllUnitOfWork = true 时，所有 Controller Action 自动包裹事务
builder.Services.AddSqlSugarSetup(isAllUnitOfWork: true);

⚠️ 注册顺序: 全局事务通过 services.AddMvcCore(options => options.Filters.Add(typeof(UnitOfWorkFilter))) 注入，UnitOfWorkFilter 的 Order = 100。如果你的项目有自定义 Filter 且依赖事务执行顺序，请注意调序。

❗ 性能提示: 全局事务模式下，即使是 GET 请求（只读操作）也会走事务流程（BeginTran → next() → CommitTran），增加不必要的数据库开销。建议仅在写操作 Controller 上使用 [UnitOfWork] 特性标注，而非全局启用。

场景六：差异日志记录

┌──────────────────────────────────────────┐
│           EnableDiffLog = true            │
├──────────────────────────────────────────┤
│  Insert / Update / Delete 触发            │
│       ↓                                  │
│  OnDiffLogEvent 回调                      │
│       ↓                                  │
│  IRestFulLog.DiffLog(dbType, diffData)   │
│       ↓                                  │
│  输出: BeforeData / AfterData / Sql       │
│        / DiffType / Elapsed              │
└──────────────────────────────────────────┘

// <inheritdoc cref="SqlSugarExtensions.UpdateWithDiffLog{T}(ISqlSugarClient, T, bool)"/>
// 更新并输出差异数据
_sqlSugarClient.UpdateWithDiffLog(entity);
// 输出:
// *****差异日志开始*****
// {
//   "AfterData":  [{"Columns": [{"ColumnName": "Amount", "Value": 2560}]}],
//   "BeforeData": [{"Columns": [{"ColumnName": "Amount", "Value": 1280}]}],
//   "BusinessData": null,
//   "DiffType": "update",
//   "Sql": "UPDATE `Order` SET `Amount`=@Amount WHERE `Id`=@Id",
//   "Elapsed": 12
// }
// *****差异日志结束*****

// <inheritdoc cref="SqlSugarExtensions.InsertWithDiffLog{T}(ISqlSugarClient, T)"/>
_sqlSugarClient.InsertWithDiffLog(entity);

// <inheritdoc cref="SqlSugarExtensions.UpdateWithDiffLogAsync{T}(ISqlSugarClient, T, bool)"/>
await _sqlSugarClient.UpdateWithDiffLogAsync(entity);

自定义差异日志实现

// <inheritdoc cref="SqlSugarSetup.AddRestFulLogSetup{TFilterType}"/>
public class MyRestFulLog : RestFulLog
{
    private readonly ILogger<MyRestFulLog> _logger;

    public MyRestFulLog(ILogger<MyRestFulLog> logger) => _logger = logger;

    public override void DiffLog(DbType dbType, DiffLogModel diffLogData)
    {
        // 写入结构化日志而非 Console
        _logger.LogInformation("差异日志 {DiffType}: {Sql}",
            diffLogData.DiffType,
            UtilMethods.GetSqlString(dbType, diffLogData.Sql, diffLogData.Parameters));
    }

    public override void SugarExecutingLog(string sql, SugarParameter[] pars, string fullSql)
    {
        _logger.LogDebug("SQL 执行: {FullSql}", fullSql);
    }

    public override void SugarErrorLog(DbType dbType, string sql, SugarParameter[] pars, string message)
    {
        _logger.LogError("SQL 异常 [{DbType}]: {Message}\n{Sql}", dbType, message,
            UtilMethods.GetSqlString(dbType, sql, pars));
    }
}

// 注册自定义日志
builder.Services.AddRestFulLogSetup<MyRestFulLog>();

❗ 性能提示: RestFulLog.DiffLogString 中通过双层嵌套循环比较 afterData 和 beforeData 的每一列，时间复杂度为 O(n*m)。在列数较多的表（>50 列）上启用差异日志可能对性能产生可感知的影响。

场景七：连接字符串 SM2 加密

// <inheritdoc cref="DbConnectionConfig.IsEncrypt"/>
var config = new DbConnectionConfig
{
    ConfigId = "1300000000001",
    DbType = SqlSugar.DbType.MySql,
    ConnectionString = "加密后的连接字符串（Base64）",
    IsEncrypt = true,                              // 启用 SM2 解密
    DbSecurity = "your-sm2-private-key"            // SM2 私钥
};

// 内部自动调用:
// string dbString = SMEncryption.SM2Decrypt(item.ConnectionString, item.DbSecurity);
// connection.ConnectionString = dbString;

⚠️ 安全提示: DbSecurity 密钥切勿硬编码在代码中。建议通过环境变量、密钥管理服务（如 Azure Key Vault）或加密的配置文件注入。

⚙️ 配置选项详解

DbConnectionConfig

⚠️ CommandTimeOut 单位是秒而非毫秒。默认 30 秒对于大多数 OLTP 操作足够，但对于复杂报表查询可能需要调大。

DataAuditing 审计字段映射

DbInitConfig

SqlSugarConst 常量

🏗️ 实体基类体系

EntityBaseId                     AutoKeyBase
├─ Id : long (雪花Id)            ├─ Id : int (自增)
└─ Check()                       └─ [SugarColumn(IsIdentity=true)]

      ↓                                ↓
EntityBase : EntityBaseId         AutoKeyEntityBase : AutoKeyBase
├─ CreateTime : DateTime?         ├─ CreateTime : DateTime?
├─ ModifyTime : DateTime?         ├─ ModifyTime : DateTime?
├─ Creator : long?                ├─ Creator : long?
├─ Modifier : long?               ├─ Modifier : long?
├─ IsDelete : IsDelete?           ├─ IsDelete : IsDelete?
├─ IDeletedEntity                 ├─ IDeletedEntity
└─ IAuditableEntity               └─ IAuditableEntity

      ↓
EntityTenant : EntityBase         EntityTenantId : EntityBaseId
├─ TenantId : long?               ├─ TenantId : long?
├─ CheckTenantId()                ├─ CheckTenantId()
└─ ITenantEntity                  └─ ITenantEntity

⚠️ 已知问题: EntityBaseData（数据权限实体基类，含 CreateOrgId）和 IOrgIdFilter 接口已完全注释掉，如需数据权限过滤需自行实现。

实体接口

📐 SQL 扩展方法

所有扩展方法均基于 SqlSugarClient（非 ISqlSugarClient），需在 using RuoVea.ExSugar; 后可用。

查询方法

写入方法

假删除（软删除）

// <inheritdoc cref="SqlSugarExtensions.FakeDelete{T}(ISqlSugarClient, T)"/>
// 实体必须继承 EntityBase
_sqlSugarClient.FakeDelete(entity);
// 效果: UPDATE xxx SET IsDelete='Y', ModifyTime=NOW(), Modifier=@userId WHERE Id=@id

// 或通过仓储调用
_repo.FakeDelete(entity);

// 异步版本
await _sqlSugarClient.FakeDeleteAsync(entity);
await _repo.FakeDeleteAsync(entity);

差异日志写入

排序构建器

// <inheritdoc cref="SqlSugarExtensions.OrderBuilder{T, Input}(ISugarQueryable{T}, Input, string, bool)"/>
var query = _sqlSugarClient.AsQueryable<Order>()
    .OrderBuilder(pageParam, defualtSortField: "Id", descSort: true);
// 自动从 pageParam.Sidx / pageParam.Sord 读取排序规则

📄 分页查询

ToPageAsync（返回 PageResult）

// <inheritdoc cref="PagedExtensions.ToPageAsync{T}(ISugarQueryable{T}, int, int, bool)"/>
// 基础分页
var result = await _sqlSugarClient.AsQueryable<Order>()
    .ToPageAsync(pageIndex: 1, pageSize: 20);
// result.Rows, result.TotalRows, result.PageIndex, result.PageSize

// <inheritdoc cref="PagedExtensions.ToPageAsync{T, Dto}(ISugarQueryable{T}, int, int)"/>
// 分页 + DTO 映射（自动 Mapster 转换）
var dtoResult = await _sqlSugarClient.AsQueryable<Order>()
    .ToPageAsync<Order, OrderDto>(pageIndex: 1, pageSize: 20);

// <inheritdoc cref="PagedExtensions.ToPageAsync{T}(ISugarQueryable{T}, PageParam)"/>
// 从 PageParam 读取分页参数
var result = await _sqlSugarClient.AsQueryable<Order>()
    .ToPageAsync(new PageParam { PageNo = 1, PageSize = 20 });

ToPagedList / ToPagedListAsync（返回 SqlSugarPagedList）

// <inheritdoc cref="SqlSugarPagedExtensions.ToPagedList{TEntity}(ISugarQueryable{TEntity}, int, int)"/>
var paged = _sqlSugarClient.AsQueryable<Order>().ToPagedList(1, 20);
// paged.Page, paged.PageSize, paged.Total, paged.TotalPages
// paged.Items, paged.HasPrevPage, paged.HasNextPage

// <inheritdoc cref="SqlSugarPagedExtensions.ToPagedListAsync{TEntity}(ISugarQueryable{TEntity}, int, int)"/>
var paged = await _sqlSugarClient.AsQueryable<Order>().ToPagedListAsync(1, 20);

SugarRepository 分页

// <inheritdoc cref="SugarRepository{T}.GetPageResultAsync"/>
var (list, total, totalPage) = await _repo.GetPageResultAsync(
    where: u => u.IsDelete == IsDelete.N,
    strWhere: "Amount > 100",           // 可选：原生 SQL 条件
    pageNo: 1,
    pageSize: 20,
    order: u => u.CreateTime,
    orderEnum: SordEnum.Desc
);

🧵 线程安全与生命周期

❗ 重要: ISqlSugarClient 以 Singleton 注册，与传统的 Scoped DbContext 模式不同。这是故意的设计选择 —— SqlSugar 的 SqlSugarScope 内部使用线程静态或 AsyncLocal 来隔离不同请求的数据库操作。不要将 ISqlSugarClient 注册改为 Scoped，这会导致 SugarRepository<T> 构造函数注入失败。

⚠️ 已知问题与注意事项

严重

一般

性能建议

🗺️ 版本迁移指南

从原生 SqlSugarCore 迁移

v8.0.x → v10.0.x

• API 无破坏性变化。v10.0.x 仅在 net10.0 TFM 上编译，所有公开 API 签名保持一致。
• Mapster 版本从 7.4.0 升级到 10.0.7，如需自定义 TypeAdapterConfig，请参考 Mapster 10.x 迁移指南。
• Microsoft.Extensions.DependencyModel 从 8.0.* 升级到 10.0.*，行为无变化。

📄 License

MIT License © RuoVea

🔗 相关资源: NuGet Gallery · 问题反馈 · Gitee 仓库