ai-coding/deploy-ease-platform

Fork 0

dengqichen ac4626e0c3 需要重写工作流相关的页面功能

2024-12-05 18:18:01 +08:00

14 KiB

Raw Blame History

API 接口文档

1. 通用说明

1.1 接口规范

基础路径: /api/v1
请求方式: REST风格
数据格式: JSON
字符编码: UTF-8
时间格式: ISO8601 (YYYY-MM-DDTHH:mm:ss.SSSZ)

1.2 通用响应格式

{
  "code": 0,           // 响应码，0表示成功，非0表示失败
  "message": "成功",    // 响应消息
  "data": {            // 响应数据
    // 具体数据结构
  }
}

1.3 通用查询参数

分页查询参数：

{
  "page": 1,           // 页码，从1开始
  "size": 10,          // 每页大小
  "sort": ["id,desc"], // 排序字段，可选
  "keyword": "",       // 关键字搜索，可选
}

1.4 通用错误码

错误码	说明	处理建议
0	成功	-
1000	系统内部错误	联系管理员
1001	数据库操作失败	重试或联系管理员
1002	并发操作冲突	刷新后重试
2000	参数验证失败	检查参数
2001	数据不存在	检查参数
2002	数据已存在	检查参数

2. 工作流定义<E5AE9A><E4B989>口

2.1 创建工作流定义

接口说明：创建新的工作流定义

请求路径：POST /workflow-definitions

请求参数：

{
  "code": "string",          // 工作流编码，必填，唯一
  "name": "string",          // 工作流名称，必填
  "description": "string",   // 描述，可选
  "nodeConfig": {            // 节点配置，必填
    "nodes": [{
      "id": "string",       // 节点ID
      "type": "string",     // 节点类型
      "name": "string",     // 节点名称
      "config": {           // 节点配置
        // 具体配置项根据节点类型定义
      }
    }]
  },
  "transitionConfig": {      // 流转配置，必填
    "transitions": [{
      "from": "string",     // 来源节点ID
      "to": "string",       // 目标节点ID
      "condition": "string" // 流转条件
    }]
  },
  "formDefinition": {        // 表单定义，必填
    // 表单配置项
  },
  "graphDefinition": {       // 图形定义，必填
    // 图形布局配置
  }
}

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": {
    "id": "long",           // 工作流定义ID
    "code": "string",       // 工作流编码
    "name": "string",       // 工作流名称
    "description": "string", // 描述
    "version": 1,           // 版本号
    "status": "DRAFT",      // 状态：DRAFT-草稿、PUBLISHED-已发布、DISABLED-已禁用
    "enabled": true,        // 是否启用
    "nodeConfig": {},       // 节点配置
    "transitionConfig": {}, // 流转配置
    "formDefinition": {},   // 表单定义
    "graphDefinition": {},  // 图形定义
    "createTime": "string", // 创建时间
    "updateTime": "string"  // 更新时间
  }
}

2.2 更新工作流定义

接口说明：更新工作流定义，仅草稿状态可更新

请求路径：PUT /workflow-definitions/{id}

路径参数：

id: 工作流定义ID

请求参数：同创建接口

响应数据：同创建接口

2.3 发布工作流定义

接口说明：发布工作流定义，使其可被使用

请求路径：POST /workflow-definitions/{id}/publish

路径参数：

id: 工作流定义ID

响应数据：同创建接口

2.4 禁用工作流定义

接口说明：禁用工作流定义，禁止新建实例

请求路径：POST /workflow-definitions/{id}/disable

路径参数：

id: 工作流定义ID

响应数据：同创建接口

2.5 启用工作流定义

接口说明：启用已<EFBFBD><EFBFBD>用的工作流定义

请求路径：POST /workflow-definitions/{id}/enable

路径参数：

id: 工作流定义ID

响应数据：同创建接口

2.6 创建新版本

接口说明：基于现有工作流定义创建新版本

