跳到正文

Fast.SqlSugar ​

逐成员 API、参数与返回参考

参考源码版本 3.5.76;目标 net8.0、net9.0、net10.0;依赖 Fast.Runtime、SqlSugarCore、System.Security.Cryptography.Pkcs、UAParser 与 Yitter.IdGenerator。提供作用域仓储、实体审计、连接选择、分页与连接配置。

从旧版升级且使用平台标志时,见 Runtime H5 迁移说明。本包的版本对齐记录见依赖链变更。

bash
dotnet add package Fast.SqlSugar

中央依赖 SqlSugarCore 为 5.1.4.221。3.5.69 调整实体自动赋值的检查与调用时机,保留既有字段空值填充规则;3.5.68 的分页输出字段删除和 3.5.67 的部门实体接口拆分继续有效。

3.5.73 连接配置与公共 API 迁移 ​

当前源码仍使用 3.5.73,本次不再递增版本。以下调整包含破坏性变更;补丁版本号不代表旧程序集、继承关系或数值合同仍兼容,消费端需要修改用法并重新编译。

原合同当前合同与迁移
DbConnectionInfo类型已移除;主库使用 ConnectionSettingsOptions,从库使用 SlaveConnectionInfo,消费端自己的数据库记录模型须自行声明字段和映射
ConnectionSettingsOptions : DbConnectionInfo直接实现 IPostConfigure;连接字段直接声明,原基类引用、依赖虚成员的派生实现和 override 需调整
SlaveConnectionInfo : DbConnectionInfo独立类型,不再提供 PostConfigure() 或 CustomConnectionStr,也不再继承主库默认值;HitRate 不再是虚属性
配置类型的继承和映射SlaveConnectionList 等原虚成员不再是虚成员,配置字段移除了原有 SugarColumn 标注;不要把配置类型自动当作旧持久化模型使用
SqlSugarDatabaseUtil类型及其工具入口改为内部实现;连接配置使用公开的 SqlSugarContext.GetConnectionConfig(options),其他工具调用改用受支持的 SqlSugar API 或消费端实现
repository.Entities改为继承的 repository.Queryable<TEntity>();Count/Any/Single/First/ToList 等便捷查询内部也使用该入口

SugarDbType 数值与转换 ​

SugarDbType 只保留以下六项。持久化数值、请求中的数字、组合配置和生成的客户端枚举应按旧成员含义迁移,不能直接整体加一;默认值 0 已不再表示 MySql。

成员原值当前值
MySql01
SqlServer12
Sqlite23
Oracle34
PostgreSQL45
MongoDb326

其他旧成员(包括 Dm、MySqlConnector、Access、Custom 等)已移除。ToDbType() / ToSugarDbType() 只接受这六种类型,未定义数值和其他数据库类型抛出 ArgumentOutOfRangeException;SqlSugar.DbType.MySqlConnector.ToSugarDbType() 同样不受支持。

ConnectionSettingsOptions.DbType 仍是独立的 SqlSugar.DbType?,它的数值未随 Fast 的 SugarDbType 改动。两种枚举之间使用公开转换方法,不直接按数值强制转换,也不要按上表批量改写连接配置中的 DbType。

注册前置与公开入口 ​

API参数与行为
AddSqlSugar(services, configuration, hostEnvironment, string connectionSection = "ConnectionSettings")读取单个 ConnectionSettingsOptions,注册 Scoped ISqlSugarClient 与泛型仓储
AddSqlSugar(services, configuration, hostEnvironment, Action<ConnectionSettingsOptions>)使用调用方回调生成的连接选项
AddSnowflake(services, configuration, string section = "SnowflakeSettings")配置雪花 ID 的静态生成器,WorkerId 后配置默认 1
AddSnowflake(services, configuration, Action<SnowflakeSettingsOptions>)当前实现创建回调对象后仍读取静态 SqlSugarContext.SnowflakeSettings;不能宣称回调对象一定生效

