跳到正文

简体中文 | English · 返回 README

模块手册 ​

Fast.NET 由 17 个可独立发布的 NuGet 包组成。除 Fast.IaaS 外,主要模块面向 .NET 8、.NET 9 和 .NET 10;Fast.IaaS 面向 .NET Standard 2.1。

点击下表中的包名查看安装、配置和示例,也可直接查阅公开 API 参考。已有项目请先查看升级与迁移。

各模块标注用法或 API 的参考版本。安装命令使用当前 NuGet 源提供的包,示例验证版本会另行标明。

包用途主要入口默认配置节点 / 外部依赖
Fast.RuntimeASP.NET Core 共享上下文、配置与 MVC 扩展AddConfigurableOptions<T>()、AddMvcFilter()通常由其他 Fast.NET 包传递引用
Fast.IaaS编码、校验、脱敏、重试、树结构与通用扩展MaskingUtil、RetryUtil 等无 Web 宿主依赖
Fast.NET.Core应用初始化、配置扫描、CORS、压缩、请求缓冲builder.Initialize()、AddCorsAccessor()、AddGzipCompression()CorsAccessorSettings
Fast.CacheCSRedisCore 缓存封装services.AddCache()RedisSettings;需要 Redis
Fast.Consul服务注册、健康检查和 KVservices.AddFastConsul()ConsulSettings;需要 Consul
Fast.DependencyInjection基于标记接口的约定式依赖注入services.AddDependencyInjection()使用 ITransientDependency、IScopedDependency、ISingletonDependency
Fast.DynamicApplication将应用服务发现为动态 APIservices.AddDynamicApplication()必须先调用 AddControllers()
Fast.EventBus进程内有界通道、发布订阅和后台处理services.AddEventBus()默认容量 3000;不提供分布式持久化
Fast.JwtBearerJWT Bearer 认证、授权和令牌工具services.AddJwtBearer()JWTSettings
Fast.Logging控制台与文件日志扩展services.AddLoggingService()Logging:Fast;文件目录必须可写
Fast.MapsterMapster 注册与对象映射services.AddMapster()Mapster 10
Fast.OpenApiOpenAPI DTO 与 JavaScript/TypeScript 客户端生成services.AddOpenApi()OpenApiSettings
Fast.Serialization.System.Text.JsonSystem.Text.Json 统一选项、转换器和脱敏services.AddSerialization()与 Newtonsoft.Json 模块通常二选一
Fast.Serialization.Newtonsoft.JsonNewtonsoft.Json 统一选项、转换器和脱敏services.AddSerialization()、MVC 扩展与 System.Text.Json 模块通常二选一
Fast.SqlSugarSqlSugar、多数据库配置、仓储和分页services.AddSqlSugar()、AddSnowflake()ConnectionSettings、SnowflakeSettings;需要数据库
Fast.SwaggerSwagger 文档、分组、安全定义和 UIAddSwaggerDocuments()、UseSwaggerDocuments()SwaggerSettings
Fast.UnifyResult统一响应、模型验证和友好异常services.AddUnifyResult()面向 MVC/控制器应用

Fast.OpenApi 生成的 TypeScript 客户端使用独立的 import type 和显式 Promise<T> 返回类型。返回非泛型 Task 或 ValueTask 的接口映射为 Promise<void>。Download、Export 接口保留文件响应:Web 端使用 AxiosResponse<Blob>,移动端使用 AxiosResponse<Blob | ArrayBuffer | string>,兼容浏览器 Blob、二进制缓冲区和原生临时文件路径。autoDownloadFile 参数默认值为 true;传入 false 时仅返回文件响应,不请求自动保存。其他缺少明确 Schema 的值仍映射为 unknown。生成结果兼容 verbatimModuleSyntax 与当前 Fast ESLint Config 规则。生成的 Web 端与移动端 multipart 上传方法还会暴露可选的 Axios onUploadProgress 回调。

Fast.IaaS 3.5.27 修复 ToDescription() 的整数时间边界:一分钟输出 01分00秒,一小时输出 01时00分00秒,一天输出 01天00时00分00秒。

