Nacos Naming 顶层规范解读服务发现领域的定位、资源模型与一致性架构【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosNacos Naming 是 Nacos 中负责服务发现的一级领域管理服务、集群、实例及其元数据、健康状态与订阅关系。本文基于 Naming 规范 展开系统讲解其领域定位、资源身份层次、临时/持久两种服务类型的语义差异、六条设计原则、接口面划分与边界约束并结合 naming 模块源码与各子规范说明底层实现脉络。读完本文你将掌握 Nacos 服务发现领域的顶层设计骨架以及各子规范资源、发现订阅、健康保护、生命周期、一致性之间的关联与定位。1. Naming 领域的定位Nacos Naming 是服务发现领域它管理服务、集群、实例、服务元数据、实例元数据、健康状态、订阅者、发布者和客户端服务视图。Naming 是 Nacos 的一级领域不是通用流量治理引擎、服务网格控制面、配置存储或 AI Registry 模型。它可以提供内部过滤、客户端 selector、权重、健康保护和元数据能力但这些能力必须限定在服务发现语义内。这一边界在 第 7 节 有更详细的约束。Naming 规范建立在两个基础规范之上Nacos 设计规范资源模型规范按 README 的说明这些规范来自当前naming、api、client、core、consistency和maintainer-client的实现属于以当前代码为来源的规范。2. 资源身份namespaceId - groupName - serviceNameNaming 使用微服务资源层次标识资源namespaceId - groupName - serviceNameCluster 和 Instance 是从属资源namespaceId - groupName - serviceName - clusterName - instance2.1 Service 身份字段字段含义说明namespaceId服务所属 namespace当接口支持默认值处理时空值或缺省值会被处理为默认 namespace idgroupNamenamespace 内的业务分组新公开规范和 v3 接口使用groupName兼容 key 中仍可能使用groupserviceNameserviceName服务资源名serviceName是 Naming service 的resourceName身份字段是稳定的。修改namespaceId、groupName或serviceName表示创建了新的 service 资源而不是普通元数据更新。详细规则见 Naming 资源规范。2.2 Instance 资源Instance 从属于 service 和 clusternamespaceId - groupName - serviceName - clusterName - ip:port字段含义ip实例地址必填port实例端口必填范围0..65535clusterName实例所属 cluster默认为DEFAULTweight实例流量权重默认为1.0healthy运行时健康状态默认为true可被心跳或主动健康检查改变enabled实例是否可被运行时消费者发现默认为trueephemeral兼容和路由字段必须与所属 service 类型匹配默认truemetadata实例元数据 key-value mapinstanceId可选的生成或用户指定运行时标识公开身份应使用 service scope 加clusterName、ip和port。instanceId是运行时标识不应在新 API 中替代规范化身份字段。2.3 内部 Key实现代码中会使用以下兼容 keygrouped service namegroupserviceNameservice keynamespacegroupserviceNameservice info keygroupserviceNameclustersmetadata id由 instanceip、port和clusterName生成这些 key 是实现和兼容 key。新 API 和 SDK 契约应优先使用显式namespaceId、groupName、serviceName、clusterName、ip和port字段。3. 服务类型临时服务与持久服务每个 Naming service 都属于以下一种服务类型服务类型含义主要状态路径临时服务非持久化运行时服务。实例由存活的 client 持有并会随心跳或连接过期而消失偏 AP 的临时 client state 和 Distro 同步持久服务持久化服务。实例作为持久资源管理并可以从服务端 snapshot 恢复偏 CP 的持久 client state 和元数据持久化服务类型是 service 级语义属性。Instance 的ephemeral输入必须与所属 service 类型匹配。实现中可以在 instance 上保留ephemeral字段用于兼容和路由但新行为不得把它当作可以在同一个 service 内混用类型的独立实例策略。对应校验规则在 Naming 资源规范 中有明确表述持久实例不得注册到临时服务临时实例也不得注册到持久服务。4. 规范层次一张完整的 Naming 规范地图Naming 顶层规范把全部能力拆解为两类子规范形成清晰的层次结构。4.1 通用规范责任含义详细规范资源模型定义 service、cluster、instance、client、publisher 和 subscriber 身份Naming 资源规范发现与订阅定义查询、订阅、推送、模糊订阅、本地缓存和 failover 视图Naming 发现与订阅规范健康检查与保护定义健康状态、主动健康检查、enabled 状态、权重、内部过滤和保护阈值Naming 健康检查与保护规范元数据与 selector定义 service、cluster、instance 元数据、运行时与运维态元数据优先级、保留 key、内部过滤、遗留 API selector 和客户端 selector 行为Naming 元数据与 Selector 规范运维定义 client 诊断、subscriber 诊断、指标、开关、日志级别和清理边界Naming 运维规范4.2 按服务类型分化的规范责任含义详细规范实例生命周期定义通用生命周期以及按服务类型区分的注册、心跳、注销、更新、批量注册和清理行为Naming 实例生命周期规范一致性与客户端状态定义通用 client 身份以及临时服务 AP 状态、持久服务 CP 状态、索引和 snapshotNaming 一致性与客户端状态规范临时服务 Distro 一致性定义临时 ownership、Distro 同步、verify、anti-entropy、清理和 AP 可见性Naming 临时服务 Distro 一致性规范持久服务 CP 一致性定义持久实例 CP 写入、metadata group、snapshot、恢复和可见性Naming 持久服务 CP 一致性规范5. 六条设计原则5.1 Service 是发现单元Naming service 是可寻址的服务发现单元。Instance 必须在 service scope 和 cluster scope 下理解脱离namespaceId、groupName和serviceName的 instance 不是完整的 Naming 资源。5.2 运行面与管理面分离运行时客户端注册或注销自己的实例、查询已知服务并订阅服务变化而服务创建、服务删除、服务元数据、集群元数据、client 诊断、subscriber 诊断、指标、开关和日志级别操作属于管理能力应通过 Admin API、Console API 或 Maintainer SDK 暴露。HTTP Open API 面向无法使用 gRPC 的自定义客户端提供指定服务的注册、心跳、注销和列表查询不应扩展为大范围服务管理或推送订阅 API。5.3 临时服务与持久服务是不同语义临时服务是非持久化运行时服务其实例绑定 client 存活状态并使用偏 AP 的临时路径持久服务是持久化服务其实例使用偏 CP 的持久路径。API、SDK 和存储代码必须保留此区别不能把ephemeral仅作为展示字段处理。5.4 发现视图是过滤后的状态Naming 发现结果不是原始存储 dump。查询和订阅结果可能经过 cluster、enabled 状态、健康状态、服务端内部过滤规则和保护阈值过滤。SDK selection 会在服务端提供的ServiceInfo视图之上继续做客户端 selector 和权重选择。5.5 推送更新客户端视图gRPC 订阅推送携带已订阅服务的最新ServiceInfo状态。客户端将推送状态保存到内存和磁盘缓存比较实例 diff通知 listener并在重连、缓存缺失或轮询兜底时重新查询。HTTP Open API 不提供长轮询或推送订阅。5.6 横切能力通过扩展接入Naming 可以集成扩展机制但 Naming 领域归属不转移关注点规则鉴权Naming API 和 gRPC handler 使用 Naming 资源并遵循鉴权与权限规范可见性对 service、instance、subscriber 或 client 的范围查询在启用可见性插件时应应用可见性规则Control高频注册、注销、查询、订阅、推送和列表流程应暴露稳定的 Control 点遵循 Control 插件规范Trace 与指标Naming 生命周期事件应遵循 Trace 插件规范共享指标和诊断遵循可观测钩子规范健康检查扩展健康检查类型通过 health checker registry 加载并必须保持 service/cluster/instance 资源模型不变寻址客户端服务端寻址应遵循寻址插件规范6. 接口面六个入口的职责划分接口面范围HTTP Open API/v3/client/ns/instance面向自定义运行时客户端提供注册、心跳、注销和列表查询HTTP Admin API/v3/admin/ns/*提供 service、instance、cluster、health、client 和运维管理gRPC API提供运行时注册、批量注册、持久注册、查询、订阅、模糊订阅和服务端推送参见 gRPC API 规范Client SDK通过NamingService面向运行时应用提供注册、注销、查询、订阅、模糊订阅、本地缓存和 failover参见 SDK 规范 和客户端运行时规范Maintainer SDK通过 naming maintainer service 提供管理类接入Console API面向 UI 的管理流程。Console API 可以调整展示形态但不能重新定义 Naming 语义以 Client SDK 为例NamingService 接口提供了完整的运行时能力getAllInstances返回当前视图selectInstances按健康、enabled 状态和正权重过滤selectOneHealthyInstance按权重选择一个实例以及subscribe/unsubscribe接收NamingEvent或客户端 selector-based eventfuzzyWatchWithServiceKeys进行基于 pattern 的 service-key 订阅。SDK selection 只作用在客户端进程内不应视为服务端流量策略。7. 边界明确什么不属于 NamingNaming 不拥有配置内容或 Config listener 语义。Naming 不拥有 AI 资源身份。AI 资源可以引用 Naming service 或 endpoint但引用关系不应让 AI 资源变成普通 Naming service。Naming metadata 是 key-value 服务发现元数据。只有 Naming 明确定义的保留元数据 key 才能改变核心行为。Naming 健康检查用于判断发现可用性不是通用应用观测或 SLA 系统。内部过滤和 SDK selector 是发现侧过滤与选择工具。遗留 API 定义的 service selector 是兼容字段不应成为新流量策略语义的基础。8. 源码中的实现锚点顶层规范中的抽象概念在源码中都有对应的实现锚点便于深入研读Distro 数据模型临时服务的 Distro 同步使用 resource typeNacos:Naming:v2:ClientData定义在 DistroClientDataProcessorresource key 为 client id。Distro 不以 service 级记录作为权威来源service view 由 client state 和索引派生。持久服务 CP group持久实例发布状态使用Constants.NAMING_PERSISTENT_SERVICE_GROUP_V2值为naming_persistent_service_v2定义在 Constants由 PersistentClientOperationServiceImpl 引用。client 状态模型gRPC 连接、HTTP connection-based client、IP-port client 的生命周期差异见 Naming 一致性与客户端状态规范 与 Naming 临时服务 Distro 一致性规范。健康保护protectThreshold用于防止发现结果收缩到过少健康实例详细语义见 Naming 健康检查与保护规范。订阅与推送gRPC 订阅记录 subscriber 并返回当前ServiceInfo视图变更推送遵循事件分发与 NotifyCenter 规范。9. 深入子规范从顶层到实现细节顶层规范只定义骨架完整的可操作语义落在各子规范中。以下是对关键子规范的精读摘要帮助读者按图索骥。9.1 实例生命周期注册 - 心跳 - 注销 - 清理实例生命周期规范 定义了 service 和 instance 的完整生命周期Service 生命周期Admin 创建 service 时必须选择临时或持久类型后续注册必须匹配只有无已注册实例时才允许删除 service运行时实例注册可以隐式创建 service singleton。实例注册必须校验字段和心跳元数据、填充 cluster 默认值、解析服务类型、确保ephemeral匹配、派生 client id、走对应操作路径并通过 Naming 事件更新索引与 storage最后发布 trace 事件。心跳HTTP Open API 心跳复用POST /v3/client/ns/instance并设置heartBeattruegRPC 临时服务通过连接生命周期事件保活。心跳找不到 instance 时返回INSTANCE_NOT_FOUND调用方应重新注册。注销幂等 no-op 设计——注销不存在的实例或兼容 client 应视为成功最后一个 publisher 消失时发出 delete-service 变更事件。更新全量更新校验权重并替换运维态 metadata局部更新只修改显式出现的字段更新不改变 service 身份。批量操作批量注册是临时服务 gRPC 能力输入必须为合法临时实例批量注销被描述为批量状态替换行为。清理包括心跳过期、连接断连释放、空 service 清理、过期元数据清理且清理必须发布与正常流程同类的资源事件。9.2 健康检查与保护健康检查与保护规范 将healthy与enabled区分开healthy由心跳/主动健康检查/手动更新仅 checker 为 NONE 时/节点间同步驱动enabled控制是否允许接收发现流量disabled 实例不应返回给运行时 Open API 消费者。临时服务的健康由运行时 publisher 存活驱动HTTP 与兼容客户端通过上报心跳维持存活Beat check task 依据 last heartbeat time 判断超时心跳时间可由保留元数据 key 自定义Key含义preserved.heart.beat.interval期望心跳间隔preserved.heart.beat.timeout实例被视为 unhealthy 前的超时时间preserved.ip.delete.timeout实例可被删除前的超时时间持久服务则由服务端健康检查 processor 主动检查内置 checker 类型包括 TCP、HTTP、MySQL 和 NONE额外类型通过 health checker registry 注册。保护阈值机制在 cluster、enabled、内部过滤和 health 过滤后如果健康比例小于等于protectThreshold服务端会标记达到保护阈值返回更宽的过滤实例集合并把 unhealthy 实例表现为 healthy——保护阈值是发现可用性保护机制不表示底层实例真实健康。9.3 发现、订阅与 failover发现与订阅规范 定义了查询返回的ServiceInfo视图含 service name、groupName、clusters、cache duration、last reference time、hosts 和保护阈值状态以及过滤链cluster 过滤、enabled-only 过滤、health-only 过滤、服务端内部过滤规则、保护阈值。gRPC 订阅在调用方连接下记录 subscriber 并返回当前视图后续变化推送Java SDK 会尽可能将同一 service 的多个本地 listener 映射成一个服务端订阅。模糊订阅通过serviceName和groupNamepattern 订阅 service key服务端维护 pattern - watched clients 与 pattern - 匹配 service keys存在数量限制。failover 模式下 SDK 可优先读取本地 failover 数据它是客户端应急视图不得改变服务端资源模型。9.4 一致性路径临时 AP 与持久 CP一致性与客户端状态规范 是理解 Naming 内部架构的核心Naming Client 是服务端对运行时通信参与方数据的抽象gRPC 一个存活连接对应一个 connection-based ClientHTTP 兼容客户端可创建 IP-port-based Client携带稳定 Client id 的新 HTTP 契约使用HttpConnectionBasedClient内部 Client id 为HTTP_CLIENTexternalClientId。发布到推送的主链路为注册、注销、订阅或取消订阅请求更新 ClientClient 更新产生 Naming 事件service 到 publisher、service 到 subscriber 的索引根据事件更新通过索引从 publisher Clients 聚合 service 数据通过索引筛选订阅同一 service 的 subscriber ClientsgRPC push 通过每个 subscriber 连接发送聚合后的ServiceInfo视图。临时服务走偏 AP 路径Distro client data 同步持久服务走偏 CP 路径persistent service group snapshot订阅属于临时 client 行为持久 client 不支持 subscriber state。临时服务 Distro 一致性规范 进一步明确了 ownership 规则connection-based client 由持有连接的节点拥有IP-port client 由 Distro responsibility 选出、变更传播client changed -CHANGE、disconnected -DELETE、verify failed -ADD、verify 与 anti-entropyrevision 匹配刷新 liveness不匹配触发 repairsnapshot 是整数据类型的 anti-entropy以及最终一致性的可见性链条owner 更新 - 本地事件更新索引 - Distro sync - peer apply - service change event 调度 push。持久服务 CP 一致性规范 定义了三个独立 CP groupConstants.NAMING_PERSISTENT_SERVICE_GROUP_V2持久实例发布状态、Constants.SERVICE_METADATAservice 和 cluster metadata、Constants.INSTANCE_METADATAinstance metadata。持久实例写入序列化为 instance store request 提交到 persistent groupmetadata 写入保留 service type 字段snapshot 恢复按更新已有 client / 创建缺失 client / 移除多余 client / 产生修复事件四步执行。失败行为上CP group 无可用 leader 时必须失败不得 fallback 到 Distro持久 batch registration 和 persistent subscription 均不支持。10. 相关规范速查Naming 临时服务 Distro 一致性规范Naming 持久服务 CP 一致性规范运行时推送与重连规范AP 一致性规范CP 一致性规范内部 RPC 与集群请求规范Naming 目录 README规范全景图【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考