ISqlSugarEntityHandler 的实现必须被扫描发现或显式注册,客户端工厂通过 GetRequiredService 获取它。处理器负责连接选择、审计、租户和 SQL 事件,不是可省略的空接口。实现构造函数不能再注入 ISqlSugarClient 形成循环依赖。

配置默认值与实际生效边界 ​

下表是 PostConfigure() 定义的值。当前 AddSqlSugar 同时保留直接绑定的静态选项,不会对这份静态对象自动调用 PostConfigure;因此不得假设通过 IOptions 后配置就补齐了客户端工厂读取的对象。回调方式可显式调用 options.PostConfigure() 后再设置业务字段;配置节点方式须提供客户端所需完整字段。

字段PostConfigure 默认值 / 单位
ServiceIp / Port / DbUser127.0.0.1 / 1433 / sa,源实现的 SQL Server 默认,不是部署建议
DbName、DbPwd、CustomConnectionStr、ConnectionId无默认值,使用外部配置
DbTypeSqlServer;换数据库不能仍依赖 SQL Server 默认端口
MaxPoolSize100;主库和从库分别使用自身设置
CommandTimeOut60 秒
SugarSqlExecMaxSeconds30 秒,超时日志阈值
DiffLog / DisableAopfalse / true
SlaveConnectionList可选从库列表;各条目还有命中权重
SnowflakeSettingsOptions.WorkerId1;多实例必须分配不同值

本页不提供可直接连接真实数据库的配置。注册片段、数据库执行和建库/迁移是不同操作;文档验证不得启动数据库初始化。

连接池、从库与自定义连接字符串 ​

自动生成 MySql、MySqlConnector、SqlServer 和 PostgreSQL 的主库/从库连接字符串时使用各自的 MaxPoolSize,null 时回退到 100。它不会重写自定义连接字符串,也不代表其他数据库驱动使用相同的连接池参数。

以下占位值必须由消费端替换;片段只构造选项,不连接数据库。PostConfigure() 的端口默认值固定为 1433,切换到 MySql 后仍需显式设置 3306。

csharp
using Fast.SqlSugar;
using DbType = SqlSugar.DbType;

var options = new ConnectionSettingsOptions();
options.PostConfigure();
options.ConnectionId = "main";
options.DbType = DbType.MySql;
options.ServiceIp = "DB_HOST";
options.Port = 3306;
options.DbName = "DB_NAME";
options.DbUser = "DB_USER";
options.DbPwd = "DB_PASSWORD";
options.MaxPoolSize = 200;
options.SlaveConnectionList =
[
    new SlaveConnectionInfo
    {
        ServiceIp = "REPLICA_HOST",
        Port = 3306,
        DbName = "DB_NAME",
        DbUser = "DB_USER",
        DbPwd = "DB_PASSWORD",
        MaxPoolSize = 50,
        HitRate = 1
    }
];

从库字段独立配置,不继承主库的地址、凭据或默认值;从库未指定端口时,连接字符串生成器才按数据库类型使用相应端口。HitRate 为命中权重,0 表示不命中。SlaveConnectionInfo.CommandTimeOut 目前没有被应用为独立的从库命令超时。

当 CustomConnectionStr 非空白时,主库直接使用它,并忽略整个 SlaveConnectionList。地址、端口、数据库、凭据和 MaxPoolSize 不再参与主库连接字符串拼接;连接池参数应写入自定义字符串。

ISqlSugarClient 工厂对未设置的 SugarSqlExecMaxSeconds、DiffLog、DisableAop 分别回退到 30、false、true。这些局部兜底不会补齐整份静态配置;DbType、CommandTimeOut 及泛型仓储构造路径仍要求完整选项。

仓储 API ​

ISqlSugarRepository<TEntity> : ISqlSugarClient,约束 TEntity : class, new()。组合查询使用继承的 Queryable<TEntity>() 返回 ISugarQueryable<TEntity>,另有 SupportsLogicDelete、SupportsRowVersion、IsSplitTable 能力标志。

