管理 REST 与 OpenAPI
管理 REST 是 CLI/UI 的同源契约面(206 路由×29 族)——程序集成的首选通道。
OpenAPI 文档
节点运行后自描述:
curl http://127.0.0.1:7901/meta/openapi.json # OpenAPI 3.1 全量文档
curl http://127.0.0.1:7901/meta/routes # UI 投影(summary/tags 同源)
- 契约源
management-api.json单源派生三层产出(openapi/routes/运行时端点)—— 手写翻译表不存在,漏一行即启动拒绝(fail-fast 防漂移); - OpenAPI 3.1 产物自解析自检(构建期机器门:paths≡catalog≡schema≡样例过解析);
- 第三方客户端直接以标准 OpenAPI 工具链生成——不需要内部 UI 的私有客户端。
请求形态
| 项 | 约定 |
|---|---|
| 认证 | Authorization: Bearer <key>(403 结构化信封——见权限模型) |
| 租户段 | 路径内嵌:/api/v1/{tenant}/config/list/route?phase=published |
| 写语义 | POST=写 draft(无热改旁路);幂等读显式 GET |
| 回执 | 版本戳 {logicalAddress, generation};清单读=JSON 数组 |
| 错误 | {code, message, traceId, issues[]}——issues 带 {entityType,key,field,message} |
示例(与 CLI 等价):
curl -X POST -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{ "targets": ["10.0.1.10:8080"] }' \
http://127.0.0.1:7901/api/v1/default/config/set/cluster/orders
{"logicalAddress":"0000000000000000d800000000000000","generation":0}
curl -H "Authorization: Bearer $KEY" \
"http://127.0.0.1:7901/api/v1/default/publish/status"
与 CLI 的一致性保证
CLI 命令树 → REST 路径的翻译表在构建期生成并机器对账:有命令必有路由、 有路由必有命令(api-inventory 机器门 68 行起持续扩张口径)。混用两个入口不会 产生行为分叉——同一命令经 CLI 与经 REST 的服务端语义逐字节一致。
SSE 实时面
/api/v1/…/audit/stream、发布进度、events、KV watch 走 SSE(带 Header 鉴权)——
浏览器 EventSource 与服务端订阅同面。事件语义见可观测。