模块手册
Fast.NET 由 17 个可独立发布的 NuGet 包组成。除 Fast.IaaS 外,主要模块面向 .NET 8、.NET 9 和 .NET 10;Fast.IaaS 面向 .NET Standard 2.1。
点击下表中的包名查看安装、配置和示例,也可直接查阅公开 API 参考。已有项目请先查看升级与迁移。
各模块标注用法或 API 的参考版本。安装命令使用当前 NuGet 源提供的包,示例验证版本会另行标明。
| 包 | 用途 | 主要入口 | 默认配置节点 / 外部依赖 |
|---|---|---|---|
Fast.Runtime | ASP.NET Core 共享上下文、配置与 MVC 扩展 | AddConfigurableOptions<T>()、AddMvcFilter() | 通常由其他 Fast.NET 包传递引用 |
Fast.IaaS | 编码、校验、脱敏、重试、树结构与通用扩展 | MaskingUtil、RetryUtil 等 | 无 Web 宿主依赖 |
Fast.NET.Core | 应用初始化、配置扫描、CORS、压缩、请求缓冲 | builder.Initialize()、AddCorsAccessor()、AddGzipCompression() | CorsAccessorSettings |
Fast.Cache | CSRedisCore 缓存封装 | services.AddCache() | RedisSettings;需要 Redis |
Fast.Consul | 服务注册、健康检查和 KV | services.AddFastConsul() | ConsulSettings;需要 Consul |
Fast.DependencyInjection | 基于标记接口的约定式依赖注入 | services.AddDependencyInjection() | 使用 ITransientDependency、IScopedDependency、ISingletonDependency |
Fast.DynamicApplication | 将应用服务发现为动态 API | services.AddDynamicApplication() | 必须先调用 AddControllers() |
Fast.EventBus | 进程内有界通道、发布订阅和后台处理 | services.AddEventBus() | 默认容量 3000;不提供分布式持久化 |
Fast.JwtBearer | JWT Bearer 认证、授权和令牌工具 | services.AddJwtBearer() | JWTSettings |
Fast.Logging | 控制台与文件日志扩展 | services.AddLoggingService() | Logging:Fast;文件目录必须可写 |
Fast.Mapster | Mapster 注册与对象映射 | services.AddMapster() | Mapster 10 |
Fast.OpenApi | OpenAPI DTO 与 JavaScript/TypeScript 客户端生成 | services.AddOpenApi() | OpenApiSettings |
Fast.Serialization.System.Text.Json | System.Text.Json 统一选项、转换器和脱敏 | services.AddSerialization() | 与 Newtonsoft.Json 模块通常二选一 |
Fast.Serialization.Newtonsoft.Json | Newtonsoft.Json 统一选项、转换器和脱敏 | services.AddSerialization()、MVC 扩展 | 与 System.Text.Json 模块通常二选一 |
Fast.SqlSugar | SqlSugar、多数据库配置、仓储和分页 | services.AddSqlSugar()、AddSnowflake() | ConnectionSettings、SnowflakeSettings;需要数据库 |
Fast.Swagger | Swagger 文档、分组、安全定义和 UI | AddSwaggerDocuments()、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 在请求审计信息不可用时保留空字段。
推荐注册顺序
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 分段设置控制台颜色并输出文本:
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 Logo | Green |
| 运行环境名称 | 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.Runtime 3.5.37 H5 数值迁移,再按 14 个相关包的版本表 核对依赖。新增 H5 后,Android 及后续标志位的数值已变化。
- 使用了已移除的 Runtime 组合成员:查看 Fast.Runtime 3.5.36 组合成员迁移。
- 使用 SqlSugar 多库配置或旧仓储成员:查看 Fast.SqlSugar 3.5.73 连接配置与公共 API 迁移。
下面的版本表保留各批次当时的版本和数值。发布记录见 Fast.NET 的 CHANGELOG。
2026-10-17 版本同步
本批次更新 Runtime、EventBus、Logging、UnifyResult,以及 Runtime 依赖链上的其他模块,共 14 个包,均按 3.5.x 补丁递增。下表记录该历史批次的源码目标版本,不代表已上传 NuGet。Fast.IaaS 与两个序列化包没有本次源码或依赖变化,版本保持不变。
| PackageId | 原版本 | 本次版本 |
|---|---|---|
Fast.Cache | 3.5.34 | 3.5.35 |
Fast.Consul | 3.5.10 | 3.5.11 |
Fast.NET.Core | 3.5.40 | 3.5.41 |
Fast.DependencyInjection | 3.5.30 | 3.5.31 |
Fast.DynamicApplication | 3.5.36 | 3.5.37 |
Fast.EventBus | 3.5.29 | 3.5.30 |
Fast.JwtBearer | 3.5.44 | 3.5.45 |
Fast.Logging | 3.5.33 | 3.5.34 |
Fast.Mapster | 3.5.28 | 3.5.29 |
Fast.OpenApi | 3.5.40 | 3.5.41 |
Fast.Runtime | 3.5.31 | 3.5.32 |
Fast.SqlSugar | 3.5.69 | 3.5.70 |
Fast.Swagger | 3.5.35 | 3.5.36 |
Fast.UnifyResult | 3.5.35 | 3.5.36 |
2026-10-17 请求内缓存优先
本轮将 Runtime 及其依赖链上的 14 个包各递增一个补丁版本。Fast.Runtime 3.5.33 在请求内缓存命中时直接返回;未命中才检查取消并进入共享缓存或远程查询。IaaS 与两个独立序列化包版本保持不变。下表为该历史批次的源码目标版本,按要求未执行 Fast.NET 构建、打包或测试;上一批次的验证记录不适用于这些新版本。
| PackageId | 原版本 | 本轮版本 |
|---|---|---|
Fast.Cache | 3.5.35 | 3.5.36 |
Fast.Consul | 3.5.11 | 3.5.12 |
Fast.NET.Core | 3.5.41 | 3.5.42 |
Fast.DependencyInjection | 3.5.31 | 3.5.32 |
Fast.DynamicApplication | 3.5.37 | 3.5.38 |
Fast.EventBus | 3.5.30 | 3.5.31 |
Fast.JwtBearer | 3.5.45 | 3.5.46 |
Fast.Logging | 3.5.34 | 3.5.35 |
Fast.Mapster | 3.5.29 | 3.5.30 |
Fast.OpenApi | 3.5.41 | 3.5.42 |
Fast.Runtime | 3.5.32 | 3.5.33 |
Fast.SqlSugar | 3.5.70 | 3.5.71 |
Fast.Swagger | 3.5.36 | 3.5.37 |
Fast.UnifyResult | 3.5.36 | 3.5.37 |
2026-10-24 鸿蒙枚举与依赖同步
本轮将 Runtime 及其依赖链上的 14 个包各递增一个 3.5.x 补丁版本;IaaS 与两个独立序列化包不变。下表为本批次的 NuGet 包版本。Fast.Runtime 新增 HarmonyOS 并调整枚举数值,这是破坏性变更,按要求继续使用 3.5.x。数值迁移和消费端重新编译要求见 Runtime 手册。
| PackageId | 原版本 | 本轮版本 |
|---|---|---|
Fast.Cache | 3.5.36 | 3.5.37 |
Fast.Consul | 3.5.12 | 3.5.13 |
Fast.NET.Core | 3.5.42 | 3.5.43 |
Fast.DependencyInjection | 3.5.32 | 3.5.33 |
Fast.DynamicApplication | 3.5.38 | 3.5.39 |
Fast.EventBus | 3.5.31 | 3.5.32 |
Fast.JwtBearer | 3.5.46 | 3.5.47 |
Fast.Logging | 3.5.35 | 3.5.36 |
Fast.Mapster | 3.5.30 | 3.5.31 |
Fast.OpenApi | 3.5.42 | 3.5.43 |
Fast.Runtime | 3.5.33 | 3.5.34 |
Fast.SqlSugar | 3.5.71 | 3.5.72 |
Fast.Swagger | 3.5.37 | 3.5.38 |
Fast.UnifyResult | 3.5.37 | 3.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.JwtBearer | 3.5.47 | 3.5.48 | Fast.JwtBearer |
Fast.Serialization.Newtonsoft.Json | 3.5.27 | 3.5.28 | Fast.Serialization.Newtonsoft.Json |
Fast.SqlSugar | 3.5.72 | 3.5.73 | Fast.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.Cache | 3.5.37 | 3.5.38 |
Fast.Consul | 3.5.13 | 3.5.14 |
Fast.NET.Core | 3.5.44 | 3.5.45 |
Fast.DependencyInjection | 3.5.33 | 3.5.34 |
Fast.DynamicApplication | 3.5.39 | 3.5.40 |
Fast.EventBus | 3.5.32 | 3.5.33 |
Fast.JwtBearer | 3.5.48 | 3.5.49 |
Fast.Logging | 3.5.36 | 3.5.37 |
Fast.Mapster | 3.5.31 | 3.5.32 |
Fast.OpenApi | 3.5.43 | 3.5.44 |
Fast.Runtime | 3.5.34 | 3.5.35 |
Fast.SqlSugar | 3.5.73 | 3.5.74 |
Fast.Swagger | 3.5.38 | 3.5.39 |
Fast.UnifyResult | 3.5.38 | 3.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.Cache | 3.5.38 | 3.5.39 |
Fast.Consul | 3.5.14 | 3.5.15 |
Fast.NET.Core | 3.5.45 | 3.5.46 |
Fast.DependencyInjection | 3.5.34 | 3.5.35 |
Fast.DynamicApplication | 3.5.40 | 3.5.41 |
Fast.EventBus | 3.5.33 | 3.5.34 |
Fast.JwtBearer | 3.5.49 | 3.5.50 |
Fast.Logging | 3.5.37 | 3.5.38 |
Fast.Mapster | 3.5.32 | 3.5.33 |
Fast.OpenApi | 3.5.44 | 3.5.45 |
Fast.Runtime | 3.5.35 | 3.5.36 |
Fast.SqlSugar | 3.5.74 | 3.5.75 |
Fast.Swagger | 3.5.39 | 3.5.40 |
Fast.UnifyResult | 3.5.39 | 3.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.Cache | 3.5.39 | 3.5.40 |
Fast.Consul | 3.5.15 | 3.5.16 |
Fast.NET.Core | 3.5.46 | 3.5.47 |
Fast.DependencyInjection | 3.5.35 | 3.5.36 |
Fast.DynamicApplication | 3.5.41 | 3.5.42 |
Fast.EventBus | 3.5.34 | 3.5.35 |
Fast.JwtBearer | 3.5.50 | 3.5.51 |
Fast.Logging | 3.5.38 | 3.5.39 |
Fast.Mapster | 3.5.33 | 3.5.34 |
Fast.OpenApi | 3.5.45 | 3.5.46 |
Fast.Runtime | 3.5.36 | 3.5.37 |
Fast.SqlSugar | 3.5.75 | 3.5.76 |
Fast.Swagger | 3.5.40 | 3.5.41 |
Fast.UnifyResult | 3.5.40 | 3.5.41 |
验证:全解决方案最终还原、Release 构建和本地打包通过,零警告、零错误。14 个包的 84 个 DLL/XML 文件、42 个程序集版本、45 条内部依赖及三套 H5 XML 说明均已核对。三个目标各通过 290 项打包程序集断言;中英文示例三目标编译通过,42 行新旧数值映射核对一致。文档完整检查通过,含类型检查、lint、34 项测试通过/1 项因缺少 Nginx 跳过、API 覆盖、构建、434 个页面的链接/资源/锚点及格式检查。未运行宿主、真实服务或数据库迁移,未发布包。
