跳到主要内容
版本:3.1

系统参数(Aegis.SystemSettings)

Aegis.SystemSettings 将宿主配置中的业务参数按系统、院区和分组组织起来。已知字段使用 IOptionsMonitor<T> 读取配置类,运行时才能确定的分组和参数名使用 ISystemSettings 读取;两种方式都支持院区覆盖默认值。

如何引入​

安装 NuGet​

dotnet add package Aegis.SystemSettings

启用组件​

在宿主项目的 Component.deps.json 中,将 SystemSettings 加入 Load 清单:

{
"Components": {
"Load": [
"SystemSettings"
]
}
}

SystemSettings 不提供请求处理中间件。在 Load 中声明后,宿主会注册参数读取服务和配置类绑定。业务项目引用当前包,即可使用 ISystemSettings、SystemSettingsBindingAttribute 等公共类型。

配置当前系统编码​

{
"SystemSettings": {
"SystemCode": "OP-Nurse"
}
}

SystemSettings:SystemCode 是当前宿主的必填系统编码。未单独指定系统的配置类和动态读取默认使用此编码;若在服务注册时调用 SetDefaultSystemCode,默认读取系统采用该调用指定的值。配置类显式声明的系统编码不受此默认值影响。

组件概览​

字段说明
组件名称系统参数
真实类库Aegis.SystemSettings
组件定位按系统、院区和分组读取业务参数
引入方式安装 NuGet,并在 Component.deps.json 中启用 SystemSettings
默认参数来源宿主已加载的 IConfiguration
强类型入口IOptionsMonitor<T>
动态入口ISystemSettings

配置类属性与参数编码对应。使用指定院区读取时,组件先读取 _default 下的值,再应用该院区已经配置的字段。

什么时候要用它​

适合以下场景:

  • 参数属于可调整的业务规则,而不是代码常量。
  • 同一套默认参数需要被不同院区局部覆盖。
  • 业务代码希望使用强类型配置类,并在参数变化后读取新值。
  • 需要在运行时切换系统、院区或分组。

以下内容继续使用其他配置能力:

  • 数据库连接串、密钥和宿主端口等基础设施配置,应使用 appsettings.json、环境变量或专用密钥管理。
  • 与当前系统无关的技术开关,不应为了集中展示而改造成业务参数。

最小可运行路径​

第一步:在 appsettings.json 中准备参数​

参数放在宿主已加载的配置中,例如 appsettings.json:

{
"SystemSettings": {
"SystemCode": "OP-Nurse",
"OP-Nurse": {
"_default": {
"Registration": {
"TimeoutSeconds": 60,
"AllowCrossSlot": false
}
},
"A": {
"Registration": {
"TimeoutSeconds": 30
}
}
}
}
}

_default 是全院区默认值,A 是 A 院区覆盖值。院区未配置的字段会继续使用默认值。

第二步:声明强类型配置​

using Aegis.SystemSettings.Bindings;

/// <summary>
/// 挂号分组的默认参数及院区覆盖参数。
/// </summary>
[SystemSettingsBinding(GroupCode = "Registration")]
public sealed class RegistrationSettings
{
/// <summary>
/// 挂号操作允许等待的秒数。
/// </summary>
public int TimeoutSeconds { get; set; } = 60;

/// <summary>
/// 是否允许跨时段挂号。
/// </summary>
public bool AllowCrossSlot { get; set; }
}

GroupCode 需要与参数分组编码保持一致。未维护的字段保留 C# 属性初始值。

第三步:在业务服务中读取​

using Microsoft.Extensions.Options;

/// <summary>
/// 每次调用均读取当前生效的挂号参数。
/// </summary>
/// <param name="settings">支持默认值和院区命名选项的配置监视器。</param>
public sealed class RegistrationService(IOptionsMonitor<RegistrationSettings> settings)
{
/// <summary>
/// 读取全院区默认参数。
/// </summary>
/// <returns>当前生效的默认挂号参数。</returns>
public RegistrationSettings GetDefault()
{
return settings.CurrentValue;
}

/// <summary>
/// 读取指定院区的覆盖参数,未配置字段沿用默认值。
/// </summary>
/// <param name="hospitalCode">院区编码。</param>
/// <returns>合并默认值和院区覆盖值后的挂号参数。</returns>
public RegistrationSettings GetForHospital(string hospitalCode)
{
return settings.Get(hospitalCode);
}
}

