CodeSpirit 配置中心 SDK 自动集成说明

概述

从统一启动框架开始，所有使用 builder.AddCodeSpiritApi<T>() 的服务都会自动集成配置中心 SDK，无需手动调用 AddCodeSpiritConfigCenter()。

架构特点：

• • ✅ 零配置：自动集成，无需手动调用
• • ✅ 轻量级：仅依赖 HTTP，无需 Redis、RabbitMQ 客户端
• • ✅ 实时推送：基于 SSE 的配置变更通知
• • ✅ 智能回退：SSE 不可用时自动切换轻量级轮询
• • ✅ 自动降级：API 不可用时使用本地配置

最后更新： 2026-01-08 v2.1（新增轮询回退机制）

集成方式

自动集成

位置： Src/CodeSpirit.Shared/Startup/ApiStartupExtensions.cs

实现方式： 通过反射动态加载配置中心 SDK，避免循环依赖

// Program.cs - 无需修改
var builder = WebApplication.CreateBuilder(args);

// 自动集成配置中心 SDK
builder.AddCodeSpiritApi<IdentityApiConfiguration>();

var app = builder.Build();

工作流程

配置加载时机

时机保证

• • ✅ 在 WebApplication.Build() 之前：配置源在构建器阶段添加
• • ✅ 在服务注册之前：配置加载在 AddCodeSpiritApi 方法早期执行
• • ✅ 在 IConfiguration 使用之前：配置提供程序的 Load() 方法在配置构建时自动调用

验证方式

方法一：控制台日志

启动应用时查看控制台输出：

[ConfigCenter SDK] 已自动集成到服务: identity

方法二：断点调试

在 ConfigCenterConfigurationProvider.Load() 方法设置断点，验证：

1. 1. 是否被调用
2. 2. 调用时机是否在应用启动之前
3. 3. 配置是否成功加载到 Data 字典

方法三：使用配置值

在服务的 ConfigureServices 方法中读取配置中心的配置：

public override void ConfigureServices(IServiceCollection services, IConfiguration configuration)
{
    var customValue = configuration["YourConfigKey"];
    Console.WriteLine($"[配置中心] 读取配置: YourConfigKey = {customValue}");
    
    // ... 其他配置
}

自动排除逻辑

配置中心服务本身

配置中心服务（ServiceName = "config"）会自动跳过 SDK 集成：

if (serviceName.Equals("config", StringComparison.OrdinalIgnoreCase))
{
    Console.WriteLine($"[ConfigCenter SDK] 跳过配置中心服务自身: {serviceName}");
    return;
}

SDK 未安装的服务

如果某个服务的项目没有引用 CodeSpirit.ConfigCenter.Sdk，会自动跳过：

catch (FileNotFoundException)
{
    // 配置中心 SDK 未加载，忽略
}

配置优先级

配置源顺序

1. 1. 命令行参数 (最高优先级)
2. 2. 环境变量
3. 3. appsettings.{Environment}.json
4. 4. appsettings.json
5. 5. 配置中心 (通过 SDK 加载)

配置覆盖规则

• • 本地配置（appsettings）会覆盖配置中心的配置
• • 如需配置中心优先，调整配置源添加顺序
• • 或在配置中心中使用更高优先级的键名

配置变更通知机制

双模式架构

SDK 支持两种配置变更通知模式，自动选择最优方案：

1. SSE 实时推送（优先模式）

SDK 在后台自动维护与配置中心的 SSE 连接：

特点：

• • ✅ 秒级推送：配置变更后立即推送到所有客户端
• • ✅ 自动重连：连接断开后自动重新建立
• • ✅ 无需轮询：基于服务端推送，资源消耗低
• • ✅ 分布式同步：多实例环境下所有客户端同步更新

2. 轻量级轮询（智能回退）

当 SSE 不可用时（如 Aspire 代理缓冲），自动切换到轻量级轮询：

特点：

• • ✅ 自动降级：SSE 失败 3 次后自动切换
• • ✅ 轻量级：仅传输版本号（~50字节），不是完整配置
• • ✅ 按需拉取：仅当版本变化时才获取完整配置
• • ✅ 可配置：支持自定义轮询间隔

配置选项：

{
  "ConfigCenter": {
    "UsePollingMode": false,
    "PollingIntervalSeconds": 30,
    "SseFailureThresholdBeforePolling": 3
  }
}

故障处理与恢复

配置中心不可用

降级策略：

• • ✅ 不影响启动：API 不可用时使用本地配置
• • ✅ 自动重试：SSE 连接断开后自动重连
• • ✅ 日志记录：控制台输出集成和连接状态

日志示例：

[ConfigCenter SDK] 已自动集成到服务: identity
[ConfigCenter SDK] 配置加载完成，版本: 123
[SSE Listener] SSE 连接已建立
[SSE Listener] SSE 连接断开，5秒后重试...

服务恢复

• • API 恢复：下次 SSE 重连时自动获取最新配置
• • 配置变更：通过 SSE 实时推送，无需等待
• • 零干预：无需手动重启应用或清理缓存

手动集成（可选）

如需更精细的控制，可在统一启动框架之前手动集成：

var builder = WebApplication.CreateBuilder(args);

// 手动集成（可配置选项）
builder.AddCodeSpiritConfigCenter(options =>
{
    options.AppId = "custom-app-id";
    options.CacheExpirationMinutes = 60;
});

// 统一启动框架会检测到已集成，跳过自动集成
builder.AddCodeSpiritApi<MyApiConfiguration>();

注意事项

✅ 优势

• • 自动集成，零配置
• • 轻量级，无外部依赖（SDK 侧）
• • 实时推送，秒级更新（SSE 模式）
• • 智能回退，轮询兜底（Aspire 适配）
• • 轮询优化，网络开销低（仅传输版本号）
• • 自动降级，容错性强
• • 配置中心服务自动排除
• • SDK 未安装的服务自动跳过

⚠️ 注意

• • 首次启动时需从 API 获取配置（约 100-500ms）
• • SSE 长连接需防火墙支持（轮询模式无此限制）
• • Aspire 环境建议直接启用轮询模式（UsePollingMode=true）
• • 轮询模式下配置更新有延迟（默认 30 秒，可配置）
• • 如需配置中心优先于本地配置，需调整配置源顺序
• • 多实例环境需配置 EventBus（服务端）

📊 性能特点

轮询模式效率对比：

相关文档

• • 配置中心重构方案 v4
• • 统一启动框架规范
• • CodeSpirit.ConfigCenter.Sdk 使用指南

更新日志

• • 2026-01-08 v2.1: 新增轮询回退机制
  • • 新增轻量级版本检查 API（GET /config/{appId}/version）
  • • SDK 支持 SSE 失败自动降级到轮询模式
  • • 轮询优化：仅传输版本号，按需拉取完整配置
  • • 添加轮询相关配置选项（UsePollingMode、PollingIntervalSeconds 等）
  • • 适配 Aspire 环境（服务发现代理缓冲 SSE）
• • 2026-01-08 v2.0: 架构优化 - 采用 SSE 实时推送方案
  • • SDK 依赖简化：仅需 HTTP 客户端
  • • 配置推送：从 MQ 改为 SSE
  • • 健康检查：基于 SSE 连接状态
  • • 缓存策略：从 Redis 改为内存缓存
• • 2026-01-07: 在统一启动框架中实现自动集成，采用反射方式避免循环依赖
• 测试账号的链接及密码获取方式如下： 请在 “CodeSpirit - 码灵” 公众号对话框中发送关键词 “体验账号” ，系统将自动为您推送相关信息。