请求路径：POST /workflow-definitions/{id}/versions

路径参数：

id: 工作流定义ID

响应数据：同创建接口

2.7 查询工作流定义列表

接口说明：分页查询工作流定义列表

请求路径：GET /workflow-definitions

请求参数：

{
  "page": 1,           // 页码，从1开始
  "size": 10,          // 每页大小
  "sort": ["id,desc"], // 排序字段
  "keyword": "",       // 关键字搜索
  "status": "DRAFT",   // 状态过滤
  "enabled": true      // 是否启用
}

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": {
    "content": [{      // 列表数据
      // 工作流定义数据，同创建接口
    }],
    "totalElements": 100, // 总记录数
    "totalPages": 10,    // 总页数
    "size": 10,         // 每页大小
    "number": 1         // 当前页码
  }
}

3. 工作流实例接口

3.1 创建工作流实例

接口说明：创建工作流实例

请求路径：POST /workflow-instances

请求参数：

{
  "definitionId": "long",    // 工作流定义ID，必填
  "businessKey": "string",   // 业务标识，可选
  "variables": {             // 初始变量，可选
    "key": "value"
  }
}

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": {
    "id": "long",           // 实例ID
    "definitionId": "long", // 定义ID
    "businessKey": "string",// 业务标识
    "status": "CREATED",    // 状态：CREATED-已创建、RUNNING-运行中、SUSPENDED-已暂停、COMPLETED-已完成、TERMINATED-已终止
    "startTime": "string",  // 开始时间
    "endTime": "string",    // 结束时间
    "variables": {},        // 变量
    "createTime": "string", // 创建时间
    "updateTime": "string"  // 更新时间
  }
}

3.2 启动工作流实例

接口说明：启动工作流实例

请求路径：POST /workflow-instances/{id}/start

路径参数：

id: 实例ID

响应数据：同创建接口

3.3 暂停工作流实例

接口说明：暂停运行中的工作流实例

请求路径：POST /workflow-instances/{id}/suspend

路径参数：

id: 实例ID

响应数据：同创建接口

3.4 恢复工作流实例

接口说明：恢复已暂停的工作流实例

请求路径：POST /workflow-instances/{id}/resume

路径参数：

id: 实例ID

响应数据：同创建接口

3.5 终止工作流实例

接口说明：强制终止工作流实例

请求路径：POST /workflow-instances/{id}/terminate

路径参数：

id: 实例ID

响应数据：同创建接口

3.6 查询工作流实例列表

接口说明：分页查询工作流实例列表

请求路径：GET /workflow-instances

请求参数：

{
  "page": 1,           // 页码，从1开始
  "size": 10,          // 每页大小
  "sort": ["id,desc"], // 排序字段
  "keyword": "",       // 关键字搜索
  "status": "RUNNING", // 状态过滤
  "definitionId": "long", // 定义ID过滤
  "businessKey": "string" // 业务标识过滤
}

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": {
    "content": [{      // 列表数据
      // 工作流实例数据，同创建接口
    }],
    "totalElements": 100, // 总记录数
    "totalPages": 10,    // 总页数
    "size": 10,         // 每页大小
    "number": 1         // 当前页码
  }
}

4. 节点实例接口

4.1 查询节点实例列表

接口说明：查询工作流实例的节点列表

请求路径：GET /workflow-instances/{instanceId}/nodes

路径参数：

instanceId: 工作流实例ID

请求参数：

{
  "status": "RUNNING" // 状态过滤，可选
}

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": [{
    "id": "long",           // 节点实例ID
    "workflowInstanceId": "long", // 工作流实例ID
    "nodeId": "string",     // 节点定义ID
    "nodeName": "string",   // 节点名称
    "nodeType": "string",   // 节点类型
    "status": "string",     // 状态：CREATED、RUNNING、COMPLETED、FAILED
    "startTime": "string",  // 开始时间
    "endTime": "string",    // 结束时间
    "output": "string",     // 输出结果
    "error": "string",      // 错误信息
    "createTime": "string", // 创建时间
    "updateTime": "string"  // 更新时间
  }]
}