家族主要返回与语义
Count/CountAsync、Any/AnyAsync数量或存在性;查询使用表达式
SingleOrDefault/SingleOrDefaultAsync主键或表达式查询单项,注意唯一结果语义
FirstOrDefault/FirstOrDefaultAsync表达式查询第一项;需稳定顺序时显式排序
ToList/ToListAsync全量、条件、排序等重载;可能返回大集合
Insert/InsertAsync单实体、数组、集合写入,返回受影响行数
InsertReturnIdentity/ExecuteReturnBigIdentity/InsertReturnEntity分别返回 int 标识、long 标识、实体;具有异步版本
Update/UpdateAsync单实体可选 isNoUpdateNull = false,另有集合重载
UpdateNoPrimaryKey 及异步版本显式指定匹配列,调用方负责条件唯一性
Delete、逻辑删除等分部接口属于真实数据写入;能力由实体接口和实现决定

仓储继承的 SqlSugar API 仍遵循 SqlSugar 合同。框架不会自动把多次调用变成一个事务,也不保证通用取消令牌重载。

实体、分页与扩展 ​

实体家族为 BaseEntity/IBaseEntity、BaseTEntity/IBaseTEntity、BaseRecordEntity/IBaseRecordEntity、IDatabaseEntity、IDepartmentEntity、IDeletedEntity、IUpdateVersion。ISqlSugarEntityHandler 提供 GetConnectionSettings<TEntity>、执行/异常回调、管理员判断及 AssignTenantId/Department/User 等审计值。

PagedInput 默认 PageIndex=1、PageSize=20、EnablePaged=true;SearchTimeList、SearchList、SortList 默认空。PagedResult<T> 返回页码、容量、总页数、总行数、Rows、前后页标志及类型信息。SqlSugarContext.MaxNotPageSize 默认 10000。PagedSearchInput/PagedSortInput、搜索特性与 SqlSugarPageExtension 共同组成动态查询合同,外部字段名仍需按允许的列筛选。

csharp
using Fast.SqlSugar;

public static class PagingDefaults
{
    public static PagedInput FirstPage() => new() { PageIndex = 1, PageSize = 20 };
}

SqlSugarDatabaseUtil 已改为内部类型,不再是消费端可调用的工具入口。连接配置使用公开的 SqlSugarContext.GetConnectionConfig(options);SugarEntityFilter 仍提供 AOP 和过滤器入口,其回调可能执行应用代码。AOP 内再次通过启用 AOP 的连接写日志可能递归,需按源码合同隔离日志操作。

3.5.69 实体自动赋值 ​

在 InsertByObject 和 UpdateByObject 的字段回调中,先匹配当前属性名称,再读取属性值并检查赋值条件;通过检查后才计算并设置新值。AssignDepartmentId/Name、AssignUserId/Name 和 AssignTenantId 不再因无关属性而提前调用,新增时已有非空值的对应处理器也不会被调用。属性读取失败时跳过该字段的自动赋值。

新增时,RowVersion 的 null/0 值仍初始化为 1;部门、租户和创建者 ID 仍仅在 null/0 时填充,部门名称和创建者名称仍仅在 null/空字符串时填充。需要处理器提供值的字段仍以存在处理器为前提。

新增时,CreatedTime 仍仅在原值为 null 时填入 DateTime.Now,调用方已传入的创建时间保持不变。更新时,能够读取的 UpdatedTime 仍覆盖为当前时间;有处理器时,对应的更新者 ID/名称仍覆盖为处理器提供的值,且仅在当前字段匹配时调用处理器。公开 API 声明和依赖版本未变。

3.5.68 分页输出字段迁移 ​

PagedOutput 不再提供 DepartmentName,其余审计字段和 RowVersion 保持原有合同。不需要部门信息的分页 DTO 可以继续直接继承;仍需返回部门名称的 DTO 应自行声明属性并完成查询投影或赋值:

csharp
#nullable enable

using Fast.SqlSugar;

/// <summary>
/// Paging output with a department name
/// </summary>
public sealed class DepartmentPagedOutput : PagedOutput
{
    /// <summary>
    /// Department name
    /// </summary>
    public string? DepartmentName { get; set; }
}

