Air.Cloud

# Nacos

Air.Cloud.Modules.Nacos 是 Air.Cloud 对 Nacos 的服务治理模块实现，提供服务注册发现、配置中心键值操作和远程配置加载能力。

# 配置加载摘要

WebInjectInNacos() 与 HostInjectInNacos() 在挂载远程配置后，都会通过 AppRealization.Output.Print 输出一条不含配置值的摘要。摘要包含 Nacos 服务端地址、dataId、group、namespace 和有效配置项数量；启用公共配置时，服务和公共 dataId 会汇总在同一条摘要中，避免重复统计。

示例：

配置加载 | 加载到配置: 来源:Nacos; 地址:http://127.0.0.1:8848/; 配置定位:dataId=order.json, common.json; group=DEFAULT_GROUP; namespace=public; 有效配置项:18个

配置值、连接字符串、密码、Token 均不会写入该日志。由于监听项为可选项，有效配置项:0个 表示本次读取未发现有值的键，不应视为已成功取得业务配置。

# 所属 Standard

Standard 模块实现 说明
IServerCenterStandard NacosServerCenterDependency 基于 Nacos Naming 的服务注册、服务列表查询和实例详情查询
IKVCenterStandard NacosKVCenterDependency 基于 Nacos Config 的配置读写删除能力

提示

Nacos Config 没有与 Consul KV 完全一致的目录前缀枚举语义。模块把 IKVCenterStandard.Key 映射为 Nacos dataId，把 Value 映射为配置内容；QueryAsync(prefix) 会把传入值当作具体 dataId 查询。

# 包名

Air.Cloud.Modules.Nacos

# 配置节点

配置节点名称为：

NacosServiceOptions
配置项 说明 默认值
ServerAddresses Nacos 服务端地址列表 空
ServerAddress Nacos 单节点地址，会并入 ServerAddresses 空
Namespace Nacos 命名空间 空，使用 public
ContextPath Nacos 上下文路径 nacos
UserName / Password Nacos 鉴权账号和密码 空
ConfigGroup 配置中心默认分组 DEFAULT_GROUP
ServiceGroup 服务发现默认分组 DEFAULT_GROUP
ConfigTimeoutMs 配置读取超时，单位毫秒 5000
ServiceName 当前服务名称 空
ServiceAddress 当前服务地址 空
ClusterName 实例集群名称 DEFAULT
Weight 实例权重 1
Ephemeral 是否临时实例 true
ConfigDataId 服务配置 dataId appsettings.{Environment}.json
EnableCommonConfig 是否加载公共配置 true
CommonConfigDataId 公共配置 dataId appsettings.Common.{Environment}.json

# 配置示例

{
  "Environment": "Production",
  "NacosServiceOptions": {
    "ServerAddress": "http://127.0.0.1:8848/",
    "Namespace": "",
    "ConfigGroup": "DEFAULT_GROUP",
    "ServiceGroup": "DEFAULT_GROUP",
    "ServiceName": "order-service",
    "ServiceAddress": "http://127.0.0.1:5295",
    "ConfigDataId": "order-service.json",
    "EnableCommonConfig": true,
    "CommonConfigDataId": "common.json"
  }
}

# 注册模块

在普通依赖注入场景中直接注册模块：

using Air.Cloud.Modules.Nacos.Extensions;

builder.Services.AddNacosModule(builder.Configuration);

注册后可通过 Air.Cloud 标准接口使用：

public class DemoService
{
    private readonly IServerCenterStandard _serverCenter;
    private readonly IKVCenterStandard _kvCenter;

    public DemoService(IServerCenterStandard serverCenter, IKVCenterStandard kvCenter)
    {
        _serverCenter = serverCenter;
        _kvCenter = kvCenter;
    }
}

# 服务注册

await _serverCenter.RegisterAsync(new NacosServerCenterServiceRegisterOptions
{
    ServiceName = "order-service",
    ServiceKey = "order-service-1",
    ServiceAddress = "http://127.0.0.1:5295",
    GroupName = "DEFAULT_GROUP",
    ClusterName = "DEFAULT",
    HealthCheckRoute = "/health"
});

查询服务：

var services = await _serverCenter.QueryAsync<NacosServerCenterServiceOptions>();
var detail = await _serverCenter.GetAsync("order-service");

# 配置中心

写入配置：

await _kvCenter.AddOrUpdateAsync("order-service.json", "{\"Feature\":{\"Flag\":\"on\"}}");

读取配置：

var item = await _kvCenter.GetAsync<NacosKvCenterServiceInformation>("order-service.json");

删除配置：

await _kvCenter.DeleteAsync("order-service.json");

# 远程配置加载

Web 应用可以使用：

using Air.Cloud.Modules.Nacos.Extensions;

var builder = WebApplication.CreateBuilder(args);
var app = builder.WebInjectInNacos();
app.Run();

通用主机可以使用：

builder.Host.HostInjectInNacos();

远程配置加载使用 ConfigDataId 和 CommonConfigDataId 两个 dataId，默认开启变更监听。需要和 Nacos 服务端中实际发布的配置 dataId、group 保持一致。

# 测试

单元测试：

dotnet test test/Air.Cloud.UnitTest/Air.Cloud.UnitTest.csproj --filter "FullyQualifiedName~Modules.Nacos" -m:1

集成测试默认关闭真实 Nacos 访问。需要验证真实 Nacos 时，在 test/Air.Cloud.IntegrationTest/appsettings.json 中配置：

{
  "NacosIntegration": {
    "RunNacosTests": true,
    "Address": "http://127.0.0.1:8848/",
    "ConfigGroup": "DEFAULT_GROUP",
    "ServiceGroup": "DEFAULT_GROUP",
    "KeyPrefix": "air-cloud-it"
  }
}

然后运行：

dotnet test test/Air.Cloud.IntegrationTest/Air.Cloud.IntegrationTest.csproj --filter "FullyQualifiedName~Modules.Nacos" -m:1

# HealthCheckRoute 与日志过滤

NacosServiceOptions 支持配置 HealthCheckRoute：

{
  "NacosServiceOptions": {
    "ServerAddress": "http://127.0.0.1:8848/",
    "ServiceName": "order-service",
    "ServiceAddress": "http://127.0.0.1:5295",
    "HealthCheckRoute": "/health"
  }
}

服务注册时，如果 NacosServerCenterServiceRegisterOptions.HealthCheckRoute 为空，模块会使用 NacosServiceOptions.HealthCheckRoute。如果注册参数中传入了 HealthCheckRoute，以注册参数为准。

AddNacosModule() 会把 NacosServiceOptions.HealthCheckRoute 写入 Air.Cloud 日志过滤插件的忽略列表。服务注册时传入的健康检查路由也会在规范化后写入忽略列表。

默认只过滤 Information 及以下级别，并保留 Warning、Error、Critical。默认分类范围包括 ASP.NET Core 的请求开始/结束日志和 ResponseCaching 中间件日志，业务 logger 不会因为当前请求路径命中健康检查地址而被过滤。

← RedisCache →