RedNb.Nacos.Http 1.0.3

<div align="center">

RedNb.Nacos

A Modern .NET SDK for Nacos

English | 简体中文

</div>

RedNb.Nacos 是一个功能完整的现代化 .NET Nacos 客户端 SDK，完全兼容 Nacos 2.x/3.x，提供 200+ 个 API 方法，涵盖配置中心、服务发现、分布式锁、AI 服务（MCP/A2A）和运维管理等全部功能。

🎯 为什么选择 RedNb.Nacos？

• 🆕 支持 .NET 8.0 和 .NET 10.0，采用最新语言特性
• ✅ API 完整度最高 - 200+ 个 API，覆盖 Nacos 全部功能
• 🔄 完整支持 Nacos 3.x 新功能（Fuzzy Watch、AI Service、分布式锁）
• 🛠️ 独有 维护服务 API - 命名空间、集群、客户端连接管理
• 📦 模块化设计，按需引用，减少依赖

✨ 特性

📦 NuGet 包

包名	描述	NuGet
RedNb.Nacos	核心抽象层：接口、模型和常量定义
RedNb.Nacos.Http	HTTP 客户端实现
RedNb.Nacos.Grpc	gRPC 高性能客户端实现
RedNb.Nacos.DependencyInjection	依赖注入扩展
RedNb.Nacos.AspNetCore	ASP.NET Core 集成
RedNb.Nacos.All	全功能包（包含以上所有）

🚀 快速开始

安装

# 基础包（推荐）
dotnet add package RedNb.Nacos.Http

# 或全功能包
dotnet add package RedNb.Nacos.All

# ASP.NET Core 集成
dotnet add package RedNb.Nacos.AspNetCore

基础用法

1. 直接使用工厂创建服务

using RedNb.Nacos;
using RedNb.Nacos.Http;

// 配置选项
var options = new NacosClientOptions
{
    ServerAddresses = "localhost:8848",
    Username = "nacos",
    Password = "nacos",
    Namespace = "",
    DefaultTimeout = 5000
};

// 创建服务工厂
var factory = new NacosHttpFactory();

// 获取各种服务
var configService = factory.CreateConfigService(options);
var namingService = factory.CreateNamingService(options);
var lockService = factory.CreateLockService(options);
var aiService = factory.CreateAiService(options);
var maintainerService = factory.CreateMaintainerService(options);

2. 配置中心

// 获取配置
var content = await configService.GetConfigAsync("app-config", "DEFAULT_GROUP", 5000);

// 发布配置
await configService.PublishConfigAsync("app-config", "DEFAULT_GROUP", jsonContent, ConfigType.Json);

// CAS 乐观锁发布
await configService.PublishConfigCasAsync("app-config", "DEFAULT_GROUP", content, "oldMd5");

// 监听配置变更
await configService.AddListenerAsync("app-config", "DEFAULT_GROUP", new MyConfigListener());

// 模糊监听（Nacos 3.0）- 监听所有以 "app-" 开头的配置
await configService.FuzzyWatchAsync("app-*", "DEFAULT_GROUP", myWatcher);

3. 服务发现

// 注册实例
var instance = new Instance
{
    Ip = "192.168.1.100",
    Port = 8080,
    Weight = 1.0,
    Healthy = true,
    Ephemeral = true,
    Metadata = new Dictionary<string, string>
    {
        { "version", "1.0.0" }
    }
};
await namingService.RegisterInstanceAsync("my-service", instance);

// 批量注册
await namingService.BatchRegisterInstanceAsync("my-service", "DEFAULT_GROUP", instances);

// 获取所有实例
var instances = await namingService.GetAllInstancesAsync("my-service");

// 选择一个健康实例（加权随机）
var selected = await namingService.SelectOneHealthyInstanceAsync("my-service");

// 订阅服务变更
await namingService.SubscribeAsync("my-service", evt =>
{
    Console.WriteLine($"Service changed: {evt.Instances?.Count} instances");
});

// 模糊监听（Nacos 3.0）
await namingService.FuzzyWatchAsync("*", "production-group", myServiceWatcher);

// 注销实例
await namingService.DeregisterInstanceAsync("my-service", instance);