Fast.Runtime 3.5.30 在请求生命周期外能够安全处理不可用的 HttpContext。LocalIpv4()、LocalIpv6() 返回服务器连接端地址,RemoteIpv4()、RemoteIpv6() 返回经过可信 UseForwardedHeaders 中间件处理后的 Connection.RemoteIpAddress;语义不准确的 LanIpv4()、LanIpv6() 已删除。Fast.NET.Core 3.5.38 在请求上下文不存在时返回 HttpRequestMethodEnum.Unknown,Fast.SqlSugar 3.5.65 在请求审计信息不可用时保留空字段。

推荐注册顺序 ​

csharp
builder.Initialize();

builder.Services.AddSerialization();
builder.Services.AddControllers();

builder.Services.AddDependencyInjection();
builder.Services.AddEventBus();
builder.Services.AddUnifyResult();
builder.Services.AddDynamicApplication();
builder.Services.AddSwaggerDocuments(builder.Configuration);

顺序约束只有在模块之间存在实际依赖时才重要。最明确的一项是:AddDynamicApplication() 必须位于 MVC 控制器注册之后。

控制台输出 ​

从 Fast.Runtime 3.5.29 起,可通过 MAppContext.ConsoleWrite 分段设置控制台颜色并输出文本:

csharp
MAppContext.ConsoleWrite(e =>
{
    e.ForegroundColor = ConsoleColor.Blue;
    e.WriteLine();
    e.WriteLine("Fast.NET");
});

回调接收 Fast.Runtime.ConsoleWriter,支持 ForegroundColor、BackgroundColor、Write、WriteLine 和 ResetColor()。写入器自动记录进入回调时的前景色和背景色,并在 finally 中恢复;ResetColor() 可在回调中提前恢复这组颜色。同一输出流上的回调串行执行,也支持嵌套调用;回调必须同步完成,回调或写入异常继续向调用方传播。Console.IsOutputRedirected 为 true 时忽略颜色设置,仅输出文本,不生成 ANSI 颜色码。

Fast.NET.Core 的启动横幅及 Runtime、OpenApi、SqlSugar 的直接诊断输出均使用此入口,适配 Windows CMD、PowerShell、Windows Terminal 和 Linux 终端。Fast.IaaS 3.5.27 继续面向 netstandard2.1,使用 src/IaaS/Internals/ConsoleWriter.cs 中的内部写入器,保持独立包兼容性,不引入 Runtime 依赖。

历史文档基线 Fast.NET.Core 3.5.38 的 builder.Initialize() 在 ASCII Logo 前输出应用及宿主信息。应用名称和程序集版本取自入口程序集,框架程序集版本取自 Core 程序集;当前实现没有同时输出信息版本。无法获取的名称或版本使用 Unknown。运行环境取自 builder.Environment,启动时间为输出横幅时的本地时间,格式为 yyyy-MM-dd HH:mm:ss。

输出内容颜色
信息字段标签DarkGray
应用名称、主机名称、操作系统、系统平台与架构、进程架构Gray
.NET 运行时描述、Fast.NET 框架版本Cyan
应用版本Cyan
ASCII LogoGreen
运行环境名称Production 为 Green,Development 为 Yellow,其他环境为 Magenta
程序启动时间White
Gitee 地址Red
使用提示Yellow
学习寄语Cyan
框架说明及 PR 邀请Magenta

横幅同时调整缩进和空行,并增加合法使用提示及学习寄语。输出重定向时保留相同文本,不生成颜色码;输出结束后由写入器恢复原始颜色。

Fast.Logging 继续通过 ConsoleFormatter 接收的 TextWriter 写入,由 ConsoleLoggerProvider 负责终端适配、必要的 ANSI 解析和日志队列输出。格式化器不直接修改 Console.ForegroundColor;LoggerColorBehavior.Default 在输出重定向时停止生成颜色码,ANSI 支持由 Provider 处理,不仅根据重定向状态判断。

依赖注入注册约定 ​

AddDependencyInjection() 会扫描实现 ITransientDependency、IScopedDependency 或 ISingletonDependency 的非抽象类。有业务接口时,服务按业务接口注册;仅实现生命周期标记接口时,服务按具体类型注册,可直接注入该实现类。

