SuperAPI AI 工具集

dotnet-options-pattern

编程与开发

查看项目

更新于 10-16 02:10

技能介绍

用途

该技能用于在 .NET 中实现 Options 模式,为配置组提供强类型访问。它将配置项绑定到专门的 Options 类,替代直接读取散落的配置键,从而在编译期获得类型检查,并在启动或运行期对配置进行集中校验。

主要能力

技能内容覆盖以下方面:

  • 三种 Options 接口的选型说明:

    • IOptions<T>:单例(Singleton)生命周期,启动时读取一次,不支持重载,不支持命名选项,适用于静态配置。
    • IOptionsSnapshot<T>:作用域(Scoped)生命周期,按请求重新加载,支持重载,支持命名选项,适用于请求级配置。
    • IOptionsMonitor<T>:单例(Singleton)生命周期,支持重载,支持命名选项,适用于单例服务和变更通知场景。
  • Options 类目录结构:示例中 Options 类统一放在 /Application/Options/ 目录下,如 DatabaseOptions.cs、JwtOptions.cs、CacheOptions.cs、EmailOptions.cs、FeatureFlagOptions.cs。

  • 基础 Options 类模板:以 DatabaseOptions 为例,约定使用 Options 后缀、提供公共 getter/setter、通过数据注解或 IValidateOptions 进行验证,并定义 SectionName 常量。示例包含连接字符串、连接池大小、超时、连接池开关、查询日志开关等属性。

  • 数据注解验证模板:以 JwtOptions 为例,使用 [Required]、[MinLength]、[Range] 等特性对 Secret、Issuer、Audience、访问令牌与刷新令牌过期时间进行约束。

  • 自定义验证模板:以 CacheOptionsValidator 实现 IValidateOptions<CacheOptions> 为例,演示复杂规则(如启用缓存时必须提供 Redis 连接字符串、滑动过期必须小于默认过期)的校验逻辑,并返回 ValidateOptionsResult。

  • 依赖注入注册模板:展示在 DependencyInjection.cs 中通过 services.Configure<T>、services.AddOptions<T>().Bind(...).ValidateDataAnnotations().ValidateOnStart()、注册自定义 IValidateOptions、以及 PostConfigure 的多种注册方式。

  • 在单例服务中使用 IOptions<T>:以 JwtTokenService 为例,通过 options.Value 读取一次配置,用于生成 JWT 令牌。

  • 在作用域服务中使用 IOptionsSnapshot<T>:以 SendEmailHandler 为例,每次请求获取最新值;文档注明其不能注入到单例服务。

  • 在单例中使用 IOptionsMonitor<T>:以 FeatureFlagService 为例,通过 OnChange 订阅配置变更并记录日志,通过 CurrentValue 读取当前值,并在 Dispose 中释放监听器。

  • 命名选项:以 StorageOptions 为例,定义 Local 与 Cloud 两个命名选项,展示 appsettings.json 结构、注册方式及在 FileUploadService 中通过 optionsSnapshot.Get(...) 访问命名选项的用法。

  • 后台服务中的 Options:以 OutboxProcessorJob 为例,说明后台服务是单例,应使用 IOptionsMonitor<T> 以获取配置更新而无需重启。

使用方式

按照技能提供的目录结构创建 Options 类,在 appsettings.json 中建立对应配置节,在依赖注入注册代码中完成绑定与验证注册,然后在服务构造函数中注入对应的 IOptions<T>、IOptionsSnapshot<T> 或 IOptionsMonitor<T> 并按需读取值。验证可在启动时通过 ValidateOnStart() 快速失败。

适用场景

适用于采用整洁架构的 .NET 项目,尤其是需要将数据库、JWT、缓存、邮件、功能开关、存储、发件箱等配置组进行强类型化管理,并需要对配置进行启动校验或运行时热更新的场景。

限制

文档明确指出 IOptionsSnapshot<T> 不能注入到单例服务中。各接口的生命周期与重载能力差异需按表格选型。关于具体价格、收费、平台依赖或其他未在资料中提及的功能,暂未提供。