4. 分布式锁 (Nacos 3.0)

// 创建锁实例
var lockInstance = LockInstance.Create("my-lock-key")
    .WithExpireTime(TimeSpan.FromSeconds(30))
    .WithOwner("client-1")
    .WithReentrant();

// 获取锁
var acquired = await lockService.LockAsync(lockInstance);
if (acquired)
{
    try
    {
        // 执行临界区代码
        await DoSomethingCritical();
    }
    finally
    {
        // 释放锁
        await lockService.UnlockAsync(lockInstance);
    }
}

// 或使用 TryLock 带超时
var success = await lockService.TryLockAsync(lockInstance, TimeSpan.FromSeconds(10));

5. AI 服务 - MCP/A2A (Nacos 3.0)

// === MCP 服务 ===
// 发布 MCP 服务器
await aiService.ReleaseMcpServerAsync("my-mcp-server", mcpServerSpec);

// 注册 MCP 端点
await aiService.RegisterMcpServerEndpointAsync("my-mcp-server", "1.0.0", endpoint);

// 获取 MCP 服务器详情
var mcpServer = await aiService.GetMcpServerAsync("my-mcp-server");

// 订阅 MCP 服务器变更
await aiService.SubscribeMcpServerAsync("my-mcp-server", myMcpListener);

// === A2A 服务 ===
// 发布 Agent Card
await aiService.ReleaseAgentCardAsync("my-agent", agentCard);

// 注册 Agent 端点
await aiService.RegisterAgentEndpointAsync("my-agent", endpoint, TransportProtocol.Http);

// 获取 Agent Card 详情
var agentCard = await aiService.GetAgentCardAsync("my-agent");

// 列出所有 Agents
var agents = await aiService.ListAgentCardsAsync(1, 20);

6. 维护服务

// === 命名空间管理 ===
var namespaces = await maintainerService.GetNamespacesAsync();
await maintainerService.CreateNamespaceAsync("new-ns", "New Namespace");
await maintainerService.UpdateNamespaceAsync("ns-id", "Updated Name", "Description");
await maintainerService.DeleteNamespaceAsync("ns-id");

// === 服务管理 ===
await maintainerService.CreateServiceAsync("my-service", "DEFAULT_GROUP", 0.5f, true, "metadata");
var services = await maintainerService.ListServicesAsync(1, 10, "DEFAULT_GROUP");
var serviceDetail = await maintainerService.GetServiceAsync("my-service", "DEFAULT_GROUP");
await maintainerService.DeleteServiceAsync("my-service", "DEFAULT_GROUP");

// === 实例管理 ===
await maintainerService.UpdateInstanceAsync("my-service", instance);
await maintainerService.UpdateInstanceHealthAsync("my-service", "192.168.1.100", 8080, true);
await maintainerService.BatchUpdateMetadataAsync("my-service", instances, metadata);

// === 配置管理 ===
await maintainerService.PublishConfigAsync("app-config", "DEFAULT_GROUP", content, ConfigType.Yaml);
var configs = await maintainerService.ListConfigsAsync(1, 10, "app", "DEFAULT_GROUP");
var history = await maintainerService.ListConfigHistoryAsync("app-config", "DEFAULT_GROUP", 1, 20);
await maintainerService.DeleteConfigsAsync(new[] { configId1, configId2 });

// === Beta/灰度配置 ===
await maintainerService.PublishBetaConfigAsync("app-config", "DEFAULT_GROUP", content, "192.168.1.*");
await maintainerService.StopBetaConfigAsync("app-config", "DEFAULT_GROUP");

// === 配置导入导出 ===
var exportData = await maintainerService.ExportConfigsAsync(new[] { configId1, configId2 });
await maintainerService.ImportConfigsAsync("DEFAULT_GROUP", policy, configData);
await maintainerService.CloneConfigsAsync(configIds, targetNamespaceId, policy);

// === 客户端连接管理 ===
var clients = await maintainerService.ListClientsAsync();
var clientDetail = await maintainerService.GetClientDetailAsync(clientId);
var subscriptions = await maintainerService.GetClientSubscribedServicesAsync(clientId);
var sdkStats = await maintainerService.GetSdkVersionStatisticsAsync();