5. 工作流变量接口

5.1 设置变量

接口说明：设置工作流实例变量

请求路径：POST /workflow-instances/{instanceId}/variables

路径参数：

instanceId: 工作流实例ID

请求参数：

{
  "name": "string",    // 变量名，必填
  "value": "object",   // 变量值，必<EFBC8C><E5BF85>
  "scope": "GLOBAL"    // 作用域：GLOBAL-全局、NODE-节点，可选，默认GLOBAL
}

响应数据：

{
  "code": 0,
  "message": "成功"
}

5.2 获取变量

接口说明：获取工作流实例变量

请求路径：GET /workflow-instances/{instanceId}/variables

路径参数：

instanceId: 工作流实例ID

请求参数：

{
  "scope": "GLOBAL" // 作用域过滤，可选
}

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": {
    "variableName": "variableValue"
  }
}

6. 工作流日志接口

6.1 查询日志列表

接口说明：查询工作流实例日志

请求路径：GET /workflow-instances/{instanceId}/logs

路径参数：

instanceId: 工作流实例ID

请求参数：

{
  "nodeId": "string",  // 节点ID过滤，可选
  "level": "INFO",     // 日志级别过滤：DEBUG、INFO、WARN、ERROR，可选
  "startTime": "string", // 开始时间过滤，可选
  "endTime": "string"   // 结束时间过滤，可选
}

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": [{
    "id": "long",           // 日志ID
    "workflowInstanceId": "long", // 工作流实例ID
    "nodeId": "string",     // 节点ID
    "level": "string",      // 日志级别
    "content": "string",    // 日志内容
    "detail": "string",     // 详细信息
    "createTime": "string"  // 创建时间
  }]
}

7. 节点类型接口

7.1 查询节点类型列表

接口说明：查询可用的节点类型列表

请求路径：GET /node-types

请求参数：

{
  "enabled": true,     // 是否启用过滤，可选
  "category": "TASK"   // 类型分类过滤：TASK、EVENT、GATEWAY，可选
}

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": [{
    "id": "long",           // 节点类型ID
    "code": "string",       // 节点类型编码
    "name": "string",       // 节点类型名称
    "category": "string",   // 分类
    "description": "string", // 描述
    "enabled": true,        // 是否启用
    "icon": "string",       // 图标
    "color": "string",      // 颜色
    "executors": [{         // 执行器列表（仅TASK类型）
      "code": "string",     // 执行器编码
      "name": "string",     // 执行器名称
      "description": "string", // 描述
      "configSchema": {}    // 配置模式
    }],
    "createTime": "string", // 创建时间
    "updateTime": "string"  // 更新时间
  }]
}

7.2 获取节点执行器列表

接口说明：获取指定节点类型支持的执行器列表

请求路径：GET /node-types/{code}/executors

路径参数：

code: 节点类型编码

响应数据：

{
  "code": 0,
  "message": "成功",
  "data": [{
    "code": "string",      // 执行器编码
    "name": "string",      // 执行器名称
    "description": "string", // 描述
    "configSchema": {      // 配置模式
      "type": "object",
      "properties": {
        // 具体配置项定义
      },
      "required": []       // 必填项
    }
  }]
}

8. 错误码说明

8.1 系统错误 (1xxx)

1000: 系统内部错误
1001: 数据库操作失败
1002: 并发操作冲突

8.2 通用业务错误 (2xxx)

2000: 参数验证失败
2001: 数据不存在
2002: 数据已存在

8.3 工作流定义错误 (3xxx)

3000: 工作流定义不存在
3001: 工作流编码已存在
3002: 工作流定义非草稿状态
3003: 工作流定义未发布
3004: 工作流定义已禁用
3005: 节点配置无效
3006: 流转配置无效
3007: 表单配置无效

