235 lines
7.3 KiB
Markdown
235 lines
7.3 KiB
Markdown
# TraceStudio 后端 API 规范（前端视角）
|
||
|
||
目标：为前端与 AI 提供一份完整、可机器读取的后端 API 规范文档，使第三方或 AI 能基于此快速生成 mock server 或直接对接后端。
|
||
|
||
说明：本文件以 `server/app/api/*.py` 中实现的接口为准，列出每个端点的 URL、方法、请求字段、响应示例以及用于 mock 服务的 JSON schema。
|
||
|
||
---
|
||
|
||
## 目录
|
||
- 文件管理 API (`/api/files/*`)
|
||
- 插件与节点 API (`/api/plugins`, `/api/node/preview`, `/api/graph/execute`, `/api/nodes/save`)
|
||
- 用户管理 (`/api/users/*`)
|
||
- 自定义节点管理 (`/api/custom-nodes/*`)
|
||
|
||
---
|
||
|
||
## 公共响应格式
|
||
- 成功响应通常包含 `data` 或直接返回对象（习惯差异），建议 mock server 使用下面两种可互换格式：
|
||
|
||
1) 标准包裹格式：
|
||
```json
|
||
{ "data": { ... }, "error": null }
|
||
```
|
||
|
||
2) 直接对象格式（FastAPI 端点常用）：
|
||
```json
|
||
{ "success": true, "message": "...", "...": ... }
|
||
```
|
||
|
||
为兼容前端接入，mock server 可以默认返回 `{"data":..., "error": null}`，同时支持返回原始端点返回的直出格式。
|
||
|
||
---
|
||
|
||
## 文件管理 API
|
||
|
||
### GET /api/files/list
|
||
- 描述：列出目录内容
|
||
- 参数（query）：
|
||
- `path` (string) 相对路径，默认 ""
|
||
- 成功响应示例：
|
||
```json
|
||
{
|
||
"path": "users/guest/data",
|
||
"items": [
|
||
{ "name": "护送30.utrace", "path": "users/guest/data/护送30.utrace", "type": "file", "size": 12345, "extension": ".utrace" },
|
||
{ "name": "sample.csv", "path": "users/guest/data/sample.csv", "type": "file", "size": 1024, "extension": ".csv" }
|
||
]
|
||
}
|
||
```
|
||
- Mock schema (JSON Schema simplified):
|
||
```json
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"path": {"type":"string"},
|
||
"items": {"type":"array","items": {"type":"object","properties": {"name":{"type":"string"},"path":{"type":"string"},"type":{"type":"string"},"size":{"type":"number"},"extension":{"type":"string"}}}}
|
||
}
|
||
}
|
||
```
|
||
|
||
### POST /api/files/upload
|
||
- 描述：上传文件（multipart/form-data）
|
||
- 请求：multipart 表单，`file` 字段为文件，query 可带 `path` 与 `username`
|
||
- 成功响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"file": { "name": "sample.csv", "path": "users/guest/data/sample.csv", "size": 1024 }
|
||
}
|
||
```
|
||
- 注意：mock server 可模拟写入并返回路径与 size
|
||
|
||
### GET /api/files/download
|
||
- 描述：下载文件
|
||
- 参数（query）：`path` (string) 必需
|
||
- 响应：文件二进制（mock server 可返回静态文本或固定二进制）
|
||
|
||
### GET /api/files/info
|
||
- 描述：获取文件元信息
|
||
- 参数：`path` (string)
|
||
- 成功示例：
|
||
```json
|
||
{ "exists": true, "name": "sample.csv", "path": "users/guest/data/sample.csv", "type": "file", "size": 1024, "modified": 1670000000.0, "extension": ".csv" }
|
||
```
|
||
|
||
### POST /api/files/action
|
||
- 描述：文件操作（delete/mkdir/rename）
|
||
- 请求体：JSON
|
||
```json
|
||
{ "action": "delete|mkdir|rename", "path": "users/guest/data", "new_name": "new_folder" }
|
||
```
|
||
- 成功示例：
|
||
```json
|
||
{ "success": true, "message": "Deleted" }
|
||
```
|
||
|
||
---
|
||
|
||
## 插件与图执行 API
|
||
|
||
### GET /api/plugins
|
||
- 描述：获取可用节点插件元数据
|
||
- 成功示例（精简）：
|
||
```json
|
||
{
|
||
"plugins": {
|
||
"CSVLoader": { "display_name":"CSV 数据加载器", "category":"Loader/CSV", "class_name":"CSVLoader", "param_schema": [{"name":"file_path","type":"string","default":""}], "inputs": [], "outputs": [{"name":"table","type":"DataTable"}] }
|
||
},
|
||
"total": 1,
|
||
"categories": ["Loader","Transform","Visualizer"]
|
||
}
|
||
```
|
||
- Mock schema：插件对象映射，键为 `class_name`
|
||
|
||
### POST /api/node/preview
|
||
- 描述：预览单个节点（返回列与 preview 数据）
|
||
- 请求 JSON：
|
||
```json
|
||
{ "node": { "id": "n1", "type": "universal", "class_name": "CSVLoader", "data": { "file_path": "users/guest/data/sample.csv" } }, "limit": 10 }
|
||
```
|
||
- 成功示例：
|
||
```json
|
||
{ "class_name":"CSVLoader", "status":"success", "columns":["col1","col2"], "preview":[{"col1":1,"col2":2}], "context": {} }
|
||
```
|
||
- 说明：如果节点输出为 DataFrame，会返回 `columns` 与 `preview` 列表
|
||
|
||
### POST /api/graph/execute
|
||
- 描述：执行完整计算图
|
||
- 请求 JSON（精简）：
|
||
```json
|
||
{ "nodes": [{"id":"n1","type":"universal","class_name":"CSVLoader","params":{...}}], "edges": [{"source":"n1","target":"n2"}], "settings": {} }
|
||
```
|
||
- 成功示例（精简）：
|
||
```json
|
||
{
|
||
"status":"success",
|
||
"message":"成功执行 2 个节点",
|
||
"execution_time": 0.123,
|
||
"results": {
|
||
"n1": { "status":"success", "outputs": {"table": {"__type":"DataFrame","columns":["a","b"],"preview":[{"a":1,"b":2}],"rows":100} }, "error": null }
|
||
},
|
||
"stats": { "total_nodes":2, "total_edges":1 }
|
||
}
|
||
```
|
||
- Mock server应实现 DataFrame preview 序列化结构（`__type: DataFrame`）以便前端渲染
|
||
|
||
### POST /api/nodes/save
|
||
- 描述：保存节点配置
|
||
- 请求 JSON：
|
||
```json
|
||
{ "nodeId": "n_xxx", "nodeData": {...} }
|
||
```
|
||
- 成功示例：
|
||
```json
|
||
{ "success": true, "message": "节点 n_xxx 配置已保存", "nodeId": "n_xxx" }
|
||
```
|
||
|
||
---
|
||
|
||
## 用户 API
|
||
|
||
### GET /api/users/list
|
||
- 描述：返回用户列表
|
||
- 成功示例：
|
||
```json
|
||
{ "users": ["guest","ouczbs"], "count": 2 }
|
||
```
|
||
|
||
### POST /api/users/add
|
||
- 描述：添加用户
|
||
- 请求 JSON：
|
||
```json
|
||
{ "username":"newuser", "display_name":"New User" }
|
||
```
|
||
- 成功示例：
|
||
```json
|
||
{ "success": true, "message": "用户 newuser 创建成功" }
|
||
```
|
||
|
||
---
|
||
|
||
## 自定义节点管理 API（/api/custom-nodes/*）
|
||
|
||
说明：此命名空间包含上传、验证、保存、加载自定义节点的完整流程，mock server 可实现下列端点的简化版本。
|
||
|
||
### GET /api/custom-nodes/list
|
||
- 示例响应：
|
||
```json
|
||
{ "success": true, "total": 1, "nodes": [{"filename":"example.py","valid":true,"loaded":true}] }
|
||
```
|
||
|
||
### POST /api/custom-nodes/validate
|
||
- 请求：{ "code": "<python code>" }
|
||
- 返回：{ "success": true, "validation": {"valid":true, "errors": [] } }
|
||
|
||
### POST /api/custom-nodes/save
|
||
- 请求：{ "filename":"my_node.py","code":"...","force":false }
|
||
- 返回：{ "success": true, "message":"节点已保存并加载", "filename":"my_node.py" }
|
||
|
||
### POST /api/custom-nodes/action
|
||
- 请求：{ "filename":"my_node.py","action":"load|unload|delete|rename","new_filename":"..." }
|
||
- 返回：{ "success": true, "message":"..." }
|
||
|
||
### POST /api/custom-nodes/upload
|
||
- multipart 文件上传，返回 `success`/`validation`/`load_result`
|
||
|
||
### GET /api/custom-nodes/loaded
|
||
- 返回当前已加载节点列表（class_name + metadata）
|
||
|
||
---
|
||
|
||
## Mock Server 指南（快速上手）
|
||
|
||
1. 推荐使用 `json-server` 或用 Node.js + Express 快速 mock（可返回静态 JSON 或根据请求构造回复）。
|
||
2. 必须支持：
|
||
- `/api/plugins` 返回插件元数据
|
||
- `/api/node/preview` 接受 `node` + `limit`，返回 `columns` + `preview`
|
||
- `/api/graph/execute` 返回 `results`，DataFrame 用 `__type: DataFrame` 标记
|
||
- `/api/files/*` 支持 list/upload/download/info/action
|
||
- `/api/custom-nodes/*` 简单实现文件列表、validate、upload、loaded
|
||
3. 示例：使用 Express 的伪代码快速实现 `/api/node/preview`：
|
||
|
||
```js
|
||
app.post('/api/node/preview', (req, res) => {
|
||
const { node, limit } = req.body
|
||
// 根据 node.class_name 返回不同的 preview
|
||
if (node.class_name === 'CSVLoader') {
|
||
return res.json({ class_name: 'CSVLoader', status: 'success', columns: ['a','b'], preview: [{a:1,b:2}] })
|
||
}
|
||
res.status(500).json({ error: 'Unknown node' })
|
||
})
|
||
```
|
||
|
||
---
|