// === 集群管理 ===
var members = await maintainerService.GetClusterMembersAsync();
var leader = await maintainerService.GetLeaderAsync();
var health = await maintainerService.HealthCheckAsync();
var metrics = await maintainerService.GetMetricsAsync();

ASP.NET Core 集成

1. 添加 Nacos 配置源

var builder = WebApplication.CreateBuilder(args);

// 添加 Nacos 作为配置源
builder.Configuration.AddNacosConfiguration(source =>
{
    source.Options.ServerAddresses = "localhost:8848";
    source.Options.Username = "nacos";
    source.Options.Password = "nacos";
    source.ConfigItems.Add(new NacosConfigurationItem 
    { 
        DataId = "app-config", 
        Group = "DEFAULT_GROUP",
        ConfigType = ConfigType.Json
    });
    source.ConfigItems.Add(new NacosConfigurationItem 
    { 
        DataId = "db-config", 
        Group = "DEFAULT_GROUP",
        Optional = true  // 可选配置
    });
});

2. 依赖注入

// 注册 Nacos 服务
builder.Services.AddNacos(options =>
{
    options.ServerAddresses = "localhost:8848";
    options.Username = "nacos";
    options.Password = "nacos";
});

// 或只注册配置服务
builder.Services.AddNacosConfigService(options => { ... });

// 或只注册命名服务
builder.Services.AddNacosNamingService(options => { ... });

// 添加健康检查
builder.Services.AddHealthChecks()
    .AddNacos();

3. 服务自动注册

var app = builder.Build();

// 自动注册当前服务到 Nacos，应用关闭时自动注销
app.UseNacosServiceRegistry(
    serviceName: "my-webapi",
    port: 5000,
    metadata: new Dictionary<string, string>
    {
        { "version", "1.0.0" },
        { "env", app.Environment.EnvironmentName }
    });

app.MapHealthChecks("/health");
app.Run();

4. 控制器中使用

[ApiController]
[Route("[controller]")]
public class DemoController : ControllerBase
{
    private readonly IConfigService _configService;
    private readonly INamingService _namingService;
    private readonly ILockService _lockService;

    public DemoController(
        IConfigService configService, 
        INamingService namingService,
        ILockService lockService)
    {
        _configService = configService;
        _namingService = namingService;
        _lockService = lockService;
    }

    [HttpGet("config")]
    public async Task<string?> GetConfig()
    {
        return await _configService.GetConfigAsync("app-config", "DEFAULT_GROUP", 5000);
    }

    [HttpGet("instances")]
    public async Task<List<Instance>> GetInstances(string serviceName)
    {
        return await _namingService.GetAllInstancesAsync(serviceName);
    }

    [HttpPost("lock")]
    public async Task<bool> AcquireLock(string key)
    {
        var lockInstance = LockInstance.Create(key).WithExpireTime(TimeSpan.FromSeconds(30));
        return await _lockService.LockAsync(lockInstance);
    }
}

🧩 功能模块详解

📁 配置中心 (IConfigService)

🌐 服务发现 (INamingService)

🔒 分布式锁 (ILockService)

LockInstance 流式 API：

var lock = LockInstance.Create("my-key")
    .WithExpireTime(TimeSpan.FromSeconds(30))  // 过期时间
    .WithLockType("distributed")               // 锁类型
    .WithNamespace("prod-namespace")           // 命名空间
    .WithOwner("service-A")                    // 所有者
    .WithParam("priority", "high")             // 自定义参数
    .WithReentrant();                          // 可重入

🤖 AI 服务 (IAiService) - Nacos 3.0

MCP 服务 (Model Context Protocol)

A2A 服务 (Agent-to-Agent)

🛠️ 维护服务 (IMaintainerService)

命名空间管理 (ICoreMaintainer)

服务管理 (IServiceMaintainer)

实例管理 (IInstanceMaintainer)

配置管理 (IConfigMaintainer)

配置历史 (IConfigHistoryMaintainer)

Beta/灰度配置 (IBetaConfigMaintainer)

配置导入导出 (IConfigOpsMaintainer)

