Nacos SDK 设计规范全景解读：Client SDK 与 Maintainer SDK 的能力边界、AI 契约与多语言对齐
【免费下载链接】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
导读
本文基于仓库specs/zh-cn/sdk/目录下的 SDK 规范 及其配套的 Java SDK 实现规范 与 Java SDK JSON 适配规范，系统梳理 Nacos SDK 的整体设计骨架：两类 SDK 的职责划分与权限边界、Agent/RAD 目标契约、MCP 生命周期托管、安全与传输对齐原则，以及 Java 基准实现的 Factory 生命周期、配置模型、接口矩阵和 JSON 序列化适配模型。读完本文，你将能够准确判断"某个能力该用哪个 SDK 接入"，掌握 Java Client SDK 与 Maintainer SDK 的核心接口与配置方式，并理解 Nacos 如何在不破坏既有 Jackson 2 用户的前提下向 Jackson 3 / Spring Boot 4 平滑演进。
1. SDK 分类：Client SDK 与 Maintainer SDK 的职责边界
SDK 规范（specs/zh-cn/sdk/sdk-spec.md）开篇即定义了 Nacos SDK 的总体定位：它是一套语义契约（semantic contract），不同语言 SDK 可以采用符合各自语言习惯的命名、异步模型和包结构，但公开能力边界必须遵循同一套规范。Java 是定义共享 SDK 语义的基准实现，由 Java SDK 实现规范 给出具体落地规则。
Nacos SDK 被严格划分为两类：
| 类别 | 目标用户 | 定位 | 典型能力 |
|---|---|---|---|
| Client SDK | 微服务应用、Agent Framework、其他运行时工作负载 | 应用正常运行期间消费 Nacos 能力 | 读取并订阅配置、注册/注销实例、查询/订阅依赖服务、发现与订阅 AI 资源、可选分布式锁 |
| Maintainer SDK | 运维工具、控制台、网关、管理平台 | 避免自行拼装和调用 Nacos Admin HTTP API | 命名空间/集群/服务端维护、配置全量管理、注册中心维护、AI 资源管理、分页过滤 |
两类 SDK 可以复用模型对象、鉴权参数、重试规则和连接基础设施，但不应混淆目标用户和权限边界——这是全文反复强调的核心设计原则。从仓库模块结构看，这一划分已经落实到 artifact 层：Java Client SDK 由nacos-clientartifact 和api模块中的公开 interface 提供，Java Maintainer SDK 则由nacos-maintainer-clientartifact 和maintainer-client模块中的公开 interface 提供。
1.1 Client SDK 应暴露什么、避免暴露什么
Client SDK 面向应用运行时访问，只应暴露运行时应用通常需要的能力：
- 读取已知配置项，并订阅这些配置的变更；
- 注册和注销当前应用实例；
- 查询和订阅应用已知依赖的服务；
- 注册、发现和订阅运行时 AI 资源（包括可调用 Agent Endpoint），并继续保留历史 MCP、A2A、Prompt、Skill 和 AgentSpec 兼容面；
- 在语言 SDK 支持时，提供分布式锁等可选运行时原语；
- 按客户端运行时规范管理自身生命周期、本地缓存、监听器和连接。
相应地，Client SDK应避免暴露大范围管理能力，包括：集群控制、服务端状态变更、日志级别变更、连接或流量重载；列举全部命名空间/配置/服务/客户端；查询历史、审计类元数据、dump 数据或订阅者列表；批量删除、跨命名空间管理等高影响操作；以及主要面向运维人员而非运行时应用的写入 API。
规范特别指出：部分历史 Client SDK interface 已经包含写入或大范围查询能力（例如配置发布、配置删除、服务列表查询），这些 API 属于兼容面。新的 SDK 设计不应继续扩大这类能力；管理类场景应转向 Maintainer SDK 或 Admin API。这一点在 Java 实现规范中有明确呼应——NamingService.getServicesOfServer被标注为"兼容性大范围查询面，新的大范围列举应使用 Maintainer SDK"，其 selector overload 已废弃，仅作为兼容面保留。
1.2 Maintainer SDK：Admin API 的类型化门面
Maintainer SDK 面向管理接入，可以暴露 Client SDK 有意不包含的能力：
- 命名空间、集群、服务端状态、readiness/liveness、日志级别等维护能力；
- 配置的列表、搜索、发布、删除、历史、beta、dump 和元数据管理；
- 服务、实例、集群元数据、订阅者、客户端、健康检查等注册中心维护能力；
- Agent、MCP、A2A、Prompt、Skill、AgentSpec 和 Pipeline 等 AI 资源管理；
- 对大规模管理数据提供分页和过滤能力。
规范将其定位为"Nacos Admin API 能力面的类型化门面"：只对管理、UI、网关或运维工具有意义的能力，应归入 Maintainer SDK，而不是 Client SDK。仓库中maintainer-client/src/main/java/com/alibaba/nacos/maintainer/client/下的结构即为这一设计的直接证据，其config/、naming/、ai/、core/子包分别对应 ConfigMaintainerService、NamingMaintainerService、AiMaintainerService 与 CoreMaintainerService。
2. Agent 与 RAD 目标契约
第 4 节定义了 Agent 管理和 Remote Agent Discovery（RAD） 的目标 SDK 契约。需要强调的是，该节是"目标契约"，并不表示任一 SDK 当前已经实现这些能力；在 Agent API 规范 定义的 Agent/RAD 能力完成实现和协商前，现有 A2A SDK 接口仍是生效的兼容契约。
2.1 目标 Client SDK 契约
目标 Client SDK 必须满足：
- 每个 SDK 实例绑定一个 namespace，公开的 Agent 发现、Watch、注册和注销方法不传 namespace；
- 提供 Agent Search、带或不带 Filter 的 Discover、Watch 与取消 Watch，以及运行时 Endpoint Register 和 Deregister；
- 通过
AiService.publishAgent提供可选的代码式 Agent 定义发布，默认只创建 draft，并可通过autoSubmit执行普通 submit Pipeline； - 在不修改调用方对象的前提下，把绑定的 namespace 注入传输请求；
- 按客户端恢复规范在 reconnect 后恢复 Watch 和 Endpoint 发布意图。
同时明确：代码式定义发布是持久操作，不进入 Endpoint redo；Endpoint 注册仍不得隐式创建 Agent。旧A2aService的多 Version Endpoint redo、AgentCard 轮询订阅和 shutdown 生命周期在兼容窗口内必须保持可恢复且资源可释放。
2.2 目标 Maintainer SDK 契约
目标 Maintainer SDK不绑定 namespace，每个 Agent 管理调用都必须显式标识 namespace。它提供新的 Agent 管理 Facade，并在 A2A 兼容窗口内继续保留 A2A 管理 Facade。
3. MCP 生命周期托管契约
在 MCP Metadata 和 Version 迁移到通用 AI Resource 生命周期期间，现有 Java Client MCP 接口继续作为兼容表面。只要现有操作可以在内部适配，公开方法签名就保持不变：
- Release继续作为 Direct-Online 兼容写入，并保持相同返回值；
- Query保持当前 Serving 投影，省略 Version 时使用
latest； - Subscription继续轮询完整 MCP Query 投影，不订阅底层 Naming Service；
- Endpoint 注销、重连和 Redo保留 Client 所有的 Runtime Publication 意图，且不创建或删除 MCP 定义。
生命周期托管不修改当前 Runtime ServiceName、Cluster、Metadata、Endpoint Request、Reconnect Snapshot 或能力协商，也不增加 Runtime Version Range 或多 Transport 字段。
Maintainer SDK 侧则保留现有 MCP 方法作为兼容 Facade，并增加与 Admin MCP Version 操作一一对应的类型化方法：Version 列表/详情、Draft 创建/更新/删除、Submit、Publish、Force Publish、Redraft、Online、Offline 和 Label 操作。旧 Detail 和 Direct-online Create/Update 方法自 3.3.0 起废弃，计划在 4.0.0 删除；调用方应迁移到精确 Version 读取和 Draft-Submit-Publish 流程。
类型化 Request Object 为McpServerDraftRequest、McpServerVersionCommand和McpServerLabelsUpdateRequest。它们不新增顶层 Namespace 或mcpId选择器；显式重载独立接收 Namespace，便利重载使用默认 Namespace。Draft 创建/更新通过 Request Object 重载复用既有createMcpServer和updateMcpServer名称；其余方法使用面向用户的 Version 和操作名称，不暴露内部 Lifecycle 托管机制。现有只接收mcpId的 Maintainer Overload 继续作为已废弃兼容输入，服务端从 MCP AI Resource Row 解析别名后执行 Name-Based 鉴权和操作。
4. 安全规则：最小权限原则
SDK 能力设计必须遵循最小权限原则，规范给出了五条明确约束：
- Client SDK 凭据应限制在运行时资源范围内，不应要求大范围读写权限；
- Maintainer SDK 凭据权限更高，文档和示例必须与 Client SDK 凭据明确区分；
- 大范围读取 API 必须提供显式过滤和分页，不应静默执行无边界的全量集群读取；
- 跨命名空间操作属于 Maintainer SDK，并应要求显式传入 namespace；
- 当 API 可以列举或导出大量配置、服务、客户端或元数据时，SDK 文档应明确说明可能的数据泄露风险。
5. 传输和 API 对齐：语义契约而非传输契约
SDK 契约是语义契约，而不是传输契约：
- Client SDK 可以使用 gRPC、HTTP Open API、本地缓存文件或多种传输组合，只要公开 SDK 行为保持稳定；
- Client SDK 的连接、server list、能力协商、本地缓存和 redo 行为由客户端运行时规范定义；
- Maintainer SDK 应与 Nacos Admin API 的语义和结果模型对齐，即使实现细节未来更换传输方式；
- SDK 模型对象应与 HTTP 和 gRPC 的语义对象对齐，避免同一个业务含义在不同传输中被重复定义；
- SDK 错误应将 Nacos 错误码和校验失败映射为符合语言习惯的异常或结果类型，同时保留服务端语义。
Java 实现在 interface 背后混合使用 gRPC、HTTP 和 config 组装（参见下文第 6 节的接口矩阵），正是"公开 interface 契约独立于具体传输方式保持稳定"这一原则的体现。
6. 多语言 SDK 对齐
Java 目前是定义共享 SDK 语义的基准实现，其他语言 SDK 应对齐相同的能力分类：
- 初始化、命名空间绑定、鉴权和生命周期关闭；
- Client SDK 的配置、注册中心、AI 以及可选分布式锁运行时能力；
- Maintainer SDK 的 Core、配置、注册中心和 AI 管理能力；
- namespace、group、dataId、service name、cluster、version、label 等一致的数据标识规则；
- 在语言运行时支持时，按照客户端本地缓存与 Redo 规范保持一致的监听、订阅、重试、超时和本地缓存行为。
语言 SDK 可以按照语言习惯暴露 future、promise、stream、coroutine、callback 或 context cancellation。这些差异应记录在语言实现规范中，而不是改变共享 SDK 范围。
7. Java Client SDK：Factory 与生命周期
Java SDK 实现规范 的第 2 节给出了 Java Client SDK 的完整 Factory 矩阵：
| Interface | Factory | 生命周期关闭方法 |
|---|---|---|
ConfigService | NacosFactory.createConfigService(...) | shutDown() |
NamingService | NacosFactory.createNamingService(...) | shutDown() |
AiService | AiFactory.createAiService(Properties) | shutdown() |
LockService | NacosLockFactory.createLockService(Properties)或NacosFactory.createLockService(Properties) | shutdown() |
NamingMaintainService | NacosFactory.createMaintainService(...) | shutDown() |
其中NamingMaintainService在 3.3.0 后已废弃，新的管理类接入应使用nacos-maintainer-client。这些 Factory 的源码均在api模块中，例如 AiFactory 通过反射加载com.alibaba.nacos.client.ai.NacosAiService实现（api/src/main/java/com/alibaba/nacos/api/ai/AiFactory.java），验证了"公开 interface 在api模块、实现下沉到client模块"的分层设计。
一个 Java Client SDK 实例绑定一个命名空间。需要访问多个命名空间的应用应创建多个 Client SDK 实例，并在不再使用时关闭实例。公开运行时接口不暴露 namespace 参数，实现使用构造时绑定的 namespace。该规则不适用于 Maintainer SDK：其 Agent 管理接口不绑定 namespace，可显式传入 namespace，并提供使用public的默认 namespace 重载；Agent 管理 Request 和 Command 对象不包含 namespace，显式方法参数是自定义 namespace 的唯一来源。
8. Java Client SDK 配置模型
Java Client SDK 配置由NacosClientProperties表达，默认配置查找顺序为：
Properties -> JVM system properties -> environment variables -> defaults第一个查找来源可通过nacos.env.first或NACOS_ENV_FIRST调整。
规范给出的常见配置项如下（完整继承原文档）：
| 配置项 | 范围 | 含义 |
|---|---|---|
serverAddr | 通用 | Nacos Server 地址列表。 |
contextPath | 通用 | 服务端 context path，默认nacos。 |
endpoint及 endpoint 相关配置 | 通用 | 动态服务端地址接入点。 |
namespace | 通用 | 当前 SDK 实例绑定的命名空间 id。 |
username,password | 通用 | 开启鉴权时的登录凭据。 |
accessKey,secretKey,ramRoleName,signatureRegionId | 通用 | RAM 风格鉴权参数。 |
configRequestTimeout | config | Config RPC 请求超时覆盖值。 |
namingRequestTimeout | naming | Naming RPC 请求超时覆盖值。 |
nacos.server.grpc.port.offset | 连接 | Java 客户端使用的 gRPC 端口偏移。 |
已废弃的历史配置项应继续兼容，但新增代码不应依赖这些配置引入新行为。此外，Java SDK JSON 适配规范 还定义了 JSON adapter 选择配置项nacos.client.json.adapter（详见第 10 节）。
9. Java Client SDK 接口矩阵
9.1 ConfigService
| 能力 | 方法 | 契约 |
|---|---|---|
| 查询配置 | getConfig,getConfigWithResult | 按dataId和group查询单个已知配置；getConfigWithResult额外返回 md5，用于 CAS。 |
| 查询并监听 | getConfigAndSignListener | 查询当前配置，并注册同一个 listener 接收后续变更。 |
| 监听 | addListener,removeListener | 添加或移除监听器。回调应优先使用 listener 提供的 executor。 |
| 发布 | publishConfig,publishConfigCas | 用于创建或更新配置的兼容写入面。CAS 发布必须比较上一次 md5。 |
| 删除 | removeConfig | 用于删除配置的兼容写入面。用户文档定义删除不存在的配置也视为成功。 |
| Filter | addConfigFilter | 添加客户端侧配置 filter。 |
| 模糊订阅 | fuzzyWatch,fuzzyWatchWithGroupKeys,cancelFuzzyWatch | 按 group 或 dataId pattern 订阅配置 key，接收 key 变更事件。 |
| 状态/生命周期 | getServerStatus,shutDown | 查询状态并释放资源。 |
新的大范围配置管理 API 应加入 Maintainer SDK，而不是扩展ConfigService。
9.2 NamingService
| 能力 | 方法 | 契约 |
|---|---|---|
| 注册 | registerInstance,batchRegisterInstance | 在 service 和 group 下注册一个或多个实例。 |
| 注销 | deregisterInstance,batchDeregisterInstance | 移除一个或多个实例。 |
| 查询实例 | getAllInstances,selectInstances,selectOneHealthyInstance | 按 cluster、health、subscribe 等选项查询缓存或远端服务信息。 |
| 订阅 | subscribe,unsubscribe | 接收服务实例变化事件。取消订阅需要使用同一个 listener 实例。 |
| 模糊订阅 | fuzzyWatch,fuzzyWatchWithServiceKeys,cancelFuzzyWatch | 按 group 或 service pattern 订阅服务 key，接收服务级事件。 |
| 列举服务 | getServicesOfServer | 兼容性大范围查询面。新的大范围列举应使用 Maintainer SDK。 |
| 本地状态 | getSubscribeServices,getServerStatus,shutDown | 查询已订阅服务、状态并释放资源。 |
9.3 AiService、AgentDiscoveryService 与 A2aService
本节是 Java 实现规范中篇幅最重、最能体现"目标契约 + 兼容窗口"设计哲学的部分。这里的 Agent/RAD 契约是目标契约，不是当前已经实现的 Java 方法清单；只有新的 Agent/RAD 能力完成实现并经过协商后才生效，在此之前现有AiService和A2aService方法仍是生效的兼容面。
目标继承关系为：
AiService extends AgentDiscoveryService, A2aService这一点在仓库源码中得到直接验证：api/src/main/java/com/alibaba/nacos/api/ai/AiService.java第 40 行声明public interface AiService extends AgentDiscoveryService, A2aService，且publishAgent(AgentPublishRequest)以@Since("3.3.0")的 default 方法形式提供（api/src/main/java/com/alibaba/nacos/api/ai/AiService.java），实现未 override 时抛出SERVER_NOT_IMPLEMENTED——这正是规范要求的"兼容 default bridge，避免已编译的第三方AiService实现立即发生 linkage failure"。
AiService直接提供 namespace-bound 的publishAgent(AgentPublishRequest)，返回AgentVersionDetail。该方法不放入AgentDiscoveryService，因为定义发布不是发现操作。官方实现复制 Request、注入 SDK namespace，并按autoSubmit创建 draft 或执行普通 submit Pipeline，且不修改调用方对象。AgentTransportMode是 API 模块中的 Java 8 兼容枚举，公开GRPC、HTTP、AUTO，可通过getValue()写入nacosAiTransportMode；模式在AiService创建时冻结，非法值在 Factory 创建阶段失败。
AgentDiscoveryService提供以下 namespace-bound 方法：
| 能力 | 方法 | 契约 |
|---|---|---|
| Search | searchAgents | 接受AgentSearchRequest，返回Page<AgentCatalogEntry>。 |
| Discover | discoverAgent重载 | 接受AgentReference和可选AgentDiscoveryFilter，返回一个完整AgentDiscoveryResult。 |
| Watch | subscribeAgent重载 | 接受相同 Reference、可选 Filter 和 Listener；返回当前完整结果，后续传递完整替换结果。 |
| 取消 Watch | unsubscribeAgent重载 | 按相同 Reference、Filter 和 Listener identity 移除 Watch。 |
| 注册 Endpoint | registerAgentEndpoints | 注册一个AgentEndpointRegistrationBatch，并保留为 redo 意图。 |
| 注销 Endpoint | deregisterAgentEndpoints | 注销该 SDK Publisher 拥有的一个AgentEndpointDeregistrationBatch。 |
这些公开方法不接受namespaceId；Proxy 复制调用方的 Request 或 Batch，把 SDK namespace 注入传输对象，且不修改调用方对象。如果共享输入模型已经携带与 SDK namespace 不同的非空值，Proxy 在本地拒绝。目标 Watch、Cache 和 Redo 行为遵循客户端本地缓存与 Redo 规范和运行时推送与重连规范。
旧 A2A Endpoint redo 按 namespace-bound SDK 内的(agentName, exactVersion)区分意图，并保存 Endpoint Payload 的防御性快照；shutdown()必须停止 AgentCard 轮询任务；Endpoint 可以先于 Agent 定义发布，且不得隐式创建定义。
当前已经实现的兼容方法（在AiService中，仓库源码已证实，如 api/src/main/java/com/alibaba/nacos/api/ai/AiService.java）：
| 能力 | 方法 | 契约 |
|---|---|---|
| MCP 查询 | getMcpServer | 按名称和可选版本查询 MCP Server 详情。 |
| MCP 发布 | releaseMcpServer | 创建 MCP Server 或发布新版本。同版本已存在时保持幂等。 |
| MCP endpoint | registerMcpServerEndpoint,deregisterMcpServerEndpoint | 注册或移除当前客户端拥有的 endpoint。 |
| MCP 订阅 | subscribeMcpServer,unsubscribeMcpServer | 订阅 MCP 详情变化。 |
| A2A AgentCard 查询 | getAgentCard | 按名称、可选版本和 registration type 查询 AgentCard。 |
| A2A AgentCard 发布 | releaseAgentCard | 创建 AgentCard 或发布新版本；setAsLatest只影响新版本。 |
| A2A endpoint | registerAgentEndpoint,deregisterAgentEndpoint | 注册或移除当前客户端拥有的 endpoint。批量注册会替换当前客户端此前为该 Agent 注册的 endpoints。 |
| A2A 订阅 | subscribeAgentCard,unsubscribeAgentCard | 订阅 AgentCard 变化。 |
| Skill | downloadSkillZip,downloadSkillZipByVersion,downloadSkillZipByLabel | 按 latest、版本或标签下载 Skill zip 字节。 |
| AgentSpec | loadAgentSpec,subscribeAgentSpec,unsubscribeAgentSpec | 加载组装后的 AgentSpec，并订阅其变化。 |
| Prompt | getPrompt,getPromptByVersion,getPromptByLabel,subscribePrompt,unsubscribePrompt | 按 key、版本或标签查询和订阅 Prompt。 |
资源语义由 AI Registry 规范、Agent API 规范、RAD 协议规范 以及各 AI 资源类型规范定义。
9.4 LockService
LockService是实验性运行时原语，其领域语义由分布式锁规范定义：
| 能力 | 方法 | 契约 |
|---|---|---|
| 用户加锁 | lock | 通过LockInstance#lock获取锁。 |
| 用户解锁 | unLock | 通过LockInstance#unLock释放锁。 |
| 远程加锁 | remoteTryLock | 发送 gRPC lock operation 请求。 |
| 远程解锁 | remoteReleaseLock | 发送 gRPC unlock operation 请求。 |
| 生命周期 | shutdown | 释放客户端资源。 |
10. Java Maintainer SDK：Factory、接口与兼容规则
10.1 Factory 与生命周期
| Interface | Factory | 生命周期关闭方法 |
|---|---|---|
ConfigMaintainerService | NacosMaintainerFactory.createConfigMaintainerService(...)或ConfigMaintainerFactory.createConfigMaintainerService(...) | close() |
NamingMaintainerService | NamingMaintainerFactory.createNamingMaintainerService(...) | close() |
AiMaintainerService | AiMaintainerFactory.createAiMaintainerService(...) | 当前 interface 未暴露 |
Maintainer service 在适用场景下继承CoreMaintainerService。它们属于高权限客户端，应使用管理类凭据进行配置。
10.2 CoreMaintainerService
暴露服务端和集群维护能力：服务端状态、liveness、readiness、ID 生成器状态和 loader metrics；日志级别更新；集群节点列表和 lookup mode 更新；当前客户端连接查看和客户端 reload 操作；命名空间列表、查询、创建、更新、删除和存在性检查；面向管理场景的 raft operation 转发。这些 API 本质上属于管理能力，不应复制到 Client SDK。
10.3 ConfigMaintainerService
包含配置获取、发布、删除和按 namespace 限定的批量删除；按 namespace、dataId、group、type、tag、app 等条件进行配置列表和搜索；clone、import/export 等管理模型；通过BetaConfigMaintainerService提供 beta 和灰度发布能力；通过ConfigHistoryMaintainerService提供历史查询和回滚访问；通过ConfigOpsMaintainerService提供 dump、listener、log 和操作端点；配置描述、标签等元数据更新。
特别值得注意的身份语义规则：按存储 ID 批量删除必须显式传入或默认出 namespace，未传 namespace 的便捷方法只表示默认 namespace，不表示跨 namespace 全局删除；按存储 ID 克隆必须显式传入或默认出源/目标 namespace，旧的单 namespace 克隆方法只表示同 namespace 克隆。暴露存储 ID 选择器的方法（如批量删除中的ids）属于兼容方法并待移除；新的 maintainer 契约应按namespaceId、groupName、dataId或这些身份元组的显式列表选择配置。
10.4 NamingMaintainerService
包含服务创建、更新、删除、详情查询和列表查询；实例注册、注销、更新、列表和元数据维护；通过NamingClientMaintainerService提供订阅者和客户端查询；注册中心 metrics 和日志级别操作；持久化实例健康状态更新；健康检查器列表和集群元数据更新。运行时实例注册仍可保留在NamingService中，但服务管理、大范围列表、订阅者查看和健康检查维护属于 Maintainer SDK。
10.5 AiMaintainerService
暴露类型化 delegate，仓库源码 AiMaintainerService 中可看到agent()、mcp()、a2a()等 default/接口方法：
agent()：返回AgentMaintainerService，与 Agent Admin HTTP API 一一映射。实例不绑定 namespace；各操作提供显式 namespace 形式，以及使用默认 namespacepublic的便利重载。Agent 定义统一通过createDraft创建：首个 draft 在 metadata 不存在时创建 Agent，后续 draft 复用已有 metadata；mcp()：返回McpMaintainerService，历史方法保持二进制兼容；新增类型化 Version 管理方法与 MCP Admin Form/Query Route 一一映射（Version 列表/详情、Draft 创建/更新/删除、Submit、Publish、Force-publish、Redraft、Online、Offline、Label 替换）；a2a()：AgentCard 注册、查询、更新、删除、版本、搜索和列表，在兼容窗口内继续保留；prompt()、skill()、agentSpec()、pipeline()：对应各 AI 资源类型的管理。
运行时 AI 注册和订阅可以继续保留在AiService；大范围 AI 资源管理属于AiMaintainerService。
11. Java 兼容规则与 JSON 适配模型
11.1 Java 兼容规则
Java SDK 实现规范 第 8 节给出了清晰的兼容底线：
api、client和plugin模块保持Java 8 兼容，除非模块策略发生变化；- Java SDK 的 JSON 序列化与反序列化必须通过Java SDK JSON 适配规范定义的中立 JSON adapter 模型，新的公开 SDK API 不得暴露具体 Jackson core/databind 类型；
- 服务端和 maintainer 模块遵循仓库 Java 版本策略；
- Client SDK 和 Maintainer SDK 的 service interface（
XxxService）新增 API 方法时，必须添加@Since声明起始支持的 Nacos 版本号（仓库源码中@Since("3.0.3")、@Since("3.2.0")、@Since("3.3.0")等注解即是该规则的落地证据）； - 已废弃的 Client SDK 方法应尽量保持二进制兼容，但新设计应引导调用方使用 Maintainer SDK；
- 公开模型变更应尽量保持源码和二进制兼容，尤其是 HTTP 和 gRPC API 共享的对象。
11.2 中立 JSON 适配模型
Java SDK JSON 适配规范 解决了 SDK 序列化层的一个现实矛盾：既不能破坏现有 Jackson 2 用户，又要为 Jackson 3 / Spring Boot 4 时代铺路。其设计目标包括：现有 Jackson 2 用户无需增加依赖或修改代码；当 classpath 存在 Jackson 3 时支持 Spring Boot 4 环境；允许 Jackson 2 和 Jackson 3 同时存在于同一个 classpath；没有可用 JSON adapter 时提供明确的 fallback 和诊断信息。
模块边界上，中立 JSON API 定义在nacos-api中（因为api模块的公开模型和 factory 必须能使用它，同时不能依赖nacos-common），包含四个核心构件：JsonUtils（JSON 操作和 adapter 选择的公开中立门面）、NacosJsonAdapter（具体 JSON provider 实现的 SPI）、NacosTypeReference<T>（参数化反序列化的泛型类型捕获）、JSON subtype 注册模型。仓库源码证实了这些构件存在于api/src/main/java/com/alibaba/nacos/api/utils/json/目录下，其中 NacosJsonAdapter 定义了name()与isAvailable()两个关键 SPI 方法。
nacos-common提供默认 adapter：Jackson 2 adapter 以普通 compile 依赖提供（默认对现有用户可用）；Jackson 3 adapter 的依赖必须是非传递或类似 provided，且必须在 Java 8 运行时安全——由ServiceLoader加载的 provider 类不得在公开方法签名、静态字段或 eager 初始化中暴露 Jackson 3 类，应在 availability check 通过后再延迟初始化实际实现。
Adapter 选择规则（配置项nacos.client.json.adapter=auto|jackson2|jackson3，未配置时使用auto）：
- 从运行时 classpath 加载
NacosJsonAdapter实现； - 对每个实现调用
isAvailable()； - 如果只有一个 adapter 可用，使用该 adapter；
- 如果 Jackson 2 和 Jackson 3 adapter 都可用，使用 Jackson 3；
- 如果没有可用 adapter，快速失败并给出明确诊断信息；
- 如果用户显式选择
jackson2或jackson3，只使用对应 adapter；如果不可用，快速失败。
Availability check 至少必须防御ClassNotFoundException、NoClassDefFoundError、UnsupportedClassVersionError、LinkageError、ServiceConfigurationError五类异常。
中立类型模型方面，新代码必须使用NacosTypeReference<T>而不是 JacksonTypeReference<T>：
JsonUtils.toObj(json, new NacosTypeReference<Result<Page<ServiceView>>>() { });NacosTypeReference<T>捕获java.lang.reflect.Type，每个 adapter 将该Type转换为自己的内部类型模型（如 Jackson 2 或 Jackson 3 的JavaType）。新的公开 SDK API 不得暴露 JacksonJavaType，应避免 JacksonJsonNode，优先使用具体 DTO 或Map<String, Object>。中立 JSON 层还必须支持 subtype 注册（记录 base type、具体 subtype、wire type name），JsonUtils在选中的 adapter 初始化或替换时 replay 注册——这是 Naming health checker、selector 等模型保持兼容所必需的。
依赖兼容性的关键事实：Jackson 2 使用com.fasterxml.jackson.*，Jackson 3 使用tools.jackson.*，Jackson annotations 仍位于com.fasterxml.jackson.annotation.*，因此两个版本可以共存；但 SDK 不得依赖 classpath 共存来选择 Jackson 2，auto模式在两者都可用时选择 Jackson 3。
12. 落地路径与验证
12.1 已知迁移目标
Java SDK JSON 适配规范 第 8 节给出了明确的迁移清单：
| 区域 | 期望迁移 |
|---|---|
api模块依赖 | 移除 Jackson core/databind 依赖；按需保留 annotation 依赖。 |
HealthCheckerFactory | 使用中立序列化、反序列化和 subtype 注册。 |
| SDK HTTP 响应解析 | 使用NacosTypeReference替换 JacksonTypeReference。 |
| 简单动态 JSON 读取 | 用 DTO 或Map<String, Object>替换 JacksonJsonNode。 |
| gRPC byte buffer 解析 | 用 Nacos 自有 input stream 或 byte array 路径替换 JacksonByteBufferBackedInputStream。 |
| Canonical JSON 比较 | 通过中立的JsonUtils.toCanonicalJson类 API 处理。 |
| Pipeline Maintainer API | 优先返回类型化PipelineExecution，而不是JsonNode。 |
12.2 行为验证要求
Java SDK JSON adapter 层变更必须包含聚焦测试，覆盖：只有 Jackson 2（现有行为保持兼容）；只有 Jackson 3（Java 17 和 Spring Boot 4 风格应用可以使用 SDK）；两者共存（auto选择 Jackson 3）；显式选择 jackson2 / jackson3；选中的 adapter 缺失时的诊断信息；subtype 注册和反序列化；NacosTypeReference对Result<Page<T>>、List<T>和Map<String, Object>的支持；Pipeline DTO 暴露后类型化结果解析；使用nacos-client的最小 Spring Boot 4 应用。
12.3 测试与文档配套
仓库中已存在与规范配套的验证资产：test/java-sdk-test/模块承载 Java SDK 集成测试场景（JAVA_SDK_IT_SCENARIOS.md、JAVA_SDK_IT_COVERAGE.md），test/maintainer-sdk-test/则覆盖 Maintainer SDK（MAINTAINER_SDK_IT_SCENARIOS.md）。规范还要求，当公开 SDK interface、factory、模型、监听行为、生命周期行为或异常映射发生变化时，必须按照Java SDK 集成测试规范使用场景化 IT 验证。Java Client SDK 用户文档位于 Nacos 文档项目的src/content/docs/next/zh-cn/manual/user/java-sdk，Java Maintainer SDK 用户文档位于src/content/docs/next/zh-cn/manual/admin/maintainer-sdk.md（两者均在独立的 Nacos 文档仓库中维护，当前仓库不包含这些页面）。
结语
从本文的梳理可以看出，Nacos SDK 规范的核心思想可以概括为一句话：用语义契约统一能力边界，用兼容窗口保护存量生态，用类型化门面收敛管理入口。Client SDK 与 Maintainer SDK 的二分法避免了运行时应用被大范围管理能力污染、也避免了运维工具重复拼装 Admin HTTP API；Agent/RAD 目标契约与 MCP 生命周期托管则体现了"目标先行、兼容兜底"的演进策略；中立 JSON 适配层更是为 Jackson 3 / Spring Boot 4 时代提前铺好了不破坏既有用户的迁移路径。对于想要接入 Nacos 的应用开发者，判断"哪个能力用哪个 SDK"只需问三个问题：这是运行时行为还是管理行为？是否需要大范围列举或跨 namespace？是否需要高权限写入？答案指向 Client SDK 还是 Maintainer SDK 就一目了然了。
【免费下载链接】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），仅供参考
