332 lines
8.2 KiB
Markdown
332 lines
8.2 KiB
Markdown
# 工作流数据格式说明
|
||
|
||
## 1. 节点类型数据示例
|
||
|
||
```json
|
||
{
|
||
"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. 流程设计数据示例
|
||
|
||
```json
|
||
{
|
||
"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（节点配置模式）
|
||
**用途**：
|
||
1. 前端动态生成配置表单
|
||
2. 后端验证配置数据的合法性
|
||
3. 提供配置项的约束和验证规则
|
||
|
||
### defaultConfig（默认配置）
|
||
**用途**：
|
||
1. 新建节点时的默认值
|
||
2. 重置配置时的参考值
|
||
3. 必须符合configSchema定义的格式
|
||
|
||
### executors（执行器定义）
|
||
**用途**：
|
||
1. 定义节点支持的执行器类型
|
||
2. 每个执行器的配置要求
|
||
3. 用于任务节点的具体执行逻辑
|
||
|
||
## 4. 字段关系说明
|
||
|
||
1. configSchema定义节点的整体配置结构
|
||
2. defaultConfig提供符合configSchema的默认值
|
||
3. executors中的configSchema定义具体执行器的配置结构
|
||
4. 实际节点配置时，executorConfig需要符合选定执行器的configSchema
|
||
|
||
## 5. 前端实现指南
|
||
|
||
### 5.1 工作流设计器组件架构
|
||
|
||
推荐使用组件化设计，主要包含以下组件：
|
||
|
||
1. **WorkflowDesigner（工作流设计器）**
|
||
- 整体容器组件
|
||
- 负责状态管理
|
||
- 处理快捷键
|
||
- 工具栏集成
|
||
|
||
2. **NodePanel（节点面板）**
|
||
- 显示可用节点类型
|
||
- 支持拖拽创建节点
|
||
- 节点分类展示
|
||
|
||
3. **Canvas（画布）**
|
||
- 节点和连线的可视化
|
||
- 处理拖拽和连线
|
||
- 网格背景
|
||
- 缩放和平移
|
||
|
||
4. **NodeConfig（节点配置）**
|
||
- 动态表单生成
|
||
- 配置验证
|
||
- 实时预览
|
||
|
||
### 5.2 接口说明
|
||
|
||
#### 5.2.1 节点类型接口
|
||
```typescript
|
||
// 获取节点类型列表
|
||
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 工作流设计接口
|
||
```typescript
|
||
// 保存工作流设计
|
||
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）
|
||
每种类型节点的连接点定义：
|
||
```typescript
|
||
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 连线验证规则
|
||
```typescript
|
||
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 连线样式配置
|
||
```typescript
|
||
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）管理以下状态：
|
||
|
||
1. **全局状态**
|
||
- 当前工作流设计
|
||
- 可用节点类型
|
||
- 画布缩放级别
|
||
- 选中的节点/连线
|
||
|
||
2. **节点状态**
|
||
- 位置信息
|
||
- 配置数据
|
||
- 验证状态
|
||
|
||
3. **连线状态**
|
||
- 连接关系
|
||
- 条件配置
|
||
- 样式信息
|
||
|
||
### 5.5 性能优化建议
|
||
|
||
1. **渲染优化**
|
||
- 使用React.memo()优化节点渲染
|
||
- 实现虚拟滚动
|
||
- 大量节点时使用分层渲染
|
||
|
||
2. **状态更新优化**
|
||
- 批量更新状态
|
||
- 使用不可变数据结构
|
||
- 实现节点位置的防抖
|
||
|
||
3. **交互优化**
|
||
- 拖拽时使用节点预览
|
||
- 连线时显示对齐参考线
|
||
- 支持快捷键操作
|
||
|
||
### 5.6 错误处理
|
||
|
||
1. **前端验证**
|
||
- 节点配置验证
|
||
- 连线规则验证
|
||
- 数据完整性检查
|
||
|
||
2. **错误提示**
|
||
- 友好的错误信息
|
||
- 错误定位高亮
|
||
- 操作建议提示
|
||
|
||
3. **异常恢复**
|
||
- 自动保存
|
||
- 操作撤销/重做
|
||
- 状态恢复机制
|
||
|
||
## 6. 最佳实践建议
|
||
|
||
1. **代码组织**
|
||
- 使用TypeScript确保类型安全
|
||
- 遵循组件设计原则
|
||
- 实现完整的测试覆盖
|
||
|
||
2. **用户体验**
|
||
- 实现撤销/重做功能
|
||
- 支持键盘快捷键
|
||
- 添加操作引导
|
||
|
||
3. **可扩展性**
|
||
- 支持自定义节点
|
||
- 支持自定义连线样式
|
||
- 预留扩展接口 |