wehub-resource-sync
164 lines
6.5 KiB
Markdown
164 lines
6.5 KiB
Markdown
<!--
|
||
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 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](../console/console-spec.md) |
|
||
| Auth API | `/v3/auth` | 插件提供的鉴权 API 和初始化流程 |
|
||
|
||
不能仅因为某个端点可以通过 HTTP 访问，就把它记录为 Open API。Open API
|
||
比 Admin API 或 Console API 承担更强的兼容性预期。
|
||
|
||
### 2.2 稳定的资源路径形态
|
||
|
||
HTTP 路径在 Nacos Server context path 之后应遵循以下形态：
|
||
|
||
```text
|
||
/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 和健康检查是常见例外。
|
||
|
||
详细响应和错误规则见 [响应与错误规范](response-error-spec.md)。
|
||
|
||
### 2.5 显式鉴权
|
||
|
||
HTTP API 应通过 `@Secured` 声明鉴权，除非端点被明确设计为公开端点、初始化
|
||
端点或健康检查端点。鉴权声明必须反映 API 受众、资源领域和操作动作。
|
||
|
||
详细规则见 [鉴权规范](authorization-spec.md)。
|
||
共享 HTTP filter 和运行时请求上下文模型由
|
||
[请求过滤与运行时上下文规范](../design/foundation-request-context-spec.md)定义。
|
||
|
||
### 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 范围](v3-api-surface.md) 中。
|
||
|
||
更多细节规范：
|
||
|
||
- [鉴权规范](authorization-spec.md)
|
||
- [响应与错误规范](response-error-spec.md)
|
||
- [请求过滤与运行时上下文规范](../design/foundation-request-context-spec.md)
|
||
|
||
## 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 集成测试规范](../testing/api-integration-test-spec.md) 新增或
|
||
更新 API IT，覆盖有意义变更的路由、校验、鉴权、响应形态和场景契约。
|
||
9. 在同一个变更中更新对应规范和网站文档。
|
||
|
||
新增 Open API 需要明确的兼容性说明。新增 Admin API 或 Console API 需要
|
||
明确的鉴权说明。新增非 `Result<T>` API 需要明确的响应形态说明。
|