alibaba--nacos/specs/zh-cn/http-api/api-spec.md

Nacos HTTP API 规范

本文档定义 Nacos HTTP API 的通用设计模型，是 API 设计规则的入口。当前 API 范围、鉴权规则、响应规则等细节维护在关联文档中。

1. 设计动机

Nacos 使用 gRPC 作为高频运行时流量的主要客户端通信协议。HTTP API 仍然 存在，是因为它服务于不同的需求：

• 为无法使用官方 SDK 或 gRPC 的客户端提供语言无关的访问方式；
• 为管理员和运维工具提供运维访问能力；
• 为 Nacos 控制台提供 UI 工作流访问能力；
• 为现有 Nacos 用户提供兼容和迁移路径；
• 便于通过常见 HTTP 基础设施进行检查、脚本化和集成。

因此，HTTP API 的设计首先区分调用者受众，再区分资源。客户端 API、运维 API 和控制台 API 可能操作相似的领域对象，但它们的兼容性承诺、权限模型 和响应预期并不相同。

2. 设计原则

2.1 受众优先

每个 HTTP API 必须先声明它的调用者受众：

受众	路径前缀	预期调用方
Open API	/v3/client	SDK 和自定义运行时客户端
Admin API	/v3/admin	运维人员和维护工具
Console API	/v3/console	Nacos 控制台 UI
Auth API	/v3/auth	插件提供的鉴权 API 和初始化流程

不能仅因为某个端点可以通过 HTTP 访问，就把它记录为 Open API。Open API 比 Admin API 或 Console API 承担更强的兼容性预期。

2.2 稳定的资源路径形态

HTTP 路径在 Nacos Server context path 之后应遵循以下形态：

/v3/{audience}/{module}/{resource}[/{subResource}]

当前模块名包括：

模块	含义
core	集群、命名空间、服务端状态、插件和运维操作
cs	配置中心
ns	注册中心
ai	MCP、A2A、Prompt、Skill、AgentSpec 和 Pipeline
auth	用户、角色和权限
copilot	控制台 Copilot 功能

部署 context path 通常为 /nacos，它不属于 Controller 映射。面向用户的 示例可以包含它，但代码级路径定义不应包含它。

2.3 HTTP Method 语义

V3 HTTP API 按操作语义使用 HTTP Method：

Method	含义
GET	查询或下载数据。
POST	创建、发布、注册、上传、提交或触发任务。
PUT	更新已有状态，或设置幂等的可变状态。
DELETE	删除、注销，或删除绑定和草稿。

任何例外都应先记录到端点级规范中，再被视为有意设计的行为。

2.4 一致的响应契约

JSON HTTP API 应返回 com.alibaba.nacos.api.model.v2.Result<T>，除非存在 明确的响应形态理由。下载、流式 API 和健康检查是常见例外。

详细响应和错误规则见 响应与错误规范。

2.5 显式鉴权

HTTP API 应通过 @Secured 声明鉴权，除非端点被明确设计为公开端点、初始化 端点或健康检查端点。鉴权声明必须反映 API 受众、资源领域和操作动作。

详细规则见 鉴权规范。 共享 HTTP filter 和运行时请求上下文模型由 请求过滤与运行时上下文规范定义。

2.6 兼容性是 API 的一部分

Open API 必须作为长期兼容面进行审查。Admin API 和 Console API 可以演进 得更快，但当文档化用户可能依赖它们时，不兼容变更仍需要废弃说明或迁移指引。

已废弃端点应保留在兼容性章节中，而不是在代码仍支持它们时从文档中静默删除。

2.7 文档跟随规范

面向用户的文档应由规范生成，或至少根据规范和实现进行人工校验。当代码和 文档不一致时，应先分类再解决：

• Normative Spec：Nacos 有意承诺的行为。
• Current Behavior：当前已经实现，但尚未确认长期契约的行为。
• Spec Decision Required：在规范更新前，不应视为已承诺的行为。

2.8 Agent 指南与自动校验

Agent 指南文件、AI skill、Controller 模板和 API 合规校验工具，应把本规范 体系作为规则来源。

这些工具可以保留简短的实现检查清单，方便在本地上下文中使用，但不应定义 与规范冲突的 API 规则。如果 Agent 指南、模板、校验工具、网站文档或实现 与规范不一致，应修正错误的一方，或显式更新规范。

自动校验应将检查结果映射到具体规范规则，包括：

• 受众和路径前缀；
• 模块和资源命名；
• HTTP Method 语义；
• Result<T> 响应形态和已记录的例外；
• @Secured 声明、action、sign type 和 API type；
• 新增 Controller 方法上的 @Since 声明；
• 已废弃兼容端点及其迁移状态。

3. 当前 V3 文档

当前 v3 HTTP API 范围记录在 V3 API 范围 中。

更多细节规范：

• 鉴权规范
• 响应与错误规范
• 请求过滤与运行时上下文规范

4. 新增或变更 HTTP API 的规则

1. 先选择受众：Open、Admin、Console 或 Auth。
2. 按稳定路径形态选择模块和资源路径。
3. 按第 2.3 节的语义使用 HTTP Method。
4. 声明鉴权和动作语义。
5. 新增 Controller 方法必须添加 @Since，声明该 API 起始支持的 Nacos 版本号。
6. JSON 响应使用 Result<T>，除非存在已记录的例外。
7. 在 form 对象或专用 validator 中实现参数校验。
8. 按照 API 集成测试规范 新增或 更新 API IT，覆盖有意义变更的路由、校验、鉴权、响应形态和场景契约。
9. 在同一个变更中更新对应规范和网站文档。

新增 Open API 需要明确的兼容性说明。新增 Admin API 或 Console API 需要 明确的鉴权说明。新增非 Result<T> API 需要明确的响应形态说明。