基础设施模块注意事项 ​

  • Fast.Cache、Fast.Consul 和 Fast.SqlSugar 需要真实外部服务。验证时应使用隔离环境,不要在仓库检查流程中直接修改生产数据。
  • Fast.EventBus 是进程内事件总线,应用重启后不会恢复尚未处理的事件。需要跨进程、持久化或至少一次投递语义时,应选择专用消息中间件。
  • 两个序列化包都使用 Fast.Serialization 命名空间和相近扩展名,同一应用应明确选择并配置其中一个。
  • Fast.Logging 的文件日志依赖运行目录权限;容器中应将目录映射到可写卷或改用标准日志输出。

配置来源 ​

选项类型实现了仓库约定的后配置流程。最终支持字段以各模块的 *SettingsOptions 类型和 XML API 文档为准。不要在文档、示例或 Issue 中提交真实令牌、连接字符串或密码。

升级与迁移 ​

按受影响的用法查阅迁移步骤:

下面的版本表保留各批次当时的版本和数值。发布记录见 Fast.NET 的 CHANGELOG。

2026-10-17 版本同步 ​

本批次更新 Runtime、EventBus、Logging、UnifyResult,以及 Runtime 依赖链上的其他模块,共 14 个包,均按 3.5.x 补丁递增。下表记录该历史批次的源码目标版本,不代表已上传 NuGet。Fast.IaaS 与两个序列化包没有本次源码或依赖变化,版本保持不变。

PackageId原版本本次版本
Fast.Cache3.5.343.5.35
Fast.Consul3.5.103.5.11
Fast.NET.Core3.5.403.5.41
Fast.DependencyInjection3.5.303.5.31
Fast.DynamicApplication3.5.363.5.37
Fast.EventBus3.5.293.5.30
Fast.JwtBearer3.5.443.5.45
Fast.Logging3.5.333.5.34
Fast.Mapster3.5.283.5.29
Fast.OpenApi3.5.403.5.41
Fast.Runtime3.5.313.5.32
Fast.SqlSugar3.5.693.5.70
Fast.Swagger3.5.353.5.36
Fast.UnifyResult3.5.353.5.36

2026-10-17 请求内缓存优先 ​

本轮将 Runtime 及其依赖链上的 14 个包各递增一个补丁版本。Fast.Runtime 3.5.33 在请求内缓存命中时直接返回;未命中才检查取消并进入共享缓存或远程查询。IaaS 与两个独立序列化包版本保持不变。下表为该历史批次的源码目标版本,按要求未执行 Fast.NET 构建、打包或测试;上一批次的验证记录不适用于这些新版本。

PackageId原版本本轮版本
Fast.Cache3.5.353.5.36
Fast.Consul3.5.113.5.12
Fast.NET.Core3.5.413.5.42
Fast.DependencyInjection3.5.313.5.32
Fast.DynamicApplication3.5.373.5.38
Fast.EventBus3.5.303.5.31
Fast.JwtBearer3.5.453.5.46
Fast.Logging3.5.343.5.35
Fast.Mapster3.5.293.5.30
Fast.OpenApi3.5.413.5.42
Fast.Runtime3.5.323.5.33
Fast.SqlSugar3.5.703.5.71
Fast.Swagger3.5.363.5.37
Fast.UnifyResult3.5.363.5.37

2026-10-24 鸿蒙枚举与依赖同步 ​

本轮将 Runtime 及其依赖链上的 14 个包各递增一个 3.5.x 补丁版本;IaaS 与两个独立序列化包不变。下表为本批次的 NuGet 包版本。Fast.Runtime 新增 HarmonyOS 并调整枚举数值,这是破坏性变更,按要求继续使用 3.5.x。数值迁移和消费端重新编译要求见 Runtime 手册。