客户端管理 (IClientMaintainer)

集群管理 (ICoreMaintainer)

📁 项目结构

RedNb.Nacos/
├── src/
│   ├── RedNb.Nacos/                     # 核心抽象层
│   │   ├── Config/                      # 配置中心接口和模型
│   │   ├── Naming/                      # 服务发现接口和模型
│   │   ├── Lock/                        # 分布式锁接口和模型
│   │   ├── Ai/                          # AI 服务接口 (MCP/A2A)
│   │   ├── Maintainer/                  # 维护服务接口
│   │   ├── Ability/                     # 能力接口
│   │   ├── Failover/                    # 故障转移
│   │   ├── Constants/                   # 常量定义
│   │   ├── Exceptions/                  # 异常类型
│   │   └── Utils/                       # 工具类
│   ├── RedNb.Nacos.Http/                # HTTP 客户端实现
│   │   ├── Config/                      # 配置服务实现
│   │   ├── Naming/                      # 命名服务实现
│   │   ├── Lock/                        # 锁服务实现
│   │   ├── Ai/                          # AI 服务实现
│   │   ├── Maintainer/                  # 维护服务实现
│   │   └── Http/                        # HTTP 客户端基础设施
│   ├── RedNb.Nacos.Grpc/                # gRPC 客户端实现
│   │   ├── Config/                      # gRPC 配置服务
│   │   ├── Naming/                      # gRPC 命名服务
│   │   ├── Lock/                        # gRPC 锁服务
│   │   └── Protos/                      # Protocol Buffer 定义
│   ├── RedNb.Nacos.DependencyInjection/ # DI 扩展
│   ├── RedNb.Nacos.AspNetCore/          # ASP.NET Core 集成
│   │   ├── Configuration/               # 配置提供程序
│   │   ├── HealthChecks/                # 健康检查
│   │   └── ServiceRegistry/             # 服务自动注册
│   └── RedNb.Nacos.All/                 # 全功能聚合包
├── samples/
│   ├── RedNb.Nacos.Sample.Console/      # 控制台示例
│   └── RedNb.Nacos.Sample.WebApi/       # WebAPI 示例
├── tests/
│   ├── RedNb.Nacos.Tests/               # 单元测试
│   ├── RedNb.Nacos.Http.Tests/          # HTTP 客户端测试
│   └── RedNb.Nacos.IntegrationTests/    # 集成测试
└── deploy/
    └── docker-compose/                  # Docker 部署配置

⚙️ 配置选项

public class NacosClientOptions
{
    // ====== 服务器连接 ======
    /// <summary>服务器地址，多个用逗号分隔</summary>
    public string ServerAddresses { get; set; } = "localhost:8848";
    
    /// <summary>命名空间 ID</summary>
    public string? Namespace { get; set; }
    
    /// <summary>上下文路径</summary>
    public string ContextPath { get; set; } = "nacos";
    
    /// <summary>集群名称</summary>
    public string ClusterName { get; set; } = "DEFAULT";
    
    /// <summary>地址服务器端点</summary>
    public string? Endpoint { get; set; }
    
    // ====== 认证配置 ======
    /// <summary>用户名</summary>
    public string? Username { get; set; }
    
    /// <summary>密码</summary>
    public string? Password { get; set; }
    
    /// <summary>访问密钥</summary>
    public string? AccessKey { get; set; }
    
    /// <summary>秘密密钥</summary>
    public string? SecretKey { get; set; }
    
    // ====== 超时设置 ======
    /// <summary>默认超时时间（毫秒），默认 5000</summary>
    public int DefaultTimeout { get; set; } = 5000;
    
    /// <summary>长轮询超时时间（毫秒），默认 30000</summary>
    public int LongPollTimeout { get; set; } = 30000;
    
    /// <summary>重试次数，默认 3</summary>
    public int RetryCount { get; set; } = 3;
    
    // ====== 功能开关 ======
    /// <summary>启用 gRPC，默认 true</summary>
    public bool EnableGrpc { get; set; } = true;
    
    /// <summary>gRPC 端口偏移，默认 1000</summary>
    public int GrpcPortOffset { get; set; } = 1000;
    
