Apq.Cfg/docs/site/guide/source-selection.md

配置源选择指南

本文档帮助您根据不同场景选择合适的配置源。

配置源分类

本地文件配置源

配置源	适用场景	优点	缺点
JSON	通用配置、结构化数据	可读性好、支持嵌套、IDE 支持好	不支持注释（标准 JSON）
YAML	DevOps 配置、K8s 配置	支持注释、简洁、可读性好	缩进敏感、解析较慢
TOML	Rust/Go 项目、简单配置	支持注释、类型明确	嵌套结构不够直观
INI	传统应用、简单键值对	简单易懂、广泛支持	不支持深层嵌套
XML	企业应用、.NET 传统项目	结构严谨、支持 Schema 验证	冗长、可读性差
.env	开发环境、Docker 配置	简单、环境变量兼容	仅支持字符串、无嵌套

数据存储配置源

配置源	适用场景	优点	缺点
Redis	高性能缓存、分布式配置	高性能、支持发布订阅	需要 Redis 服务
Database	配置审计、多租户	支持事务、可审计	性能较低、需要数据库

远程配置中心

配置中心	适用场景	优点	缺点
Consul	服务发现 + 配置管理	多功能、健康检查	功能复杂
Etcd	K8s 生态、强一致性需求	强一致性、高可用	资源占用较高
Nacos	阿里云生态、微服务	功能丰富、中文文档好	依赖较重
Apollo	大型企业、多环境管理	权限管理、灰度发布	部署复杂、只读
Zookeeper	分布式协调、传统项目	成熟稳定、广泛使用	配置管理非主要功能
Vault	密钥管理、安全敏感配置	安全性高、审计完善	学习曲线陡峭

场景选择建议

1. 单体应用 / 小型项目

推荐配置：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddJson($"config.{env}.json", level: 1, writeable: false, optional: true)
    .AddEnvironmentVariables(level: 2, prefix: "APP_")
    .Build();

理由：简单、无外部依赖、与 ASP.NET Core 配置模式一致。

2. 微服务架构

推荐配置：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddSource(new ConsulCfgSource(options => {
        options.Address = "http://consul:8500";
        options.KeyPrefix = $"services/{serviceName}/";
        options.EnableHotReload = true;
    }, level: 10))
    .Build();

理由：Consul 同时提供服务发现和配置管理，减少基础设施复杂度。

3. Kubernetes 环境

推荐配置：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddSource(new YamlFileCfgSource("/config/app-config.yaml", level: 1, 
        writeable: false, optional: false, reloadOnChange: true))
    .AddEnvironmentVariables(level: 2)
    .Build();

理由：ConfigMap 挂载为 YAML 文件，环境变量注入敏感配置。

4. 阿里云 / 国内云环境

推荐配置：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddSource(new NacosCfgSource(options => {
        options.ServerAddresses = "mse-xxx.nacos.mse.aliyuncs.com:8848";
        options.AccessKey = Environment.GetEnvironmentVariable("NACOS_AK");
        options.SecretKey = Environment.GetEnvironmentVariable("NACOS_SK");
        options.DataId = "app-config";
        options.EnableHotReload = true;
    }, level: 10))
    .Build();

理由：Nacos 是阿里云 MSE 原生支持的配置中心，中文文档完善。

5. 多环境 / 灰度发布

推荐配置：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddSource(new ApolloCfgSource(options => {
        options.AppId = "my-app";
        options.MetaServer = "http://apollo-meta:8080";
        options.Cluster = Environment.GetEnvironmentVariable("APOLLO_CLUSTER") ?? "default";
        options.Namespaces = new[] { "application", "common" };
        options.EnableHotReload = true;
    }, level: 10))
    .Build();

理由：Apollo 提供完善的多环境、多集群、灰度发布支持。

6. 安全敏感配置 / 密钥管理