原先对该基类属性的 override、base.DepartmentName 访问及仅约束为 PagedOutput 的泛型成员访问需要调整,并重新编译依赖程序集。基类默认序列化输出不再包含部门名称;保留响应字段时还应核对返回类型、JSON 命名策略与客户端模型。分页 DTO 无需因此实现 IDepartmentEntity;该实体接口与部门赋值钩子保持原有合同。

3.5.67 部门字段迁移 ​

BaseEntity/IBaseEntity 与 BaseRecordEntity/IBaseRecordEntity 不再声明 DepartmentId、DepartmentName,继承 BaseEntity 的 BaseTEntity 也不再自带这两个字段。这是公共 API 的破坏性变更;不需要部门信息的实体无需补充字段。

需要部门归属或部门审计快照的实体应显式实现 IDepartmentEntity,声明两个属性及其 SqlSugar 映射。接口本身不提供属性实现或 SugarColumn 配置;以下示例保留旧字段的类型、长度、可空和建表排序约定:

csharp
using Fast.SqlSugar;
using SqlSugar;

[SugarTable("DepartmentDocument")]
public sealed class DepartmentDocument : BaseTEntity, IDepartmentEntity
{
    [SugarColumn(IsPrimaryKey = true)]
    public long Id { get; set; }

    [SugarColumn(ColumnDescription = "部门Id", CreateTableFieldSort = 989)]
    public long? DepartmentId { get; set; }

    [SugarColumn(ColumnDescription = "部门名称", Length = 20, IsNullable = true, CreateTableFieldSort = 990)]
    public string DepartmentName { get; set; } = "";
}

原来通过 IBaseEntity 或 IBaseRecordEntity 访问部门字段的泛型约束、表达式和映射,需要改为 IDepartmentEntity 或对应具体实体。仍需访问审计字段的调用方应同时保留原有审计合同。BaseRecordEntity 的设备、系统、浏览器、省、市、IP 字段建表排序调整为 971–976;创建人和创建时间保持原有合同。

新增对象时,SugarEntityFilter 仍按属性名匹配部门字段,并未检查实体是否实现 IDepartmentEntity。存在处理器时,仅将 null/0 的部门 ID、null/空字符串的部门名称填入处理器提供的值;已有非空值保持不变。更新对象时不会自动重新分配部门。仅实现接口不会自动启用部门数据权限过滤,现有全局过滤仍负责租户和软删除。

迁移前应核对部门表示数据归属还是创建时快照,以及业务层的数据权限条件。源码移除属性不等于删除已有数据库列;既有字段、历史数据、索引和约束应单独审核,不运行建库、迁移或删列来完成文档核验。

查询仓储的实际调用 ​

下面是 Fast.SqlSugar 消费端服务,目标为本页支持的 .NET 版本。前提是宿主已按本页配置注册仓储,并存在实体对应的业务表。本示例不建库、不建表,也不执行写入;文档维护不连接数据库运行它。

csharp
using Fast.SqlSugar;
using SqlSugar;

[SugarTable("CatalogItem")]
public sealed class CatalogItem
{
    [SugarColumn(IsPrimaryKey = true)]
    public long Id { get; set; }
    public string Name { get; set; } = "";
}

public sealed class CatalogReader(ISqlSugarRepository<CatalogItem> repository)
{
    public ISugarQueryable<CatalogItem> QueryByName(string name) =>
        repository.Queryable<CatalogItem>().Where(item => item.Name == name);

    public Task<int> CountAsync(string name) =>
        repository.CountAsync(item => item.Name == name);

    public Task<bool> ExistsAsync(long id) =>
        repository.AnyAsync(item => item.Id == id);

    public Task<CatalogItem> FindAsync(long id) =>
        repository.SingleOrDefaultAsync((object)id);
}

