Fast.SqlSugar

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

版本 3.5.65；目标 net8.0、net9.0、net10.0；依赖 Fast.Runtime、SqlSugarCore、SQLite 原生支持、UAParser 与 Yitter.IdGenerator。提供作用域仓储、实体审计、连接选择、分页与数据库工具。

bash

dotnet add package Fast.SqlSugar

注册前置与公开入口

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 默认端口
`CommandTimeOut`	60 秒
`SugarSqlExecMaxSeconds`	30 秒，超时日志阈值
`DiffLog` / `DisableAop`	false / true
`SlaveConnectionList`	可选从库列表；各条目还有命中权重
`SnowflakeSettingsOptions.WorkerId`	1；多实例必须分配不同值

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

仓储 API

ISqlSugarRepository<TEntity> : ISqlSugarClient，约束 TEntity : class, new()。其公开查询入口 Entities 返回 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、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、SugarEntityFilter、连接与数据库类型扩展包含真实数据库操作或 AOP 配置；不能作为只读核验命令执行。AOP 内再次通过启用 AOP 的连接写日志可能递归，需按源码合同隔离日志操作。

查询仓储的实际调用

下面是 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 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 必须结合真实数据库配置审阅，不能从查询成功推断写入安全。

来源与验证

依据注册实现、仓储合同、实体处理器。本轮未编译新增片段，未连接数据库、生成迁移或执行任何数据/结构操作。

非分页数量上限

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

Fast.SqlSugar ​

注册前置与公开入口 ​

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

仓储 API ​

实体、分页与扩展 ​

查询仓储的实际调用 ​

来源与验证 ​

非分页数量上限 ​