Do While 任务
Do While 是 Taskflow 中的高级控制流任务,实现了循环执行逻辑。它允许基于条件表达式重复执行一组任务,直到条件不再满足为止。这种任务特别适用于需要迭代处理的场景,如批量数据处理、分页API调用等。
核心特性
条件评估
- 支持多种评估器类型
- 灵活的条件表达式配置
- 动态迭代控制
执行模式
- 先执行后评估(do-while 语义)
- 支持迭代计数和限制
- 自动任务引用名称管理
数据处理
- 支持列表迭代
- 迭代状态维护
- 完整的执行历史记录
任务参数
参数 | 描述 | 必需/可选 |
---|---|---|
evaluatorType | 条件评估器类型: - value-param : 评估指定输入参数 - graaljs : 使用 ES6 兼容的 JavaScript 表达式 | 必需 |
loopCondition | 循环继续条件: - value-param: 参数键名 - graaljs: JavaScript 条件表达式 | 必需 |
loopOver | 循环体中要执行的任务列表 | 必需 |
inputParameters.keepLastN | 保留最近 N 次迭代的结果。默认值为 2。设置为 0 表示保留所有迭代结果。 | 可选 |
inputParameters.items | 用于列表迭代模式的数组。迭代次数等于数组长度。 | 可选 |
执行语义
迭代命名规则
- 任务引用名称格式:
{taskReferenceName}__{iterationNumber}
- 迭代编号从 1 开始递增
- 失败重试时迭代从 1 重新开始
- 任务引用名称格式:
状态管理
- 每次迭代的状态独立维护
- 支持迭代间数据传递
- 提供迭代计数器访问
条件评估
- 每次迭代后进行条件检查
- 支持复杂逻辑表达式
- 可访问当前迭代状态
配置示例
基本配置
{
"name": "do_while",
"taskReferenceName": "do_while_ref",
"type": "DO_WHILE",
"inputParameters": {
"value": "${workflow.input.value}"
},
"evaluatorType": "graaljs",
"loopCondition": "(function(){ return $.value < 10; })();",
"loopOver": [
{
"name": "http_task",
"taskReferenceName": "http_task_ref",
"type": "HTTP",
"inputParameters": {
"http_request": {
"uri": "https://www.taskflow.cn/api",
"method": "POST",
"body": {
"iteration": "${do_while_ref.output.iteration}"
}
}
}
}
]
}
列表迭代模式
{
"name": "do_while",
"taskReferenceName": "do_while_ref",
"type": "DO_WHILE",
"inputParameters": {
"items": ["a", "b", "c"]
},
"evaluatorType": "value-param",
"loopOver": [
{
"name": "process_item",
"taskReferenceName": "process_item_ref",
"type": "SIMPLE",
"inputParameters": {
"item": "${do_while_ref.output.item}"
}
}
]
}
最佳实践
性能优化
- 使用 keepLastN 限制历史数据
- 避免过于复杂的条件表达式
- 合理设置迭代上限
错误处理
- 实现适当的重试策略
- 处理边界条件
- 监控迭代计数
数据管理
- 谨慎使用大型数据结构
- 及时清理临时数据
- 使用变量引用而非硬编码
使用限制
结构限制
- 不支持嵌套 Do While
- 分支任务需在循环范围内完成
- 不支持隔离组执行
性能考虑
- 建议限制最大迭代次数
- 注意内存使用
- 考虑任务超时设置
错误处理
- 条件评估错误导致 FAILED_WITH_TERMINAL_ERROR
- 迭代执行失败触发重试机制
- 支持自定义错误处理策略
UI 配置指南
- 添加 Do While 任务
- 配置评估器类型和条件
- 添加循环体任务
- 设置迭代限制(可选)
- 配置错误处理策略
任务输出
Do While 任务将返回以下参数。
参数 | 描述 |
---|---|
iteration | 迭代次数。如果 Do While 任务正在进行中,iteration 将显示当前迭代编号。如果 Do While 任务已完成,iteration 将显示最终迭代次数。 |
此外,将为每次迭代创建一个对象,以其迭代编号(例如 1、2、3)为键,并包含所有循环任务的任务引用名称及其输出。
输出负载还可能包含 loopCondition
中存储的任何状态。例如,如果 loopCondition
是 if ($.LoopTask['iteration'] <= 10) {$.LoopTask.storage = 3; true } else {false}
,则 storage
将作为输出参数存在。
示例输出
{
"1": {
"taskA_ref": {
"response": {
"headers": {},
"body": {},
"statusCode": 200
}
},
"taskB_ref": {
//taskBOutput
}
},
"2": {
"taskA_ref": {
"response": {
"headers": {},
"body": {},
"statusCode": 200
}
},
"taskB_ref": {
//taskBOutput
}
},
"iteration": 2
}
访问 Do While 任务输出
每次完成 do while 循环中的任务时,输出都会被保存并按迭代值索引。这使得条件可以使用 $.TaskName[’iteration’]['loopTask']
检查特定任务迭代的输出,将 TaskName
替换为实际的 Do While 任务引用名称,将 loopTask
替换为循环任务引用名称。
在 UI 中添加 Do While 任务
添加 Do While 任务的步骤:
在工作流中,选择 (+) 图标并添加 Do While 任务。
在 Script params 中,添加将在表达式中评估的参数。
在 Loop condition 中,选择评估器类型并输入循环条件。
- Value-Param—确保表达式值与您在 Script params 中定义的参数键匹配。
- ECMASCRIPT—输入 JavaScript 脚本。
在工作流中,选择 (+) 图标以向 do while 循环添加任务。
(可选)通过取消选中 No Limits 来设置所需的迭代次数。默认情况下,迭代次数没有限制。
示例
以下是使用 Do While 任务的一些示例。
使用 `graaljs` 评估器
{
"name": "do_while",
"taskReferenceName": "do_while_ref",
"inputParameters": {
"number": "${workflow.input.qty}"
},
"type": "DO_WHILE",
"loopCondition": "(function () {\n if ($.do_while_ref['iteration'] < $.number) {\n return true;\n }\n return false;\n})();",
"loopOver": [
{
"name": "first task",
"taskReferenceName": "first_task",
"inputParameters": {
"http_request": {
"uri": "https://www.taskflow.cn/api",
"method": "POST"
}
},
"type": "HTTP"
},
{
"name": "second task",
"taskReferenceName": "second_task",
"inputParameters": {
"http_request": {
"uri": "https://www.taskflow.cn/api",
"method": "POST"
}
},
"type": "HTTP"
}
]
"evaluatorType": "graaljs"
}
成功执行后,假设发生了三次迭代,上述 Do While 任务将产生以下执行 JSON:
{
"taskType": "DO_WHILE",
"outputData": {
"iteration": 3,
"1": {
"first_task": {
"response": {},
"headers": {
"Content-Type": "application/json"
}
},
"second_task": {
"response": {},
"headers": {
"Content-Type": "application/json"
}
}
},
"2": {
"first_task": {
"response": {},
"headers": {
"Content-Type": "application/json"
}
},
"second_task": {
"response": {},
"headers": {
"Content-Type": "application/json"
}
}
},
"3": {
"first_task": {
"response": {},
"headers": {
"Content-Type": "application/json"
}
},
"second_task": {
"response": {},
"headers": {
"Content-Type": "application/json"
}
}
}
}
}
在循环任务中使用迭代键
有时,您可能希望在循环任务中使用 Do While 迭代值/计数器。在此示例中,对 GitHub 存储库进行 API 调用以获取所有标星者,每次迭代都会增加分页。
Do While 任务的 taskReferenceName
是 "get_all_stars_loop_ref"。要评估当前迭代,在 loopCondition
中使用参数 $.get_all_stars_loop_ref['iteration']
。在嵌入循环的 HTTP 任务中,使用 ${get_all_stars_loop_ref.output.iteration}
来定义 API 应返回的结果页面。
{
"name": "get_all_stars",
"taskReferenceName": "get_all_stars_loop_ref",
"inputParameters": {
"stargazers": "4000"
},
"type": "DO_WHILE",
"loopCondition": "if ($.get_all_stars_loop_ref['iteration'] < Math.ceil($.stargazers/100)) { true; } else { false; }",
"loopOver": [
{
"name": "100_stargazers",
"taskReferenceName": "hundred_stargazers_ref",
"inputParameters": {
"counter": "${get_all_stars_loop_ref.output.iteration}",
"http_request": {
"uri": "https://www.taskflow.cn/api",
"method": "GET",
"headers": {
"Authorization": "token ${workflow.input.gh_token}",
"Accept": "application/vnd.github.v3.star+json"
}
}
},
"type": "HTTP"
}
]
}
迭代项目列表
可以迭代项目列表。要迭代列表,Do-While 任务必须有一个专门命名为 'items' 的输入参数,其中包含要处理的集合。参数名称 'items' 是必需的,不能替换为其他名称。
迭代次数将等于列表大小。如果 "items"=["a","b","c"]
,循环任务将执行三次;如果 "items"=[]
,Do While 任务将被标记为完成而不执行循环任务。
列表中的每个项目都使用 ${do_while_ref.output.item}
传递到循环任务的每次迭代中。
{
"name": "do_while",
"taskReferenceName": "do_while_ref",
"inputParameters": {
"items": ["a", "b", "c"]
},
"type": "DO_WHILE",
"loopCondition": "",
"loopOver": [
{
"name": "http",
"taskReferenceName": "http_ref",
"inputParameters": {
"uri": "https://www.taskflow.cn/api",
"method": "GET",
"accept": "application/json",
"contentType": "application/json",
"encode": true,
"body": {
"item": "${do_while_ref.output.item}"
},
"headers": {}
},
"type": "HTTP"
}
],
"evaluatorType": "value-param"
}
限制
Do While 任务有几个限制:
- 分支—在 Do While 任务中,支持使用 Switch、Fork/Join、Dynamic Fork 任务进行分支。但是,如果分支超出其范围,Do While 任务可能不会按预期执行,因为循环任务将在范围内执行。
- 嵌套循环—不支持嵌套的 Do While 任务。要实现类似于嵌套 do while 循环的功能,可以在 Do While 任务中使用子工作流任务。
- 隔离组执行—不支持隔离组执行。但是,Do While 任务中的循环任务支持域。
错误
如果在评估 loopCondition
期间发生异常,任务将设置为 FAILED_WITH_TERMINAL_ERROR
。