PackageId原版本本轮版本
Fast.Cache3.5.363.5.37
Fast.Consul3.5.123.5.13
Fast.NET.Core3.5.423.5.43
Fast.DependencyInjection3.5.323.5.33
Fast.DynamicApplication3.5.383.5.39
Fast.EventBus3.5.313.5.32
Fast.JwtBearer3.5.463.5.47
Fast.Logging3.5.353.5.36
Fast.Mapster3.5.303.5.31
Fast.OpenApi3.5.423.5.43
Fast.Runtime3.5.333.5.34
Fast.SqlSugar3.5.713.5.72
Fast.Swagger3.5.373.5.38
Fast.UnifyResult3.5.373.5.38

Fast.SqlSugar 显式引用分目标版本的 System.Security.Cryptography.Pkcs,并移除 SQLitePCLRaw.bundle_e_sqlite3 的显式引用和中央覆盖;Fast.Swagger 将 Swashbuckle.AspNetCore 升至 10.3.1。详情分别见 SqlSugar和 Swagger手册。

本轮完成源码、依赖关系与 MSBuild 有效包元数据核对;按要求不运行测试,也未执行还原、构建、打包或消费端验证。历史构建和断言记录不代表这些新版本已经验证。入门示例仍使用原有固定依赖,其编译记录不覆盖本批次版本。

2026-10-30 Core 静态文件映射 ​

Fast.NET.Core 从 3.5.43 递增至 3.5.44,新增可从 StaticFileSettings 或自定义配置节读取 MIME 类型映射的 UseStaticFiles 重载。映射可补充或覆盖默认扩展名,其余默认映射保留;依赖仍为 Fast.Runtime 3.5.34。配置示例与边界见 Core 手册。

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

本批次只更新下表中的三个 NuGet 包,模块实现和公开 API 保持不变。

PackageId原版本新版本指南
Fast.JwtBearer3.5.473.5.48Fast.JwtBearer
Fast.Serialization.Newtonsoft.Json3.5.273.5.28Fast.Serialization.Newtonsoft.Json
Fast.SqlSugar3.5.723.5.73Fast.SqlSugar

两个 ASP.NET Core 包按 net8.0 / net9.0 / net10.0 使用 8.0.33 / 9.0.22 / 10.0.14;Pkcs 使用 8.0.2 / 9.0.22 / 10.0.14。三个模块所有目标均已还原、Release 构建、本地打包并核验依赖和 DLL/XML,最终无警告或错误。未执行宿主或运行时回归。入门示例保留原有固定依赖,其编译记录不覆盖本批次;Core 保留单独更新的 3.5.44,Runtime 保持 3.5.34。

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

3.5.73 批次未再次升版;该批次的连接配置与公共 API 调整继续包含在本次 3.5.74 中。源码现已移除 DbConnectionInfo、仓储 Entities 和数据库工具类的公共访问,调整主从连接配置,并缩减、重编号 SugarDbType;这些变更需要消费端迁移并重新编译。主库和从库的 MySql/MySqlConnector、SqlServer、PostgreSQL 连接字符串均支持 MaxPoolSize;自定义主库连接字符串会忽略从库列表。详见 连接配置及 API 迁移。

2026-10-30 Runtime 标志位与依赖链对齐 ​

Runtime 升至 3.5.35,其余 13 个直接或间接引用包各递增一次补丁版本。新产物引用 Runtime 3.5.35;DynamicApplication 同步引用 UnifyResult 3.5.39,Swagger 同步引用 DynamicApplication 3.5.40。IaaS 与两个独立序列化包不在该引用链内,保持原版本;外部依赖版本不变。

PackageId原版本新版本
Fast.Cache3.5.373.5.38
Fast.Consul3.5.133.5.14
Fast.NET.Core3.5.443.5.45
Fast.DependencyInjection3.5.333.5.34
Fast.DynamicApplication3.5.393.5.40
Fast.EventBus3.5.323.5.33
Fast.JwtBearer3.5.483.5.49
Fast.Logging3.5.363.5.37
Fast.Mapster3.5.313.5.32
Fast.OpenApi3.5.433.5.44
Fast.Runtime3.5.343.5.35
Fast.SqlSugar3.5.733.5.74
Fast.Swagger3.5.383.5.39
Fast.UnifyResult3.5.383.5.39