8.4 工作流实例错误 (4xxx)

4000: 工作流实例不存在
4001: 工作流实例状态无效
4002: 工作流实例已终止
4003: 节点实例不存在
4004: 变量类型无效

9. 数据结构说明

9.1 工作流状态

enum WorkflowStatus {
  DRAFT = "DRAFT",         // 草稿
  PUBLISHED = "PUBLISHED", // 已发布
  DISABLED = "DISABLED"    // 已禁用
}

9.2 实例状态

enum InstanceStatus {
  CREATED = "CREATED",     // 已创建
  RUNNING = "RUNNING",     // 运行中
  SUSPENDED = "SUSPENDED", // 已暂停
  COMPLETED = "COMPLETED", // 已完成
  TERMINATED = "TERMINATED"// 已终止
}

9.3 节点状态

enum NodeStatus {
  CREATED = "CREATED",     // 已创建
  RUNNING = "RUNNING",     // 运行中
  COMPLETED = "COMPLETED", // 已完成
  FAILED = "FAILED"        // 失败
}

9.4 日志级别

enum LogLevel {
  DEBUG = "DEBUG",
  INFO = "INFO",
  WARN = "WARN",
  ERROR = "ERROR"
}

9.5 变量作用域

enum VariableScope {
  GLOBAL = "GLOBAL",       // 全局变量
  NODE = "NODE"           // 节点变量
}

10. 最佳实践

10.1 工作流设计

工作流定义创建流程：
- 创建草稿
- 配置节点和流转
- 验证配置
- 发布使用
节点类型选择：
- 根据业务场景选择合适的节点类型
- 配置合适的执行器
- 设置必要的变量

10.2 实例管理

实例生命周期管理：
- 创建 -> 启动 -> 运行 -> 完成
- 必要时可暂停或终止
- 记录关键节点日志
变量使用：
- 合理使用变量作用域
- 及时清理无用变量
- 注意变量类型匹配

10.3 错误处理

异常处理：
- 捕获所有可能的错误码
- 提供友好的错误提示
- 记录详细的错误日志
重试机制：
- 对非致命错误进行重试
- 设置合理的重试间隔
- 限制最大重试次数

10.4 性能优化

查询优化：
- 合理使用分页
- 避免大量数据查询
- 使用合适的查询条件
缓存使用：
- 缓存常用数据
- 及时更新缓存
- 避免缓存穿透

14 KiB Raw Blame History Unescape Escape

API 接口文档

1. 通用说明

1.1 接口规范

1.2 通用响应格式

1.3 通用查询参数

1.4 通用错误码

2. 工作流定义<E5AE9A><E4B989>口

2.1 创建工作流定义

2.2 更新工作流定义

2.3 发布工作流定义

2.4 禁用工作流定义

2.5 启用工作流定义

2.6 创建新版本

2.7 查询工作流定义列表

3. 工作流实例接口

3.1 创建工作流实例

3.2 启动工作流实例

3.3 暂停工作流实例

3.4 恢复工作流实例

3.5 终止工作流实例

3.6 查询工作流实例列表

4. 节点实例接口

4.1 查询节点实例列表

5. 工作流变量接口

5.1 设置变量

5.2 获取变量

6. 工作流日志接口

6.1 查询日志列表

7. 节点类型接口

7.1 查询节点类型列表

7.2 获取节点执行器列表

8. 错误码说明

8.1 系统错误 (1xxx)

8.2 通用业务错误 (2xxx)

8.3 工作流定义错误 (3xxx)

8.4 工作流实例错误 (4xxx)

9. 数据结构说明

9.1 工作流状态

9.2 实例状态

9.3 节点状态

9.4 日志级别

9.5 变量作用域

10. 最佳实践

10.1 工作流设计

10.2 实例管理

10.3 错误处理

10.4 性能优化

14 KiB

Raw Blame History