Fast.SqlSugar
参考源码版本 3.5.76;目标 net8.0、net9.0、net10.0;依赖 Fast.Runtime、SqlSugarCore、System.Security.Cryptography.Pkcs、UAParser 与 Yitter.IdGenerator。提供作用域仓储、实体审计、连接选择、分页与连接配置。
从旧版升级且使用平台标志时,见 Runtime H5 迁移说明。本包的版本对齐记录见依赖链变更。
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。
| 成员 | 原值 | 当前值 |
|---|---|---|
MySql | 0 | 1 |
SqlServer | 1 | 2 |
Sqlite | 2 | 3 |
Oracle | 3 | 4 |
PostgreSQL | 4 | 5 |
MongoDb | 32 | 6 |
其他旧成员(包括 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 / DbUser | 127.0.0.1 / 1433 / sa,源实现的 SQL Server 默认,不是部署建议 |
DbName、DbPwd、CustomConnectionStr、ConnectionId | 无默认值,使用外部配置 |
DbType | SqlServer;换数据库不能仍依赖 SQL Server 默认端口 |
MaxPoolSize | 100;主库和从库分别使用自身设置 |
CommandTimeOut | 60 秒 |
SugarSqlExecMaxSeconds | 30 秒,超时日志阈值 |
DiffLog / DisableAop | false / true |
SlaveConnectionList | 可选从库列表;各条目还有命中权重 |
SnowflakeSettingsOptions.WorkerId | 1;多实例必须分配不同值 |
本页不提供可直接连接真实数据库的配置。注册片段、数据库执行和建库/迁移是不同操作;文档验证不得启动数据库初始化。
连接池、从库与自定义连接字符串
自动生成 MySql、MySqlConnector、SqlServer 和 PostgreSQL 的主库/从库连接字符串时使用各自的 MaxPoolSize,null 时回退到 100。它不会重写自定义连接字符串,也不代表其他数据库驱动使用相同的连接池参数。
以下占位值必须由消费端替换;片段只构造选项,不连接数据库。PostConfigure() 的端口默认值固定为 1433,切换到 MySql 后仍需显式设置 3306。
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 共同组成动态查询合同,外部字段名仍需按允许的列筛选。
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 应自行声明属性并完成查询投影或赋值:
#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 配置;以下示例保留旧字段的类型、长度、可空和建表排序约定:
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 版本。前提是宿主已按本页配置注册仓储,并存在实体对应的业务表。本示例不建库、不建表,也不执行写入;文档维护不连接数据库运行它。
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。此结果不替代后续依赖漏洞审计。