表达式由查询提供器翻译,示例没有拼接 SQL。SingleOrDefaultAsync 未命中时需要按空结果处理,尽管当前声明没有 nullable 标注。CountAsync 返回匹配数量;这三个方法不承诺自动开启事务。连接失败、SQL 翻译或数据库异常不会自动转为“未找到”。写入、逻辑删除、行版本、事务和继承自 SqlSugar 的 API 必须结合真实数据库配置审阅,不能从查询成功推断写入安全。

来源与验证 ​

依据 注册实现、仓储合同、实体处理器。2026-10-17 已按 3.5.69 当前工作区的实体赋值修改核对文档,并在恢复 CreatedTime 仅 null 时填充后,完成 net8.0、net9.0、net10.0 的 Release 构建与本地打包。已核验包身份、程序集版本、DLL/XML 内容及包内 DLL 与最新构建产物一致;依赖版本未变,当时双语 API 参考的 278 项公开及受保护声明保持一致;该历史记录不覆盖本页当前 3.5.73 的公共 API 迁移。处理器调用时机和空值规则按源码核对,未执行运行时回归或真实实体保存流程。该历史构建中 SqlSugar 传递依赖 System.Security.Cryptography.Pkcs 8.0.1 存在 NU1902/NU1903 告警;3.5.72 的依赖调整见下文,尚未重新还原核验。未启动业务宿主、连接数据库或执行数据/结构操作。

非分页数量上限 ​

非分页查询最多读取 MaxNotPageSize + 1 条用于判定超限。恰好 N 条允许返回,N+1 条才拒绝;同步和异步入口一致。上限必须在 1 至 int.MaxValue-1 之间。此规则不移除分页保护,也不在测试中执行数据库写操作。

2026-11-02 依赖链变更 ​

2026-11-02 依赖链同步:本包从 3.5.75 递增至 3.5.76,依赖更新为 Fast.Runtime 3.5.37。本模块自身实现与公开声明未变。Runtime 新增移动端 H5,并将 Android 及后续位依次后移;数字协议和掩码须迁移,消费端须重新编译并同步前端枚举,见 Runtime H5 迁移说明。

2026-10-24 版本与依赖 ​

2026-10-24 将本包从 3.5.71 递增至 3.5.72,依赖更新至 Fast.Runtime 3.5.34。本模块自身实现和公开声明未改。

显式引用 System.Security.Cryptography.Pkcs,net8.0、net9.0、net10.0 的中央版本分别为 8.0.2、9.0.21、10.0.13。移除 SQLitePCLRaw.bundle_e_sqlite3 的显式引用及中央 3.0.5 覆盖;SQLite 依赖交由保持为 5.1.4.221 的 SqlSugarCore 传递解析。本轮未还原依赖,不能据此认定实际 SQLite 版本或历史漏洞告警已经消除。

使用 AppEnvironmentEnum 的消费端需按 Runtime 鸿蒙迁移说明迁移数值并重新编译。本轮只核对源码与 MSBuild 有效包元数据,按要求不运行测试,也未执行还原、构建、打包或消费端运行验证。

2026-10-30 依赖补丁更新 ​

Fast.SqlSugar 从 3.5.72 递增至 3.5.73。System.Security.Cryptography.Pkcs 按 net8.0 / net9.0 / net10.0 分别使用 8.0.2 / 9.0.22 / 10.0.14。net8.0 的 8.0.2 保持不变,只升级 net9.0 和 net10.0 的补丁依赖。Fast.Runtime 3.5.34 和 SqlSugarCore 5.1.4.221 保持不变。

本次依赖升级未调整模块实现或公开 API。已重新还原并完成三个目标的 Release 构建和本地打包,核验包身份、依赖分组及 DLL/XML 与构建产物一致,最终构建无警告或错误。本次未执行宿主、HTTP/序列化/ORM 运行时回归、数据库或 Redis 操作,也未重新编译本页的消费端示例。

本次还原的实际 Pkcs 版本为 8.0.2 / 9.0.22 / 10.0.14,与配置和包依赖分组一致,未再出现 NU1603/NU1902/NU1903;SQLitePCLRaw.bundle_e_sqlite3 均传递解析为 2.1.12。此结果不替代后续依赖漏洞审计。