CurrentValue 读取全院区默认值;Get(hospitalCode) 先加载默认值,再叠加指定院区的覆盖值。院区编码由业务上下文显式传入,组件不读取隐式请求上下文。

院区参数覆盖​

取值顺序是“全院区默认值打底,指定院区局部覆盖”。

读取方式TimeoutSecondsAllowCrossSlot
settings.CurrentValue60false
settings.Get("A")30false
settings.Get("B")60false

B 院区没有单独配置时,整个结果来自全院区默认值。

按运行时坐标读取​

编译期无法确定分组或参数编码时,注入 ISystemSettings:

using Aegis.SystemSettings.Bindings;

/// <summary>
/// 按运行时给定的院区、分组和参数名读取系统参数。
/// </summary>
/// <param name="settings">当前系统的参数读取入口。</param>
public sealed class DynamicSettingsService(ISystemSettings settings)
{
/// <summary>
/// 读取默认院区的挂号超时秒数。
/// </summary>
/// <returns>当前超时秒数;缺失或无法转换时返回 60。</returns>
public int GetDefaultTimeout()
{
return settings.Get("Registration", "TimeoutSeconds", 60);
}

/// <summary>
/// 读取指定院区的挂号超时秒数。
/// </summary>
/// <param name="hospitalCode">院区编码。</param>
/// <returns>院区值、默认院区值或缺省值 60。</returns>
public int GetHospitalTimeout(string hospitalCode)
{
return settings
.For(hospitalCode)
.Get("Registration", "TimeoutSeconds", 60);
}

/// <summary>
/// 读取业务要求必需存在的字符串参数。
/// </summary>
/// <param name="groupCode">参数所属分组。</param>
/// <param name="key">参数编码。</param>
/// <returns>已配置的字符串值。</returns>
/// <exception cref="InvalidOperationException">参数缺失或无法读取为字符串。</exception>
public string GetRequiredValue(string groupCode, string key)
{
return settings.Require<string>(groupCode, key);
}
}
API语义
Get<T>(groupCode, key, defaultValue)参数缺失或无法转换时返回默认值
Require<T>(groupCode, key)参数缺失或无法转换时抛出异常
For(hospitalCode)切换到当前系统的指定院区
ForSystem(systemCode, hospitalCode)切换到指定系统和院区
Group(groupCode).As<T>()将分组绑定为一次性强类型快照

Group(groupCode).As<T>() 返回调用时的快照,后续参数变更不会修改已返回的对象。

跨系统读取​

配置类固定读取另一个系统时,在绑定特性中指定 SystemCode:

using Aegis.SystemSettings.Bindings;

/// <summary>
/// 固定读取结算系统中的折扣参数。
/// </summary>
[SystemSettingsBinding(SystemCode = "Settle", GroupCode = "Discount")]
public sealed class BillingDiscountSettings
{
/// <summary>
/// 自费结算适用的折扣比例。
/// </summary>
public decimal SelfPayDiscountRate { get; set; }
}

系统编码由运行时参数决定时,使用 ISystemSettings:

var rate = settings
.ForSystem("Settle", hospitalCode)
.Get("Discount", "SelfPayDiscountRate", 1m);

一个强类型配置类只能对应一个系统和分组坐标。

绑定声明决定读取哪个系统和分组,参数仍需存在于宿主配置中。例如上面的配置类读取 SystemSettings:Settle:_default:Discount;按院区读取时,再叠加 SystemSettings:Settle:院区编码:Discount。

默认自动扫描项目程序集与 Aegis.* 框架程序集。配置类位于额外第三方程序集时,在宿主服务注册阶段追加其扫描范围:

services.AddSystemSettingsBindings(typeof(BillingDiscountSettings).Assembly);

这段注册用于补充扫描范围,不再对同一类型追加显式绑定。

显式注册配置类​

配置类不适合添加 [SystemSettingsBinding] 特性时,可以在宿主中显式声明绑定:

services.AddSystemSettingsBinding<RegistrationSettings>(groupCode: "Registration");

指定另一个系统时:

services.AddSystemSettingsBinding<BillingDiscountSettings>(groupCode: "Discount", systemCode: "Settle");

同一类型不能同时使用特性绑定和显式绑定,冲突会在宿主启动时报错。

采用显式注册时,配置类不保留前面示例中的 [SystemSettingsBinding]。在 AddSystemSettings 回调内使用 AddBinding<T> 也遵循相同规则,同一类型只声明一次。

读取参数变化​

IOptionsMonitor<T> 可以被任意生命周期的服务注入。宿主 IConfiguration 发出重载通知后,组件清除默认值和已读取过的院区缓存,后续读取会重新绑定。配置来源本身需要支持并触发重载;修改不支持重载的来源不会自动刷新参数。

业务只需要读取当前参数时,保存监视器,并在每次使用时获取对应院区的值:

using Microsoft.Extensions.Options;

/// <summary>
/// 按需读取 A 院区当前生效的挂号参数。
/// </summary>
/// <param name="settings">由系统参数组件维护的挂号参数监视器。</param>
public sealed class RegistrationPolicyReader(IOptionsMonitor<RegistrationSettings> settings)
{
/// <summary>
/// 每次读取时从监视器获取 A 院区的有效超时秒数。
/// </summary>
public int TimeoutSeconds => settings.Get("A").TimeoutSeconds;
}

配置缓存由监视器维护,每次属性访问通过 Get("A") 获取当时的有效配置。更新生效后,后续读取取得新值,之前保存的配置对象不会原地变化。

业务需要在参数变化时重建本地资源,可以按其生命周期订阅 OnChange,并协调初始构建与变更处理的并发。回调中的 name 不一定是某个院区编码,需要指定院区的新值时重新调用 Get(hospitalCode);订阅返回的 IDisposable 应在服务停止时释放。

JSON 字符串参数​

IConfiguration.Bind 不会将一个值中的 JSON 文本自动反序列化为列表或嵌套对象。参数值本身是 JSON 字符串时,先读取字符串,再显式反序列化:

using System.Text.Json;

var raw = settings
.For(hospitalCode)
.Get<string>("Registration", "ExcludedDepartments");

var departments = string.IsNullOrEmpty(raw)
? []
: JsonSerializer.Deserialize<List<string>>(raw) ?? [];

int、bool、decimal 和 string 等基本类型可以直接读取。

接入后怎么确认生效​

  1. 启动宿主,确认 ISystemSettings 和已标注配置类的 IOptionsMonitor<T> 可以从 DI 解析。
  2. 读取 CurrentValue,确认与全院区默认值一致。
  3. 传入已配置的院区编码,确认只覆盖该院区已维护的字段。
  4. 读取不存在的参数,分别确认 Get 返回默认值、Require 抛出异常。

边界与限制​

  • SystemSettings:SystemCode 指定宿主的默认系统;配置类显式声明的 SystemCode 可以指向其他系统,并应与目标配置节的系统编码匹配。
  • 院区编码、分组编码和参数编码由业务代码与参数来源约定,应保持稳定。
  • IOptionsMonitor<T> 适合已知字段的强类型读取;ISystemSettings 适合运行时坐标,不提供编译期字段检查。
  • Group(groupCode).As<T>() 是一次性快照,不会自动更新已返回的对象。
  • 一个配置类只能使用一种绑定声明,不能同时使用特性和显式注册。
  • 将 JSON 存入单个参数值时,需要由业务代码显式反序列化。
  • 动态读取不会校验参数名是否拼写正确;关键参数可以使用 Require<T>,避免将默认值误认为已配置值。

常见问题​

为什么读到的都是配置类默认值​

按顺序检查 SystemCode、GroupCode、院区编码和属性名。系统编码需要匹配 SystemSettings 下的系统节,分组编码需要匹配绑定声明,配置类属性名需要与参数编码对应。

参数变化后会修改已取得的配置对象吗​

不会。IOptionsMonitor<T> 在下一次读取时返回重新绑定的对象;业务代码长期保留的旧对象和 Group(groupCode).As<T>() 已返回的快照不会就地变化。