<!--
  Copyright 1999-2026 Alibaba Group Holding Ltd.

  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.
-->

# Nacos Java SDK 实现规范

本文档定义 Java SDK 如何实现共享的 [SDK 规范](./sdk-spec.md)，覆盖 Java
Client SDK 和 Java Maintainer SDK。

Java SDK 的 JSON 序列化兼容模型由
[Java SDK JSON 适配规范](./sdk-java-json-adapter-spec.md)定义。

## 1. 范围

Java SDK 当前包含两类公开能力：

- Java Client SDK，主要由 `nacos-client` artifact 和 `api` 模块中的公开
  interface 提供。
- Java Maintainer SDK，由 `nacos-maintainer-client` artifact 和
  `maintainer-client` 模块中的公开 interface 提供。

Java Client SDK 是现有运行时应用行为的基准。它的连接、server list、能力协商、
本地缓存和 redo 行为由[客户端运行时规范](../client/README.md)定义。Java Maintainer SDK
是管理、UI、网关和运维场景的推荐 Java 接入方式。

当公开 SDK interface、factory、模型、监听行为、生命周期行为或异常映射发生
变化时，必须按照[Java SDK 集成测试规范](../testing/java-sdk-integration-test-spec.md)
使用场景化 IT 验证 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`。

一个 Java SDK 实例绑定一个命名空间。需要访问多个命名空间的应用应创建多个
SDK 实例，并在不再使用时关闭实例。

## 3. Java Client SDK 配置模型

Java Client SDK 配置由 `NacosClientProperties` 表达。

默认配置查找顺序为：

```text
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 端口偏移。 |

已废弃的历史配置项应继续兼容，但新增代码不应依赖这些配置引入新行为。

## 4. Java Client SDK 扩展点

Java Client SDK 扩展点运行在应用进程内。它们从客户端 classpath 加载，或通过 SDK API
注册，并随所属 SDK 实例关闭。它们不受服务端插件 Admin API 控制。

| 扩展点 | SPI 或 API | 契约 |
| --- | --- | --- |
| 寻址 | `ServerListProvider` | 选择和刷新 HTTP 与 gRPC client 使用的 server list。内置实现支持固定 `serverAddr` 和动态 `endpoint` 模式。 |
| 鉴权 | `AbstractClientAuthService` / `ClientAuthService` | 为 `RequestResource` 生成 access token、RAM 签名或 OIDC bearer token 等请求身份材料。 |
| 配置 filter | `IConfigFilter` 和 `ConfigService#addConfigFilter` | 按稳定顺序拦截配置发布请求和查询响应。 |
| 配置加密 | `ConfigEncryptionFilter` 加 `EncryptionPluginService` | 当算法插件存在时，在发布前加密 `cipher-{algorithm}-` 配置，并在查询后解密匹配配置。 |

客户端扩展不得重新定义 Nacos 资源身份，也不得扩大 Client SDK 的能力面。扩展如果需要管理
访问，应使用 Maintainer SDK 或 Admin API，而不是向运行时客户端增加高权限操作。

寻址扩展必须返回 Java HTTP 和 gRPC client 可解析的地址，并在动态发现变化时发布 server
list change 事件。鉴权扩展必须使用 `RequestResource` 进行资源感知签名，而不是自行解析
传输 payload。配置 filter 必须保持请求和响应字段语义；当必需的加密插件缺失时，应显式
失败。

### 4.1 内置客户端鉴权服务

Java 客户端当前通过 SPI 注册以下 `AbstractClientAuthService` 实现：

| 实现 | 身份材料 | 契约 |
| --- | --- | --- |
| `NacosClientAuthServiceImpl` | `username`、`password` 和 `accessToken`。 | 与默认 Nacos 鉴权插件的登录 API 集成，并在 token 过期前刷新。 |
| `RamClientAuthServiceImpl` | `accessKey`、`secretKey`、`ramRoleName`、`signatureRegionId`。 | 按 [RAM 鉴权插件规范](../auth/ram-auth-plugin-spec.md)通过 `RequestResource` 生成资源感知的 RAM 风格签名。 |
| `OidcClientAuthServiceImpl` | OIDC client credentials 和 bearer token。 | 按 [OIDC 鉴权插件规范](../auth/oidc-auth-plugin-spec.md)在配置了 OIDC 属性时使用 OAuth2 client credentials flow。 |

Java 客户端会合并所有已加载客户端鉴权服务的 identity 输出。未配置的实现应返回空 identity
context，而不是修改请求 payload 或让无关 SDK 调用失败。默认 Nacos 鉴权插件只拥有 Nacos
用户名/密码和 token 流程；[RAM](../auth/ram-auth-plugin-spec.md) 和
[OIDC](../auth/oidc-auth-plugin-spec.md) 是客户端鉴权扩展，只有在当前服务端鉴权插件或部署侧
身份校验器接受对应身份材料时才会生效。

## 5. Java Client SDK Interface

### 5.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` | 查询状态并释放资源。 |

配置标识遵循用户文档中对 `dataId`、`group` 和配置内容大小的约束。新的大范围
配置管理 API 应加入 Maintainer SDK，而不是扩展 `ConfigService`。

### 5.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` | 查询已订阅服务、状态并释放资源。 |

`getServicesOfServer` 的 selector overload 已废弃，仅作为兼容面保留。

### 5.3 AiService 和 A2aService