推荐配置：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddSource(new VaultCfgSource(
        address: "https://vault.example.com:8200",
        roleId: Environment.GetEnvironmentVariable("VAULT_ROLE_ID")!,
        roleSecret: Environment.GetEnvironmentVariable("VAULT_SECRET_ID")!,
        enginePath: "kv",
        path: "apps/my-app/secrets",
        kvVersion: 2,
        level: 10
    ))
    .Build();

理由：Vault 专为密钥管理设计，提供审计、轮换、访问控制等安全特性。

7. 传统企业应用 / 遗留系统

推荐配置：

var cfg = new CfgBuilder()
    .AddSource(new XmlFileCfgSource("app.config", level: 0, writeable: false))
    .AddSource(new IniFileCfgSource("settings.ini", level: 1, writeable: false))
    .AddSource(new DatabaseCfgSource(options => {
        options.Provider = "SqlServer";
        options.ConnectionString = connectionString;
        options.Table = "AppConfig";
    }, level: 2))
    .Build();

理由：兼容现有配置格式，数据库配置便于审计和管理。

8. 开发环境 / 本地调试

推荐配置：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddJson("config.Development.json", level: 1, writeable: false, optional: true)
    .AddSource(new EnvFileCfgSource(".env", level: 2, optional: true))
    .AddSource(new EnvFileCfgSource(".env.local", level: 3, optional: true))
    .AddEnvironmentVariables(level: 4, prefix: "APP_")
    .Build();

理由：.env 文件便于本地开发，不会提交到版本控制。

配置源组合最佳实践

层级设计原则

level 0-9:   本地文件配置（基础配置）
level 10-19: 远程配置中心（动态配置）
level 20+:   环境变量/命令行（覆盖配置）

推荐的通用模式

var cfg = new CfgBuilder()
    // 基础配置（打包在应用中）
    .AddJson("config.json", level: 0, writeable: false)
    
    // 环境特定配置（可选）
    .AddJson($"config.{env}.json", level: 1, writeable: false, optional: true)
    
    // 本地覆盖（开发用，不提交版本控制）
    .AddJson("config.local.json", level: 2, writeable: true, optional: true, isPrimaryWriter: true)
    
    // 远程配置中心（生产环境）
    .AddSource(new ConsulCfgSource(options => { /* ... */ }, level: 10))
    
    // 密钥管理（敏感配置）
    .AddSource(new VaultCfgSource(options => { /* ... */ }, level: 15))
    
    // 环境变量（最高优先级覆盖）
    .AddEnvironmentVariables(level: 20, prefix: "APP_")
    
    .Build();

性能对比

配置源	首次加载	读取性能	热重载延迟
JSON	~1ms	~20ns	~100ms
YAML	~5ms	~20ns	~100ms
Redis	~10ms	~100μs	~10ms
Consul	~50ms	~20ns	~100ms
Etcd	~50ms	~20ns	~50ms
Nacos	~100ms	~20ns	~100ms
Vault	~100ms	~20ns	~30s (轮询)

决策流程图

需要配置管理？
├── 单体应用 → JSON + 环境变量
├── 微服务
│   ├── 已有 Consul → Consul
│   ├── K8s 环境 → Etcd 或 ConfigMap
│   └── 阿里云 → Nacos
├── 需要灰度发布 → Apollo
├── 需要密钥管理 → Vault
└── 传统企业应用 → Database

迁移建议

从 config.json 迁移到配置中心

1. 保持本地配置作为默认值
2. 配置中心只存储需要动态修改的配置
3. 敏感配置使用 Vault 或环境变量
4. 逐步迁移，先在测试环境验证

从其他配置库迁移

Apq.Cfg 兼容 Microsoft.Extensions.Configuration，可以通过 ToMicrosoftConfiguration() 方法与现有代码集成：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .Build();

// 转换为 IConfiguration，兼容现有代码
IConfigurationRoot msConfig = cfg.ToMicrosoftConfiguration();

下一步

• 配置源概述 - 了解各配置源详情
• 最佳实践 - 配置管理最佳实践
• 复杂场景示例 - 企业级应用示例