    /// <summary>启用日志，默认 true</summary>
    public bool EnableLogging { get; set; } = true;
    
    /// <summary>启动时加载缓存</summary>
    public bool NamingLoadCacheAtStart { get; set; }
    
    /// <summary>空推送保护</summary>
    public bool NamingPushEmptyProtection { get; set; }
    
    // ====== TLS 设置 ======
    /// <summary>启用 TLS</summary>
    public bool EnableTls { get; set; }
    
    /// <summary>TLS 证书路径</summary>
    public string? TlsCertPath { get; set; }
    
    /// <summary>TLS 密钥路径</summary>
    public string? TlsKeyPath { get; set; }
    
    /// <summary>TLS CA 证书路径</summary>
    public string? TlsCaPath { get; set; }
    
    // ====== 其他 ======
    /// <summary>应用名称</summary>
    public string? AppName { get; set; }
}

🔧 高级特性

配置监听器

public class MyConfigListener : IConfigChangeListener
{
    public void OnReceiveConfigInfo(ConfigInfo configInfo)
    {
        Console.WriteLine($"Config changed: {configInfo.DataId}");
        Console.WriteLine($"New content: {configInfo.Content}");
        Console.WriteLine($"MD5: {configInfo.Md5}");
    }
}

配置过滤器

public class EncryptionFilter : IConfigFilter
{
    public string Name => "EncryptionFilter";
    public int Order => 1;

    public void DoFilter(IConfigRequest? request, IConfigResponse? response, IConfigFilterChain chain)
    {
        // 解密响应内容
        if (response?.Content != null)
        {
            response.Content = Decrypt(response.Content);
        }
        chain.DoFilter(request, response);
    }
}

// 注册过滤器
configService.AddConfigFilter(new EncryptionFilter());

模糊监听 (Fuzzy Watch) - Nacos 3.0

// 监听所有以 "app-" 开头的配置
await configService.FuzzyWatchAsync("app-*", "DEFAULT_GROUP", new MyFuzzyWatcher());

// 监听某个组下的所有服务
await namingService.FuzzyWatchAsync("*", "production-group", myServiceWatcher);

// 取消模糊监听
await configService.CancelFuzzyWatchAsync("app-*", "DEFAULT_GROUP", myWatcher);

📊 功能统计

🔗 兼容性

🗺️ 路线图

• 配置中心 (Config Service)
• 服务发现 (Naming Service)
• 模糊监听 (Fuzzy Watch) - Nacos 3.0
• AI 服务 - MCP/A2A (Nacos 3.0)
• 分布式锁 (Lock Service) - Nacos 3.0
• 维护服务 (Maintainer Service)
• ASP.NET Core 集成
• 依赖注入支持
• 健康检查
• 服务自动注册
• HTTP 客户端实现
• gRPC 客户端实现
• 安全认证 (Security Proxy)
• Prometheus 指标监控

📄 许可证

本项目采用 Apache License 2.0 许可证开源。

Copyright 2024-2026 RedNb

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

🤝 贡献指南

我们欢迎任何形式的贡献！请阅读以下指南：

如何贡献

1. Fork 本仓库
2. 创建 功能分支 (git checkout -b feature/AmazingFeature)
3. 提交 更改 (git commit -m 'Add some AmazingFeature')
4. 推送 到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

贡献类型

• 🐛 Bug 修复
• ✨ 新功能
• 📝 文档改进
• 🧪 测试用例
• 🎨 代码优化

代码规范

• 遵循 C# 编码约定
• 所有公共 API 必须有 XML 文档注释
• 提交信息遵循 Conventional Commits

🙏 致谢

• Nacos - 阿里巴巴开源的动态服务发现、配置管理和服务管理平台
• nacos-sdk-csharp - 官方 C# SDK 参考

⭐ Star History

如果这个项目对你有帮助，请给我们一个 ⭐ Star！

📞 联系方式

• 📧 Email: 442962355@qq.com
• 💬 Issues: GitHub Issues
• 📖 Discussions: GitHub Discussions

<div align="center">

如果觉得有用，请给个 ⭐ Star 支持一下！

Made with ❤️ by RedNb

</div>