Skip to main content

异步任务组件

异步任务组件（Async）用于把耗时的后续流程放到后台异步执行，让接口提前返回，避免调用方长时间等待。

概述​

当一个接口后的流程包含批量处理、报表生成等耗时操作时，同步执行会阻塞用户操作。异步任务组件插入流程后，其之后的节点转入后台执行，接口在到达该组件时即可返回，任务在后台继续运行。

异步任务支持两种执行模式：

模式值（AsyncMode）说明
后台执行Background后续流程在后台静默执行，不展示进度
进度执行Progress后续流程在后台执行，并向用户展示执行进度

选择「进度执行」时可额外填写任务名称（TaskName），作为进度提示的标题；留空时使用通用名称。

组件位置

异步任务只有出现在流程中才生效，通常放在「开始」之后、耗时业务组件之前。它属于高级组件分类（Senior），在接口画布的高级组件分组中，不在基础组件分组。

配置项​

配置项说明
执行模式（AsyncMode）后台执行 / 进度执行
任务名称（TaskName）仅「进度执行」模式显示，作为进度标题，可空

执行流程​

使用场景​

  • 数据批量导入/导出
  • 报表生成
  • 数据同步
  • 批量消息发送

下一步​

属性明细​

以下内容面向技术实现与 AI 检索，说明异步任务组件的节点元数据。

节点元数据​

异步任务组件由 FlowCmpType.Async 标识：

属性名类型含义取值/存储值
typestring组件类型固定为 "Async"
AsyncModestring执行模式"Background"（缺省）/ "Progress"
TaskNamestring任务名称进度执行模式下的标题，可空
orderstring同级排序例："2"

元数据存储示例​

{
  "ID": "async1",
  "type": "Async",
  "AsyncMode": "Progress",
  "TaskName": "批量生成报表",
  "order": "2"
}

服务端执行逻辑​

异步任务组件由 AsyncComponentManager（继承 InterfaceComponentManagerBase）实现，组件类型为 FlowComponentTypeEnum.Async。

节点 meta 中的所有值均以字符串存储，服务端统一通过 SafeGet("Key") 读取字符串后再按需转换类型。

执行时机与场景​

当接口流程执行到异步任务节点时触发。若当前上下文已被异步任务接管（context.TinyTaskContext != null），说明该链路已在后台任务中运行，组件不再重复入队，直接同步执行下游。

输入参数（meta 键）​

键读取方式含义
AsyncModemeta.SafeGet("AsyncMode")"Progress" 表示进度模式；其余值（含缺省）按后台模式处理
TaskNamemeta.SafeGet("TaskName")进度模式任务名称，空白时使用本地化默认名
IsDisabledmeta.SafeGet("IsDisabled") == "true"为 true 时跳过本组件，直接执行下游

执行步骤​

  1. 读取 AsyncMode。
  2. 若 context.TinyTaskContext != null，直接调用 ExecuteNextAsync 执行下游并结束。
  3. 进度模式（AsyncMode == "Progress"）：
    • TaskName 为空时取本地化默认任务名；
    • 调用 ITinyTaskHelper.StartTask(taskName, taskContext => { context.TinyTaskContext = taskContext; return ExecuteNextAsync(context); })，把下游链路作为后台任务入队；
    • 返回新上下文 new ComponentContext { InterfaceId = context.InterfaceId, Result = ResponseResult.Success() }，并把 Result.taskId 设为任务 Id。
  4. 后台模式（缺省或其它值）：调用 _ = ExecuteNextBackgroundAsync(context) 触发即忘（fire-and-forget）后台执行，立即返回 ResponseResult.Success()。

后台任务的入队由 TinyTaskHelper.StartTask 完成：先将 TinyTaskInfo（含任务 Id）以 TinyTask_{taskId} 为键写入缓存（6 小时过期），序列化当前 ChameleonContext，随后在 Task.Run 新建的 DI Scope 中还原上下文并执行 taskAction；任务进度通过 TinyTaskContext.UpdateProgress / Complete / CompleteWithError 回写。

输出与上下文​

  • 返回的上下文使用新的 ComponentContext（仅带 InterfaceId 与 Result），避免与后台线程共享同一上下文。
  • 进度模式下 Result.taskId 为后台任务 Id，调用方可用它查询进度。
  • 后台线程中的下游组件仍在原 context 上写入 CmpResult、Result、DicParam。
  • ExecuteNextAsync 在 TinyTaskContext 存在时会以 context.TinyTaskContext.ServiceProvider 覆盖 ServiceProvider，保证后台链路使用同一容器。

权限、安全与限制​

  • 组件自身不做权限校验，也不使用 IsFinalResult。
  • 后台模式下的异常不会抛给调用方，仅记录错误日志（含 TenantId / UserId / InterfaceId）。
  • 任务信息缓存有效期为 6 小时。
  • 框架级限制：链路递归深度超过 100 会抛出异常。

异常与校验​

  • 校验期仅调用 VerifyNextAsync，不校验 AsyncMode / TaskName。
  • 下游节点缺失由 GetNextList 抛出异常。