ouczbs/TraceStudio-dev

Fork 0

Boshuang Zhao 5790ec164f add web v2

2026-01-10 19:08:49 +08:00

7.3 KiB

Raw Blame History

TraceStudio 后端 API 规范（前端视角）

目标：为前端与 AI 提供一份完整、可机器读取的后端 API 规范文档，使第三方或 AI 能基于此快速生成 mock server 或直接对接后端。

说明：本文件以 server/app/api/*.py 中实现的接口为准，列出每个端点的 URL、方法、请求字段、响应示例以及用于 mock 服务的 JSON schema。

公共响应格式

成功响应通常包含 data 或直接返回对象（习惯差异），建议 mock server 使用下面两种可互换格式：

标准包裹格式：

{ "data": { ... }, "error": null }

直接对象格式（FastAPI 端点常用）：

{ "success": true, "message": "...", "...": ... }

为兼容前端接入，mock server 可以默认返回 {"data":..., "error": null}，同时支持返回原始端点返回的直出格式。

文件管理 API

GET /api/files/list

描述：列出目录内容
参数（query）：
- path (string) 相对路径，默认 ""
成功响应示例：

{
  "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):

{
  "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
成功响应示例：

{
  "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)
成功示例：

{ "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

{ "action": "delete|mkdir|rename", "path": "users/guest/data", "new_name": "new_folder" }

成功示例：

{ "success": true, "message": "Deleted" }

插件与图执行 API

GET /api/plugins

描述：获取可用节点插件元数据
成功示例（精简）：

{
  "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：

{ "node": { "id": "n1", "type": "universal", "class_name": "CSVLoader", "data": { "file_path": "users/guest/data/sample.csv" } }, "limit": 10 }

成功示例：

{ "class_name":"CSVLoader", "status":"success", "columns":["col1","col2"], "preview":[{"col1":1,"col2":2}], "context": {} }

说明：如果节点输出为 DataFrame，会返回 columns 与 preview 列表

POST /api/graph/execute

描述：执行完整计算图
请求 JSON（精简）：

{ "nodes": [{"id":"n1","type":"universal","class_name":"CSVLoader","params":{...}}], "edges": [{"source":"n1","target":"n2"}], "settings": {} }

成功示例（精简）：

{
  "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：

{ "nodeId": "n_xxx", "nodeData": {...} }

成功示例：

{ "success": true, "message": "节点 n_xxx 配置已保存", "nodeId": "n_xxx" }

用户 API

GET /api/users/list

描述：返回用户列表
成功示例：

{ "users": ["guest","ouczbs"], "count": 2 }

POST /api/users/add

描述：添加用户
请求 JSON：

{ "username":"newuser", "display_name":"New User" }

成功示例：

{ "success": true, "message": "用户 newuser 创建成功" }

自定义节点管理 API（/api/custom-nodes/*）

说明：此命名空间包含上传、验证、保存、加载自定义节点的完整流程，mock server 可实现下列端点的简化版本。

GET /api/custom-nodes/list

示例响应：

{ "success": true, "total": 1, "nodes": [{"filename":"example.py","valid":true,"loaded":true}] }

POST /api/custom-nodes/validate

请求：{ "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 指南（快速上手）

推荐使用 json-server 或用 Node.js + Express 快速 mock（可返回静态 JSON 或根据请求构造回复）。
必须支持：
- /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
示例：使用 Express 的伪代码快速实现 /api/node/preview：

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' })
})

7.3 KiB Raw Blame History Unescape Escape