PlumX.Core.Config 1.0.0-preview.7

PlumX.Core.Config

NuGet 包 ID：PlumX.Core.Config

定位

PlumX.Core.Config 是配置中心中立层，定义配置中心选项、provider 契约和配置构建扩展。Nacos、Consul SDK 分别位于 PlumX.Core.Configuration.Nacos 和 PlumX.Core.Configuration.Consul，不会由 Config 自动带入所有应用。

目标框架与依赖

• 目标框架：net8.0
• 项目引用：无
• 主要依赖：Microsoft.Extensions.Configuration.Abstractions、Configuration.Binder

接入方式

AddPlumConfig 是 WebApplicationBuilder 的便捷入口：先注册本地配置文件，再按 ConfigCenter 节加载已引用的远程 Provider。配置源优先级按运行模式区分：Development 等 Debug 环境远程配置作为本地默认值；Production 等非 Debug 环境远程配置最后加载并覆盖本地同名键。

builder.AddPlumConfig(options =>
{
    options.ConfigurationCenterFilePath = "Configs/config-center.json";
    options.CommonConfigFilePaths.Add("Configs/CommonConfig.json");
});

需要精确控制配置构建顺序的宿主可分别调用 AddPlumConfigFiles 和 AddPlumConfigurationCenter：

builder.Configuration.AddPlumConfigurationCenter(
    builder.Configuration.GetSection("ConfigCenter"));

本地配置引导

AddPlumConfigFiles 将 ConfigurationCenterFilePath 指定的配置中心引导文件（默认 hysSettings.json）作为第一项加载，然后加载公共配置文件、应用配置文件和环境配置文件。该引导文件只用于提供 ConfigCenter 连接配置，不是第二份公共配置。Development 等 Debug 环境最终优先级为 Nacos/Consul < CommonConfig.json < appsettings.json < appsettings.{Environment}.json < 环境变量 < 命令行参数；Production 等非 Debug 环境按 hysSettings.json -> 命令行参数 -> 环境变量 -> CommonConfig.json -> appsettings.json -> appsettings.{Environment}.json -> Nacos/Consul 排列，远程 Provider 最终覆盖本地配置。

AddPlumConfigFiles 会通过 [PlumX.Core.Config] Console 日志逐项输出加入的本地 JSON source、optional、reloadOnChange 和数量汇总。该日志表示 source 已加入 IConfigurationBuilder，不表示可选文件一定存在或已经成功解析；实际读取仍在 Build() 时发生。日志不读取或输出任何配置值。

builder.Configuration.AddPlumConfigFiles(
    builder.Environment.ContentRootPath,
    AppContext.BaseDirectory,
    builder.Environment.EnvironmentName,
    "/run/secrets/plum/config-center.json");

最后一个参数也可以是相对于启动项目 ContentRoot 的路径。容器部署必须传入容器内挂载路径，不能把开发机绝对路径写入镜像。

新宿主使用 PlumConfigurationFileOptions 只需一次调用即可替换默认 hysSettings.json，并加载多个任意名称、任意位置的公共配置文件：

using PlumX.Core.Config.Configurations;

var fileOptions = new PlumConfigurationFileOptions
{
    ConfigurationCenterFilePath = "/app/configs/config-center.json"
};
fileOptions.CommonConfigFilePaths.Add("configs/CommonConfig.json");
fileOptions.CommonConfigFilePaths.Add("/app/configs/feature-flags.json");

builder.Configuration.AddPlumConfigFiles(
    builder.Environment.ContentRootPath,
    AppContext.BaseDirectory,
    builder.Environment.EnvironmentName,
    fileOptions);

ConfigurationCenterFilePath 替换默认 hysSettings.json 查找，并且只注册这一份配置中心引导文件；CommonConfigFilePaths 非空时按集合顺序替换默认 CommonConfig.json 查找。路径可以是 ContentRoot 相对路径或绝对路径；显式角色文件仍是可选本地文件，未找到时不会阻止启动。保留原六参数重载，未传入 options 时保持旧目录和文件名回退。

本地 JSON 文件在 Development 等非 Production 环境默认启用变更监听；Production 默认关闭，以减少 Linux 容器中的文件监听器占用。调用方需要覆盖默认值时，可传入末尾的可选参数：

builder.Configuration.AddPlumConfigFiles(
    builder.Environment.ContentRootPath,
    AppContext.BaseDirectory,
    builder.Environment.EnvironmentName,
    reloadOnChange: true);

此参数只影响本扩展添加的本地 JSON 文件，不影响 ConfigCenter:ReloadOnChange 的远程配置刷新。Linux Production 部署还应在进程启动前设置 DOTNET_HOSTBUILDER__RELOADCONFIGONCHANGE=false，关闭 WebApplication.CreateBuilder 更早注册的默认 appsettings*.json 监听。

也可以绑定 PlumConfigurationOptions 后调用同名重载。远程 provider 必须由应用显式引用，且 provider 程序集名称遵循 PlumX.Core.Configuration.{Type}。

配置

{
  "ConfigCenter": {
    "Type": "None",
    "Address": "",
    "AppMainRoute": "plum/app",
    "PublicRoute": "plum/common",
    "PrivateRoute": "plum/app",
    "PublicNames": [],
    "Optional": true,
    "FailStartupOnError": false,
    "ReloadOnChange": true,
    "PollWaitTime": 120
  }
}

Type 支持 None、Nacos、Consul。启用 provider 时地址为空，或 provider 加载失败，只有在 Optional=true 且 FailStartupOnError=false 时才会记录警告并继续；显式失败配置会抛出启动异常。仅保留兼容入口 AddConfigServiceV2。

主要 API

• PlumConfigurationOptions：配置中心类型、地址、路由、公共配置名、轮询和失败策略。
• PlumConfigurationFileOptions：配置中心设置文件与多个本地公共配置文件的路径。
• IConfigurationCenterProvider：独立 provider 的加载契约。
• AddPlumConfig：WebApplicationBuilder 便捷入口，加载本地文件后按 ConfigCenter 添加 Provider。
• AddPlumConfigurationCenter：按配置动态加载 provider。
• AddConfigServiceV2：旧配置入口兼容层，绑定传入配置根的 HysOptions 后按 Type 加载 Provider。

边界与运维说明

本项目不直接连接 Nacos 或 Consul，也不保存密钥。生产环境应通过环境变量、密钥中心或外部配置注入 Address、UserName、Password；需要对应 provider 的应用必须显式添加项目引用。

这些启动诊断默认写入 Console.Out，当前不提供 PlumX.Core 配置开关；它们不注册日志 Provider，也不替代 PlumX.Core.Observability 或应用自己的 ILogger 配置。

完整的字段定义、共享/应用配置覆盖顺序、外部引导文件、Docker 路径和 ConfigCenter{PropertyName} 环境变量见 配置中心与本地配置加载。

完整使用示例

本地文件、外部引导 JSON 与远程 Provider 的组合加载见 模块使用示例。使用 Consul KV 的完整可运行入口见 PlumX.Demo.Consul。