8.2 KiB
8.2 KiB
工作流数据格式说明
1. 节点类型数据示例
{
"id": 2003,
"createTime": "2024-12-05 12:40:03",
"createBy": "system",
"updateTime": "2024-12-05 12:40:03",
"updateBy": "system",
"version": 1,
"deleted": false,
"extraData": null,
"code": "SHELL",
"name": "Shell脚本节点",
"description": "执行Shell脚本的任务节点",
"category": "TASK",
"icon": "code",
"color": "#1890ff",
"executors": [
{
"code": "SHELL",
"name": "Shell脚本执行器",
"description": "执行Shell脚本，支持配置超时时间和工作目录",
"configSchema": "{\"type\":\"object\",\"required\":[\"script\"],\"properties\":{\"script\":{\"type\":\"string\",\"title\":\"脚本内容\",\"format\":\"shell\",\"description\":\"需要执行的Shell脚本内容\"},\"timeout\":{\"type\":\"number\",\"title\":\"超时时间\",\"description\":\"脚本执行的最大时间(秒)\",\"minimum\":1,\"maximum\":3600,\"default\":300},\"workingDir\":{\"type\":\"string\",\"title\":\"工作目录\",\"description\":\"脚本执行的工作目录\",\"default\":\"/tmp\"}}}",
"defaultConfig": null
}
],
"configSchema": "{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"title\": \"节点名称\",\n \"minLength\": 1,\n \"maxLength\": 50\n },\n \"description\": {\n \"type\": \"string\",\n \"title\": \"节点描述\",\n \"maxLength\": 200\n },\n \"executor\": {\n \"type\": \"string\",\n \"title\": \"执行器\",\n \"enum\": [\"SHELL\"],\n \"enumNames\": [\"Shell脚本执行器\"]\n },\n \"retryTimes\": {\n \"type\": \"number\",\n \"title\": \"重试次数\",\n \"minimum\": 0,\n \"maximum\": 3,\n \"default\": 0\n },\n \"retryInterval\": {\n \"type\": \"number\",\n \"title\": \"重试间隔(秒)\",\n \"minimum\": 1,\n \"maximum\": 300,\n \"default\": 60\n }\n },\n \"required\": [\"name\", \"executor\"]\n}",
"defaultConfig": "{\"name\": \"Shell脚本\", \"executor\": \"SHELL\", \"retryTimes\": 0, \"retryInterval\": 60}",
"enabled": true
}
2. 流程设计数据示例
{
"nodes": [
{
"id": "node_1",
"type": "START",
"position": { "x": 100, "y": 100 },
"data": {
"name": "开始",
"description": "流程开始节点",
"config": {
"name": "开始",
"description": "这是一个开始节点"
}
}
}
],
"edges": [
{
"id": "edge_1",
"source": "node_1",
"target": "node_2",
"type": "default",
"data": {
"condition": null
}
}
]
}
3. 关键字段说明
configSchema（节点配置模式）
用途：
- 前端动态生成配置表单
- 后端验证配置数据的合法性
- 提供配置项的约束和验证规则
defaultConfig（默认配置）
用途：
- 新建节点时的默认值
- 重置配置时的参考值
- 必须符合configSchema定义的格式
executors（执行器定义）
用途：
- 定义节点支持的执行器类型
- 每个执行器的配置要求
- 用于任务节点的具体执行逻辑
4. 字段关系说明
- configSchema定义节点的整体配置结构
- defaultConfig提供符合configSchema的默认值
- executors中的configSchema定义具体执行器的配置结构
- 实际节点配置时，executorConfig需要符合选定执行器的configSchema
5. 前端实现指南
5.1 工作流设计器组件架构
推荐使用组件化设计，主要包含以下组件：
-
WorkflowDesigner（工作流设计器）
- 整体容器组件
- 负责状态管理
- 处理快捷键
- 工具栏集成
-
NodePanel（节点面板）
- 显示可用节点类型
- 支持拖拽创建节点
- 节点分类展示
-
Canvas（画布）
- 节点和连线的可视化
- 处理拖拽和连线
- 网格背景
- 缩放和平移
-
NodeConfig（节点配置）
- 动态表单生成
- 配置验证
- 实时预览
5.2 接口说明
5.2.1 节点类型接口
// 获取节点类型列表
GET /api/v1/node-types
Response: {
code: number;
data: NodeType[];
message: string;
}
// 获取单个节点类型详情
GET /api/v1/node-types/{id}
Response: {
code: number;
data: NodeType;
message: string;
}
5.2.2 工作流设计接口
// 保存工作流设计
POST /api/v1/workflows/{id}/design
Request: {
nodes: Node[];
edges: Edge[];
}
Response: {
code: number;
data: boolean;
message: string;
}
// 获取工作流设计
GET /api/v1/workflows/{id}/design
Response: {
code: number;
data: {
nodes: Node[];
edges: Edge[];
};
message: string;
}
5.3 节点连线实现
5.3.1 连接点（Anchors）
每种类型节点的连接点定义：
interface NodeAnchor {
id: string;
type: 'input' | 'output';
position: 'top' | 'right' | 'bottom' | 'left';
allowMultiple?: boolean; // 是否允许多条连线
}
const nodeAnchors = {
START: [
{ id: 'output', type: 'output', position: 'bottom', allowMultiple: true }
],
END: [
{ id: 'input', type: 'input', position: 'top', allowMultiple: false }
],
TASK: [
{ id: 'input', type: 'input', position: 'top', allowMultiple: false },
{ id: 'output', type: 'output', position: 'bottom', allowMultiple: true }
],
GATEWAY: [
{ id: 'input', type: 'input', position: 'top', allowMultiple: false },
{ id: 'output', type: 'output', position: 'bottom', allowMultiple: true }
]
};
5.3.2 连线验证规则
interface ConnectionValidation {
sourceNode: Node;
targetNode: Node;
sourceAnchor: NodeAnchor;
targetAnchor: NodeAnchor;
}
function validateConnection({
sourceNode,
targetNode,
sourceAnchor,
targetAnchor
}: ConnectionValidation): boolean {
// 1. 检查源节点和目标节点是否有效
if (!sourceNode || !targetNode) return false;
// 2. 检查是否形成循环
if (wouldCreateCycle(sourceNode, targetNode)) return false;
// 3. 检查锚点类型匹配
if (sourceAnchor.type !== 'output' || targetAnchor.type !== 'input') return false;
// 4. 检查目标锚点是否已被占用（如果不允许多重连接）
if (!targetAnchor.allowMultiple && hasExistingConnection(targetNode, targetAnchor)) {
return false;
}
return true;
}
5.3.3 连线样式配置
const edgeStyles = {
default: {
type: 'smoothstep', // 平滑阶梯线
animated: false,
style: {
stroke: '#b1b1b7',
strokeWidth: 2
}
},
selected: {
style: {
stroke: '#1890ff',
strokeWidth: 2
}
},
conditional: {
type: 'smoothstep',
animated: true,
style: {
stroke: '#722ed1',
strokeWidth: 2,
strokeDasharray: '5,5'
}
}
};
5.4 状态管理建议
推荐使用状态管理库（如Redux或MobX）管理以下状态：
-
全局状态
- 当前工作流设计
- 可用节点类型
- 画布缩放级别
- 选中的节点/连线
-
节点状态
- 位置信息
- 配置数据
- 验证状态
-
连线状态
- 连接关系
- 条件配置
- 样式信息
5.5 性能优化建议
-
渲染优化
- 使用React.memo()优化节点渲染
- 实现虚拟滚动
- 大量节点时使用分层渲染
-
状态更新优化
- 批量更新状态
- 使用不可变数据结构
- 实现节点位置的防抖
-
交互优化
- 拖拽时使用节点预览
- 连线时显示对齐参考线
- 支持快捷键操作
5.6 错误处理
-
前端验证
- 节点配置验证
- 连线规则验证
- 数据完整性检查
-
错误提示
- 友好的错误信息
- 错误定位高亮
- 操作建议提示
-
异常恢复
- 自动保存
- 操作撤销/重做
- 状态恢复机制
6. 最佳实践建议
-
代码组织
- 使用TypeScript确保类型安全
- 遵循组件设计原则
- 实现完整的测试覆盖
-
用户体验
- 实现撤销/重做功能
- 支持键盘快捷键
- 添加操作引导
-
可扩展性
- 支持自定义节点
- 支持自定义连线样式
- 预留扩展接口