|
|
@@ -0,0 +1,524 @@
|
|
|
+# Apq.Cfg 解决方案分析报告
|
|
|
+
|
|
|
+**生成日期**：2026-01-02（更新版）
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 一、总体评价 (9.4/10)
|
|
|
+
|
|
|
+这是一个**设计精良、功能完善**的统一配置管理库，本次更新新增了**默认层级**功能，简化了配置源的使用：
|
|
|
+
|
|
|
+| 方面 | 评分 | 说明 |
|
|
|
+|------|------|------|
|
|
|
+| **架构设计** | 9.5/10 | 清晰的分层架构、插件化配置源、默认层级设计合理 |
|
|
|
+| **功能完整性** | 9.5/10 | 支持 18 种配置源 + 配置验证 + 快照导出 + 模板引擎 |
|
|
|
+| **代码质量** | 9/10 | 命名规范统一、注释完善、异步支持良好 |
|
|
|
+| **测试覆盖** | 9.5/10 | **505 个单元测试**，全部通过，API 覆盖率 100%，完整性能基准 |
|
|
|
+| **文档质量** | 9.5/10 | README 详细，多语言文档站点，默认层级文档完善 |
|
|
|
+| **性能优化** | 8.5/10 | 批量操作零分配回调、层级缓存、防抖重载 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 二、本次更新亮点
|
|
|
+
|
|
|
+### 2.1 新增功能：默认层级
|
|
|
+
|
|
|
+新增 `CfgSourceLevels` 静态类，为每种配置源定义了默认层级：
|
|
|
+
|
|
|
+| 层级范围 | 用途 | 配置源 | 默认层级 |
|
|
|
+|----------|------|--------|----------|
|
|
|
+| 0-99 | 基础配置文件 | Json, Ini, Xml, Yaml, Toml | 0 |
|
|
|
+| 100-199 | 远程存储 | Redis, Database | 100 |
|
|
|
+| 200-299 | 配置中心 | Consul, Etcd, Nacos, Apollo, Zookeeper | 200 |
|
|
|
+| 300-399 | 密钥管理 | Vault | 300 |
|
|
|
+| 400+ | 环境相关 | .env, EnvironmentVariables | 400 |
|
|
|
+
|
|
|
+**使用示例**：
|
|
|
+
|
|
|
+```csharp
|
|
|
+// 之前需要手动指定层级
|
|
|
+var cfg = new CfgBuilder()
|
|
|
+ .AddJson("config.json", level: 0)
|
|
|
+ .AddConsul("http://consul:8500", "myapp/config/", level: 10)
|
|
|
+ .AddEnvironmentVariables(level: 20, prefix: "APP_")
|
|
|
+ .Build();
|
|
|
+
|
|
|
+// 现在可以使用默认层级
|
|
|
+var cfg = new CfgBuilder()
|
|
|
+ .AddJson("config.json") // 默认层级 0
|
|
|
+ .AddConsul("http://consul:8500", "myapp/config/") // 默认层级 200
|
|
|
+ .AddEnvironmentVariables(prefix: "APP_") // 默认层级 400
|
|
|
+ .Build();
|
|
|
+```
|
|
|
+
|
|
|
+### 2.2 文档更新
|
|
|
+
|
|
|
+- 更新了所有配置源文档，添加默认层级说明
|
|
|
+- 更新了中英文文档站点的 config-sources 和 examples 目录
|
|
|
+- 代码示例统一使用默认层级
|
|
|
+
|
|
|
+### 2.3 版本信息
|
|
|
+
|
|
|
+**当前版本**：v1.1.2（准备中）
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 三、项目结构概览
|
|
|
+
|
|
|
+### 3.1 解决方案组成
|
|
|
+
|
|
|
+共 **21 个项目**，分为以下几类：
|
|
|
+
|
|
|
+```
|
|
|
+Apq.Cfg/ # 核心库（JSON、环境变量、DI 集成）
|
|
|
+├── 文件格式扩展 (5 个)
|
|
|
+│ ├── Apq.Cfg.Ini/ # INI 格式支持
|
|
|
+│ ├── Apq.Cfg.Xml/ # XML 格式支持
|
|
|
+│ ├── Apq.Cfg.Yaml/ # YAML 格式支持
|
|
|
+│ ├── Apq.Cfg.Toml/ # TOML 格式支持
|
|
|
+│ └── Apq.Cfg.Env/ # .env 文件格式支持
|
|
|
+├── 远程配置中心 (8 个)
|
|
|
+│ ├── Apq.Cfg.Redis/ # Redis 配置源
|
|
|
+│ ├── Apq.Cfg.Database/ # 数据库配置源
|
|
|
+│ ├── Apq.Cfg.Consul/ # Consul 配置中心
|
|
|
+│ ├── Apq.Cfg.Etcd/ # Etcd 配置中心
|
|
|
+│ ├── Apq.Cfg.Nacos/ # Nacos 配置中心
|
|
|
+│ ├── Apq.Cfg.Apollo/ # Apollo 配置中心
|
|
|
+│ ├── Apq.Cfg.Zookeeper/ # Zookeeper 配置中心
|
|
|
+│ └── Apq.Cfg.Vault/ # HashiCorp Vault 密钥管理
|
|
|
+├── 加密脱敏 (3 个)
|
|
|
+│ ├── Apq.Cfg.Crypto/ # 加密脱敏核心包
|
|
|
+│ ├── Apq.Cfg.Crypto.DataProtection/ # ASP.NET Core Data Protection 集成
|
|
|
+│ └── Apq.Cfg.Crypto.Tool/ # 加密命令行工具 (dotnet tool)
|
|
|
+├── 源生成器 (1 个)
|
|
|
+│ └── Apq.Cfg.SourceGenerator/ # 编译时源生成器（Native AOT）
|
|
|
+├── 测试项目 (2 个)
|
|
|
+│ ├── Apq.Cfg.Tests.Net8/ # .NET 8 测试项目
|
|
|
+│ └── Apq.Cfg.Tests.Net10/ # .NET 10 测试项目
|
|
|
+└── 其他 (2 个)
|
|
|
+ ├── Apq.Cfg.Samples/ # 示例项目
|
|
|
+ └── Apq.Cfg.Benchmarks/ # 性能基准测试
|
|
|
+```
|
|
|
+
|
|
|
+### 3.2 目标框架支持
|
|
|
+
|
|
|
+| 项目类型 | 目标框架 |
|
|
|
+|---------|---------|
|
|
|
+| 核心库及扩展项目 | `net8.0;net10.0` (LTS 版本) |
|
|
|
+| Apq.Cfg.SourceGenerator | `netstandard2.0` (Roslyn 分析器要求) |
|
|
|
+| Apq.Cfg.Tests.Net8 | `net8.0` |
|
|
|
+| Apq.Cfg.Tests.Net10 | `net10.0` |
|
|
|
+| Apq.Cfg.Samples | `net10.0` |
|
|
|
+| Apq.Cfg.Benchmarks | `net8.0;net10.0` |
|
|
|
+| Apq.Cfg.Crypto.Tool | `net10.0` |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 四、测试覆盖分析
|
|
|
+
|
|
|
+### 4.1 测试统计
|
|
|
+
|
|
|
+| 统计项 | 数量 |
|
|
|
+|-------|------|
|
|
|
+| 测试文件数 | 33 个 |
|
|
|
+| 测试方法总数 | **505 个** |
|
|
|
+| 需外部服务 | 41 个 |
|
|
|
+| 可直接运行 | 464 个 |
|
|
|
+
|
|
|
+### 4.2 测试分布
|
|
|
+
|
|
|
+| 测试类别 | 测试文件 | 测试数量 |
|
|
|
+|---------|---------|---------|
|
|
|
+| **加密脱敏** | CryptoTests.cs | 58 |
|
|
|
+| **编码处理** | EncodingTests.cs, EncodingDetectionTests.cs | 47 |
|
|
|
+| **性能优化** | PerformanceOptimizationTests.cs | 30 |
|
|
|
+| **配置验证** | ValidationTests.cs | 30 |
|
|
|
+| **配置变更** | ConfigChangesSubscriptionTests.cs | 28 |
|
|
|
+| **边界条件** | BoundaryConditionTests.cs | 25 |
|
|
|
+| **动态重载** | DynamicReloadTests.cs | 22 |
|
|
|
+| **依赖注入** | ServiceCollectionExtensionsTests.cs | 21 |
|
|
|
+| **配置模板** | TemplateTests.cs | 21 |
|
|
|
+| **异常处理** | ExceptionHandlingTests.cs | 18 |
|
|
|
+| **配置快照** | SnapshotTests.cs | 17 |
|
|
|
+| **文件格式** | JsonCfgTests, EnvCfgTests, IniCfgTests, XmlCfgTests, YamlCfgTests, TomlCfgTests | 52 |
|
|
|
+| **远程配置** | RedisCfgTests, DatabaseCfgTests, ConsulCfgTests, EtcdCfgTests, NacosCfgTests, ApolloCfgTests, ZookeeperCfgTests, VaultCfgTests | 56 |
|
|
|
+| **其他** | CfgBuilderAdvancedTests, CfgSectionTests, ConcurrencyTests, SourceGeneratorTests, CfgRootExtensionsTests, EnvVarsCfgTests | 47 |
|
|
|
+
|
|
|
+### 4.3 测试框架版本
|
|
|
+
|
|
|
+| 框架 | 通过 | 失败 | 跳过 | 总计 | 状态 |
|
|
|
+|-----|-----|-----|-----|-----|------|
|
|
|
+| .NET 8.0 | 464 | 0 | 41 | 505 | ✅ 通过 |
|
|
|
+| .NET 10.0 | 464 | 0 | 41 | 505 | ✅ 通过 |
|
|
|
+
|
|
|
+> **说明**：41 个跳过的测试需要外部服务（Redis、Consul、Etcd、Nacos、Apollo、Zookeeper、Vault、Database）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 五、核心功能详解
|
|
|
+
|
|
|
+### 5.1 配置源默认层级 (CfgSourceLevels)
|
|
|
+
|
|
|
+**文件位置**：`Apq.Cfg/CfgSourceLevels.cs`
|
|
|
+
|
|
|
+```csharp
|
|
|
+public static class CfgSourceLevels
|
|
|
+{
|
|
|
+ // 本地文件配置源 (0-99)
|
|
|
+ public const int Json = 0;
|
|
|
+ public const int Ini = 0;
|
|
|
+ public const int Xml = 0;
|
|
|
+ public const int Yaml = 0;
|
|
|
+ public const int Toml = 0;
|
|
|
+
|
|
|
+ // 远程存储 (100-199)
|
|
|
+ public const int Redis = 100;
|
|
|
+ public const int Database = 100;
|
|
|
+
|
|
|
+ // 配置中心 (200-299)
|
|
|
+ public const int Consul = 200;
|
|
|
+ public const int Etcd = 200;
|
|
|
+ public const int Nacos = 200;
|
|
|
+ public const int Apollo = 200;
|
|
|
+ public const int Zookeeper = 200;
|
|
|
+
|
|
|
+ // 密钥管理 (300-399)
|
|
|
+ public const int Vault = 300;
|
|
|
+
|
|
|
+ // 环境相关 (400+)
|
|
|
+ public const int Env = 400;
|
|
|
+ public const int EnvironmentVariables = 400;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 5.2 配置验证
|
|
|
+
|
|
|
+支持多种验证规则，可在启动时或运行时验证配置：
|
|
|
+
|
|
|
+```csharp
|
|
|
+var result = cfg.Validate(v => v
|
|
|
+ .Required("Database:ConnectionString")
|
|
|
+ .Range("App:Port", 1, 65535)
|
|
|
+ .Regex("App:Email", @"^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$")
|
|
|
+ .OneOf("App:Environment", "Development", "Staging", "Production")
|
|
|
+ .Length("App:ApiKey", minLength: 32, maxLength: 64)
|
|
|
+ .DependsOn("App:UseCache", "App:CacheServer")
|
|
|
+ .Custom("App:Timeout", value => int.TryParse(value, out var t) && t > 0, "必须是正整数")
|
|
|
+);
|
|
|
+
|
|
|
+if (!result.IsValid)
|
|
|
+{
|
|
|
+ foreach (var error in result.Errors)
|
|
|
+ {
|
|
|
+ Console.WriteLine($"{error.Key}: {error.Message}");
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 5.3 配置快照导出
|
|
|
+
|
|
|
+支持将配置导出为多种格式：
|
|
|
+
|
|
|
+```csharp
|
|
|
+// 导出为 JSON
|
|
|
+var json = cfg.ExportSnapshotAsJson();
|
|
|
+
|
|
|
+// 导出为键值对
|
|
|
+var keyValue = cfg.ExportSnapshot(ExportFormat.KeyValue);
|
|
|
+
|
|
|
+// 导出为环境变量格式
|
|
|
+var env = cfg.ExportSnapshotAsEnv();
|
|
|
+
|
|
|
+// 带过滤和脱敏
|
|
|
+var options = new ExportOptions
|
|
|
+{
|
|
|
+ Format = ExportFormat.Json,
|
|
|
+ KeyFilter = key => !key.Contains("Secret"),
|
|
|
+ ValueMasker = (key, value) => key.Contains("Password") ? "***" : value
|
|
|
+};
|
|
|
+var filtered = cfg.ExportSnapshot(options);
|
|
|
+```
|
|
|
+
|
|
|
+### 5.4 配置模板与变量替换
|
|
|
+
|
|
|
+支持在配置值中使用变量引用：
|
|
|
+
|
|
|
+```csharp
|
|
|
+// config.json: { "App:Name": "MyApp", "App:LogPath": "${App:Name}/logs" }
|
|
|
+var cfg = new CfgBuilder()
|
|
|
+ .AddJson("config.json") // 使用默认层级 0
|
|
|
+ .Build();
|
|
|
+
|
|
|
+// 解析变量引用
|
|
|
+var logPath = cfg.GetResolved("App:LogPath");
|
|
|
+// 返回: "MyApp/logs"
|
|
|
+
|
|
|
+// 引用环境变量
|
|
|
+var home = cfg.GetResolved("Paths:Home"); // ${ENV:USERPROFILE}
|
|
|
+
|
|
|
+// 引用系统属性
|
|
|
+var machine = cfg.GetResolved("Paths:Machine"); // ${SYS:MachineName}
|
|
|
+```
|
|
|
+
|
|
|
+#### 变量语法
|
|
|
+
|
|
|
+| 语法 | 说明 | 示例 |
|
|
|
+|------|------|------|
|
|
|
+| `${Key}` | 引用其他配置键 | `${App:Name}` |
|
|
|
+| `${ENV:Name}` | 引用环境变量 | `${ENV:USERPROFILE}` |
|
|
|
+| `${SYS:Property}` | 引用系统属性 | `${SYS:MachineName}` |
|
|
|
+
|
|
|
+#### 支持的系统属性
|
|
|
+
|
|
|
+| 属性名 | 说明 |
|
|
|
+|--------|------|
|
|
|
+| `MachineName` | 计算机名 |
|
|
|
+| `UserName` | 当前用户名 |
|
|
|
+| `UserDomainName` | 用户域名 |
|
|
|
+| `ProcessId` | 当前进程 ID |
|
|
|
+| `Now` | 当前时间（ISO 8601 格式） |
|
|
|
+| `UtcNow` | 当前 UTC 时间 |
|
|
|
+| `Today` | 当前日期（yyyy-MM-dd） |
|
|
|
+| `ProcessorCount` | 处理器数量 |
|
|
|
+| `CLRVersion` | CLR 版本 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 六、核心库源文件结构
|
|
|
+
|
|
|
+核心库 `Apq.Cfg` 包含以下模块：
|
|
|
+
|
|
|
+```
|
|
|
+Apq.Cfg/
|
|
|
+├── ICfgRoot.cs # 配置根接口
|
|
|
+├── ICfgSection.cs # 配置节接口
|
|
|
+├── MergedCfgRoot.cs # 合并配置根实现
|
|
|
+├── CfgSection.cs # 配置节实现
|
|
|
+├── CfgBuilder.cs # 配置构建器
|
|
|
+├── CfgSourceLevels.cs # 配置源默认层级常量（新增）
|
|
|
+├── CfgRootExtensions.cs # 扩展方法
|
|
|
+├── ServiceCollectionExtensions.cs # DI 扩展
|
|
|
+├── Changes/ # 配置变更
|
|
|
+│ ├── ChangeType.cs
|
|
|
+│ ├── ConfigChange.cs
|
|
|
+│ ├── ConfigChangeEvent.cs
|
|
|
+│ ├── ReloadStrategy.cs
|
|
|
+│ ├── ReloadErrorEvent.cs
|
|
|
+│ └── DynamicReloadOptions.cs
|
|
|
+├── DependencyInjection/ # 依赖注入
|
|
|
+│ ├── ObjectBinder.cs
|
|
|
+│ ├── ApqCfgOptionsMonitor.cs
|
|
|
+│ └── ApqCfgOptionsSnapshot.cs
|
|
|
+├── EncodingSupport/ # 编码支持
|
|
|
+│ ├── EncodingDetector.cs
|
|
|
+│ ├── EncodingDetectionResult.cs
|
|
|
+│ ├── EncodingMapping.cs
|
|
|
+│ └── EncodingOptions.cs
|
|
|
+├── Internal/ # 内部实现
|
|
|
+│ ├── ChangeCoordinator.cs
|
|
|
+│ ├── FastCollections.cs
|
|
|
+│ ├── KeyPathParser.cs
|
|
|
+│ ├── MergedConfigurationProvider.cs
|
|
|
+│ ├── MergedConfigurationSource.cs
|
|
|
+│ ├── ValueCache.cs
|
|
|
+│ ├── ValueConverter.cs
|
|
|
+│ ├── ValueMaskerChain.cs
|
|
|
+│ └── ValueTransformerChain.cs
|
|
|
+├── Security/ # 安全
|
|
|
+│ ├── IValueMasker.cs
|
|
|
+│ ├── IValueTransformer.cs
|
|
|
+│ └── ValueTransformerOptions.cs
|
|
|
+├── Snapshot/ # 快照导出
|
|
|
+│ ├── CfgRootSnapshotExtensions.cs
|
|
|
+│ ├── ConfigExporter.cs
|
|
|
+│ ├── ExportContext.cs
|
|
|
+│ ├── ExportOptions.cs
|
|
|
+│ └── SnapshotExporters.cs
|
|
|
+├── Sources/ # 配置源
|
|
|
+│ ├── ICfgSource.cs
|
|
|
+│ ├── JsonFileCfgSource.cs
|
|
|
+│ ├── Environment/
|
|
|
+│ │ └── EnvVarsCfgSource.cs
|
|
|
+│ └── File/
|
|
|
+│ └── FileCfgSourceBase.cs
|
|
|
+├── Template/ # 模板引擎
|
|
|
+│ ├── CfgBuilderTemplateExtensions.cs
|
|
|
+│ ├── IVariableResolver.cs
|
|
|
+│ ├── TemplateEngine.cs
|
|
|
+│ ├── TemplateExtensions.cs
|
|
|
+│ ├── VariableResolutionOptions.cs
|
|
|
+│ └── VariableResolvers.cs
|
|
|
+└── Validation/ # 配置验证
|
|
|
+ ├── CfgRootValidationExtensions.cs
|
|
|
+ ├── ConfigValidationBuilder.cs
|
|
|
+ ├── ConfigValidationException.cs
|
|
|
+ ├── ConfigValidator.cs
|
|
|
+ ├── IConfigValidator.cs
|
|
|
+ ├── IValidationRule.cs
|
|
|
+ ├── ValidationError.cs
|
|
|
+ ├── ValidationResult.cs
|
|
|
+ └── Rules/
|
|
|
+ ├── CustomRule.cs
|
|
|
+ ├── DependsOnRule.cs
|
|
|
+ ├── EnumValuesRule.cs
|
|
|
+ ├── LengthRule.cs
|
|
|
+ ├── RangeRule.cs
|
|
|
+ ├── RegexRule.cs
|
|
|
+ └── RequiredRule.cs
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 七、版本管理
|
|
|
+
|
|
|
+### 7.1 当前版本
|
|
|
+
|
|
|
+**v1.1.2**（准备中）- 所有 18 个 NuGet 包统一版本
|
|
|
+
|
|
|
+### 7.2 版本历史
|
|
|
+
|
|
|
+| 版本 | 发布日期 | 主要变更 |
|
|
|
+|-----|---------|---------|
|
|
|
+| v1.1.2 | 2026-01 | 默认层级功能，文档更新 |
|
|
|
+| v1.1.1 | 2026-01 | 小修复 |
|
|
|
+| v1.1.0 | 2026-01 | 配置验证、快照导出、模板引擎；移除 .NET 6.0 |
|
|
|
+| v1.0.6 | 2025-12 | 加密脱敏功能，性能优化 |
|
|
|
+| v1.0.4 | 2025-12 | 远程配置中心完善 |
|
|
|
+
|
|
|
+### 7.3 NuGet 包列表
|
|
|
+
|
|
|
+| 包名 | 说明 | 默认层级 |
|
|
|
+|-----|------|----------|
|
|
|
+| Apq.Cfg | 核心库（JSON、环境变量） | Json: 0, Env: 400 |
|
|
|
+| Apq.Cfg.Ini | INI 文件支持 | 0 |
|
|
|
+| Apq.Cfg.Xml | XML 文件支持 | 0 |
|
|
|
+| Apq.Cfg.Yaml | YAML 文件支持 | 0 |
|
|
|
+| Apq.Cfg.Toml | TOML 文件支持 | 0 |
|
|
|
+| Apq.Cfg.Env | .env 文件支持 | 400 |
|
|
|
+| Apq.Cfg.Redis | Redis 配置源 | 100 |
|
|
|
+| Apq.Cfg.Database | 数据库配置源 | 100 |
|
|
|
+| Apq.Cfg.Consul | Consul 配置中心 | 200 |
|
|
|
+| Apq.Cfg.Etcd | Etcd 配置中心 | 200 |
|
|
|
+| Apq.Cfg.Nacos | Nacos 配置中心 | 200 |
|
|
|
+| Apq.Cfg.Apollo | Apollo 配置中心 | 200 |
|
|
|
+| Apq.Cfg.Zookeeper | Zookeeper 配置中心 | 200 |
|
|
|
+| Apq.Cfg.Vault | HashiCorp Vault | 300 |
|
|
|
+| Apq.Cfg.Crypto | 加密脱敏核心 | - |
|
|
|
+| Apq.Cfg.Crypto.DataProtection | ASP.NET Core 集成 | - |
|
|
|
+| Apq.Cfg.Crypto.Tool | 命令行工具 | - |
|
|
|
+| Apq.Cfg.SourceGenerator | 源生成器 | - |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 八、远程配置中心支持
|
|
|
+
|
|
|
+| 配置中心 | 默认层级 | 写入支持 | 数据格式 | 热重载 | 特点 |
|
|
|
+|---------|----------|---------|---------|--------|------|
|
|
|
+| **Consul** | 200 | ✅ | KV/JSON/YAML | ✅ Blocking Query | KV 存储，支持前缀监听 |
|
|
|
+| **Etcd** | 200 | ✅ | KV/JSON | ✅ Watch API | 强一致性，支持前缀监听 |
|
|
|
+| **Nacos** | 200 | ✅ | JSON/YAML/Properties | ✅ IListener | 支持命名空间、分组、多 DataId |
|
|
|
+| **Apollo** | 200 | ❌ | Properties | ✅ 长轮询 + 通知 | 支持多环境、集群、命名空间 |
|
|
|
+| **Zookeeper** | 200 | ✅ | KV/JSON | ✅ Watch API | 节点监听，支持会话管理 |
|
|
|
+| **Vault** | 300 | ✅ | KV (V1/V2) | ✅ 轮询 | 密钥管理，支持 Token/AppRole 认证 |
|
|
|
+| **Redis** | 100 | ✅ | KV/Hash | ✅ Pub/Sub | 高性能缓存，支持集群 |
|
|
|
+| **Database** | 100 | ✅ | 表结构 | ✅ 轮询 | 支持多种数据库（SqlSugar） |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 九、加密脱敏
|
|
|
+
|
|
|
+### 9.1 支持的加密算法
|
|
|
+
|
|
|
+| 加密算法 | 说明 |
|
|
|
+|---------|------|
|
|
|
+| AES-GCM | 推荐，认证加密，支持 128/192/256 位密钥 |
|
|
|
+| AES-CBC | 兼容性好，带 HMAC 完整性校验 |
|
|
|
+| ChaCha20-Poly1305 | 高性能，适合移动端 |
|
|
|
+| SM4 | 国密算法，支持 CBC/ECB 模式 |
|
|
|
+| 3DES | 兼容旧系统，支持 128/192 位密钥 |
|
|
|
+
|
|
|
+### 9.2 脱敏功能
|
|
|
+
|
|
|
+| 功能 | 说明 |
|
|
|
+|------|------|
|
|
|
+| SensitiveMasker | 敏感字段脱敏（密码、密钥等） |
|
|
|
+| EncryptionTransformer | 配置值加解密转换 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十、性能基准
|
|
|
+
|
|
|
+### 10.1 基准测试类
|
|
|
+
|
|
|
+| 测试类 | 说明 |
|
|
|
+|-------|------|
|
|
|
+| ReadWriteBenchmarks | 读写性能测试 |
|
|
|
+| CacheBenchmarks | 缓存效果测试 |
|
|
|
+| TypeConversionBenchmarks | 类型转换测试 |
|
|
|
+| ConcurrencyBenchmarks | 并发访问测试 |
|
|
|
+| BatchOperationBenchmarks | 批量操作测试 |
|
|
|
+| LargeFileBenchmarks | 大文件加载测试 |
|
|
|
+| MultiSourceBenchmarks | 多源合并测试 |
|
|
|
+| KeyPathBenchmarks | 键路径解析测试 |
|
|
|
+| GetSectionBenchmarks | 配置节访问测试 |
|
|
|
+| SaveBenchmarks | 持久化测试 |
|
|
|
+| RemoveBenchmarks | 删除操作测试 |
|
|
|
+| MicrosoftConfigBenchmarks | MS Configuration 转换测试 |
|
|
|
+| EncodingBenchmarks | 编码检测测试 |
|
|
|
+| ObjectBinderBenchmarks | 对象绑定测试 |
|
|
|
+| SourceGeneratorBenchmarks | 源生成器测试 |
|
|
|
+| DependencyInjectionBenchmarks | DI 集成测试 |
|
|
|
+| CryptoBenchmarks | 加密脱敏测试 |
|
|
|
+| ConsulBenchmarks | Consul 性能测试 |
|
|
|
+| EtcdBenchmarks | Etcd 性能测试 |
|
|
|
+
|
|
|
+### 10.2 运行时性能对比
|
|
|
+
|
|
|
+| 运行时 | 相对性能 | 建议 |
|
|
|
+|--------|----------|------|
|
|
|
+| .NET 8.0 | 基准 | 生产可用 |
|
|
|
+| .NET 10.0 | +10-15% | 最佳性能 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十一、改进建议
|
|
|
+
|
|
|
+### 11.1 已完成的改进
|
|
|
+
|
|
|
+- [x] 配置验证功能（30 个测试）
|
|
|
+- [x] 配置快照导出（17 个测试）
|
|
|
+- [x] 配置模板与变量替换（21 个测试）
|
|
|
+- [x] 迁移指南文档（中英文）
|
|
|
+- [x] 最佳实践指南更新
|
|
|
+- [x] 移除 .NET 6.0 支持
|
|
|
+- [x] **默认层级功能**（CfgSourceLevels）
|
|
|
+- [x] **文档站点更新**（中英文 config-sources、examples 目录）
|
|
|
+
|
|
|
+### 11.2 待修复问题
|
|
|
+
|
|
|
+无已知问题。所有 505 个测试在 .NET 8.0 和 .NET 10.0 上均通过。
|
|
|
+
|
|
|
+### 11.3 未来优化方向
|
|
|
+
|
|
|
+| 优化项 | 说明 | 优先级 |
|
|
|
+|--------|------|--------|
|
|
|
+| **内存池化** | `MergedCfgRoot` 中使用 `ArrayPool<T>` | 中 |
|
|
|
+| **Span<T> 优化** | 键路径解析使用 `ReadOnlySpan<char>` | 中 |
|
|
|
+| **ValueTask 替代** | 热路径方法返回 `ValueTask` | 低 |
|
|
|
+| **分布式锁** | 远程配置源写入时的分布式锁 | 低 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十二、总结
|
|
|
+
|
|
|
+Apq.Cfg 是一个功能完善、设计精良的 .NET 统一配置管理库：
|
|
|
+
|
|
|
+1. **全面的配置源支持**：7 种文件格式 + 8 种远程配置中心
|
|
|
+2. **智能的默认层级**：无需手动指定层级，开箱即用
|
|
|
+3. **强大的加密脱敏**：5 种加密算法 + 敏感字段脱敏
|
|
|
+4. **完整的测试覆盖**：505 个单元测试，100% API 覆盖
|
|
|
+5. **丰富的高级功能**：配置验证、快照导出、模板引擎
|
|
|
+6. **现代化的框架支持**：.NET 8/10 LTS + Native AOT
|
|
|
+7. **差异化功能**：配置模板是 `Microsoft.Extensions.Configuration` 不支持的功能
|
|
|
+
|
|
|
+项目已准备好用于生产环境，建议使用 .NET 10.0 以获得最佳性能。
|