`AiService` 继承 `A2aService`。
资源语义由 [AI Registry 规范](../ai/ai-registry-spec.md)和各 AI 资源类型规范定义。

| 能力 | 方法 | 契约 |
| --- | --- | --- |
| 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。 |

当前 Java 实现在 interface 背后可以混合使用 gRPC、HTTP 和 config 组装。公开
interface 契约应独立于具体传输方式保持稳定。

### 5.4 LockService

`LockService` 是实验性运行时原语，其领域语义由[分布式锁规范](../lock/lock-spec.md)定义。

| 能力 | 方法 | 契约 |
| --- | --- | --- |
| 用户加锁 | `lock` | 通过 `LockInstance#lock` 获取锁。 |
| 用户解锁 | `unLock` | 通过 `LockInstance#unLock` 释放锁。 |
| 远程加锁 | `remoteTryLock` | 发送 gRPC lock operation 请求。 |
| 远程解锁 | `remoteReleaseLock` | 发送 gRPC unlock operation 请求。 |
| 生命周期 | `shutdown` | 释放客户端资源。 |

## 6. Java Maintainer SDK Factory 和生命周期

| Interface | Factory | 生命周期关闭方法 |
| --- | --- | --- |
| `ConfigMaintainerService` | `NacosMaintainerFactory.createConfigMaintainerService(...)` 或 `ConfigMaintainerFactory.createConfigMaintainerService(...)` | `close()` |
| `NamingMaintainerService` | `NamingMaintainerFactory.createNamingMaintainerService(...)` | `close()` |
| `AiMaintainerService` | `AiMaintainerFactory.createAiMaintainerService(...)` | 当前 interface 未暴露 |

Maintainer service 在适用场景下继承 `CoreMaintainerService`。它们属于高权限
客户端，应使用管理类凭据进行配置。

## 7. Java Maintainer SDK Interface

### 7.1 CoreMaintainerService

`CoreMaintainerService` 暴露服务端和集群维护能力：

- 服务端状态、liveness、readiness、ID 生成器状态和 loader metrics；
- 日志级别更新；
- 集群节点列表和 lookup mode 更新；
- 当前客户端连接查看和客户端 reload 操作；
- 命名空间列表、查询、创建、更新、删除和存在性检查；
- 面向管理场景的 raft operation 转发。

这些 API 本质上属于管理能力，不应复制到 Client SDK。

### 7.2 ConfigMaintainerService

`ConfigMaintainerService` 包含：

- 配置获取、发布、删除和批量删除；
- 按 namespace、dataId、group、type、tag、app 等条件进行配置列表和搜索；
- clone、import/export 等管理模型；
- 通过 `BetaConfigMaintainerService` 提供 beta 和灰度发布能力；
- 通过 `ConfigHistoryMaintainerService` 提供历史查询和回滚相关访问；
- 通过 `ConfigOpsMaintainerService` 提供 dump、listener、log 和操作端点；
- 配置描述、标签等元数据更新。

管理类写入和大范围查询应加入这里，而不是继续扩展 `ConfigService`。

### 7.3 NamingMaintainerService

`NamingMaintainerService` 包含：

- 服务创建、更新、删除、详情查询和列表查询；
- 实例注册、注销、更新、列表和元数据维护；
- 通过 `NamingClientMaintainerService` 提供订阅者和客户端查询；
- 注册中心 metrics 和日志级别操作；
- 持久化实例健康状态更新；
- 健康检查器列表和集群元数据更新。

运行时实例注册仍可保留在 `NamingService` 中，但服务管理、大范围列表、订阅者
查看和健康检查维护属于 Maintainer SDK。

### 7.4 AiMaintainerService

`AiMaintainerService` 暴露类型化 delegate：

- `mcp()`：MCP Server 列表、搜索、详情、创建、更新和删除；
- `a2a()`：AgentCard 注册、查询、更新、删除、版本、搜索和列表；
- `prompt()`：Prompt 管理；
- `skill()`：Skill 管理；
- `agentSpec()`：AgentSpec 管理；
- `pipeline()`：Pipeline 管理。

运行时 AI 注册和订阅可以继续保留在 `AiService`；大范围 AI 资源管理属于
`AiMaintainerService`。

## 8. Java 兼容规则

- `api`、`client` 和 `plugin` 模块保持 Java 8 兼容，除非模块策略发生变化。
- Java SDK 的 JSON 序列化与反序列化必须通过
  [Java SDK JSON 适配规范](./sdk-java-json-adapter-spec.md)定义的中立 JSON
  adapter 模型。新的公开 SDK API 不得暴露具体 Jackson core/databind 类型。
- 服务端和 maintainer 模块遵循仓库 Java 版本策略。
- Client SDK 和 Maintainer SDK 的 service interface（`XxxService`）新增 API 方法
  时，必须添加 `@Since`，声明该方法起始支持的 Nacos 版本号。
- 已废弃的 Client SDK 方法应尽量保持二进制兼容，但新的设计应引导调用方使用
  Maintainer SDK。
- 公开模型变更应尽量保持源码和二进制兼容，尤其是 HTTP 和 gRPC API 共享的对象。

## 9. 文档参考

- Java Client SDK 用户文档：Nacos 文档项目中的
  `src/content/docs/next/zh-cn/manual/user/java-sdk`。
- Java Maintainer SDK 用户文档：Nacos 文档项目中的
  `src/content/docs/next/zh-cn/manual/admin/maintainer-sdk.md`。