验证:全解决方案 Release 构建和本地打包通过,零警告、零错误。14 个受影响包的 84 个 DLL/XML 文件与构建产物哈希一致,42 个程序集版本及 45 条内部依赖记录与源码版本一致;全部 28 个中英文模块版本入口与核对记录一致。Fast.Docs 的 pnpm run check 通过,含类型检查、lint、34 项测试通过/1 项因缺少 Nginx 跳过、API 覆盖、站点构建、434 个 HTML 页面的链接/资源/锚点及格式检查。未运行应用宿主、服务集成或数据库操作,未发布 NuGet 包。

2026-10-31 Runtime 组合成员移除与依赖链对齐 ​

Runtime 升至 3.5.36,其余 13 个引用包各递增一个补丁版本。DynamicApplication 引用 UnifyResult 3.5.40,Swagger 引用 DynamicApplication 3.5.41;全部引用链跟随 Runtime 3.5.36。IaaS、两个独立序列化包及外部依赖版本保持不变。组合成员删除属于破坏性 API 变更,源码及名称协议须迁移;来自 3.5.35 的数字掩码无需重新编号。

PackageId原版本新版本
Fast.Cache3.5.383.5.39
Fast.Consul3.5.143.5.15
Fast.NET.Core3.5.453.5.46
Fast.DependencyInjection3.5.343.5.35
Fast.DynamicApplication3.5.403.5.41
Fast.EventBus3.5.333.5.34
Fast.JwtBearer3.5.493.5.50
Fast.Logging3.5.373.5.38
Fast.Mapster3.5.323.5.33
Fast.OpenApi3.5.443.5.45
Fast.Runtime3.5.353.5.36
Fast.SqlSugar3.5.743.5.75
Fast.Swagger3.5.393.5.40
Fast.UnifyResult3.5.393.5.40

验证:全解决方案最终还原、Release 构建和本地打包通过,零警告、零错误。14 个受影响包的 84 个 DLL/XML 文件、42 个程序集版本和 45 条内部依赖记录均已核对。Runtime 的三个运行时各通过 182 项断言,中英文替代掩码示例三目标编译通过;当前公开声明经审阅从 265 项减为 261 项。文档完整检查通过:类型检查、lint、34 项测试通过/1 项因缺少 Nginx 跳过、API 覆盖、站点构建、434 个 HTML 页面的链接/资源/锚点及格式检查。未运行应用宿主、真实服务或数据库迁移,未发布包。

2026-11-02 移动端 H5 与依赖链对齐 ​

Runtime 升至 3.5.37,其余 13 个引用包各递增一个补丁版本。DynamicApplication 引用 UnifyResult 3.5.41,Swagger 引用 DynamicApplication 3.5.42;内部引用链跟随 Runtime 3.5.37。IaaS、两个独立序列化包及外部依赖版本保持不变。H5 与 Web 为不同平台标识;旧 Android=16 不能直接解释为新 H5,消费端需按旧成员含义迁移并重新编译。

PackageId原版本新版本
Fast.Cache3.5.393.5.40
Fast.Consul3.5.153.5.16
Fast.NET.Core3.5.463.5.47
Fast.DependencyInjection3.5.353.5.36
Fast.DynamicApplication3.5.413.5.42
Fast.EventBus3.5.343.5.35
Fast.JwtBearer3.5.503.5.51
Fast.Logging3.5.383.5.39
Fast.Mapster3.5.333.5.34
Fast.OpenApi3.5.453.5.46
Fast.Runtime3.5.363.5.37
Fast.SqlSugar3.5.753.5.76
Fast.Swagger3.5.403.5.41
Fast.UnifyResult3.5.403.5.41

验证:全解决方案最终还原、Release 构建和本地打包通过,零警告、零错误。14 个包的 84 个 DLL/XML 文件、42 个程序集版本、45 条内部依赖及三套 H5 XML 说明均已核对。三个目标各通过 290 项打包程序集断言;中英文示例三目标编译通过,42 行新旧数值映射核对一致。文档完整检查通过,含类型检查、lint、34 项测试通过/1 项因缺少 Nginx 跳过、API 覆盖、构建、434 个页面的链接/资源/锚点及格式检查。未运行宿主、真实服务或数据库迁移,未发布包。