工作流协议 on Dapr 文档库

Workflow 协议 - 管理 API

Mon, 01 Jan 0001 00:00:00 +0000

Workflow 管理 API

Workflow 管理 API 允许 Dapr 客户端控制 workflow 实例的生命周期。这些 API 通过标准 Dapr gRPC 端点公开，通常通过 SDK 提供。

gRPC 服务定义

管理 API 是 dapr.proto.runtime.v1 中 Dapr 服务的一部分。虽然可能存在多个版本（Alpha1、Beta1），以下描述的是当前的实现逻辑。

StartWorkflow

启动一个新的 workflow 实例。

请求（StartWorkflowRequest）：

字段	类型	描述
`instance_id`	`string`	可选。workflow 实例的唯一标识符。如果未提供，Dapr 将生成一个随机的 UUID。
`workflow_component`	`string`	要使用的 workflow 组件的名称。目前，Dapr 使用内置引擎。
`workflow_name`	`string`	要执行的 workflow 定义的名称。
`options`	`map<string, string>`	可选。组件特定选项。
`input`	`bytes`	可选。workflow 实例的输入数据，通常是 JSON 序列化字符串。

响应（StartWorkflowResponse）：

字段	类型	描述
`instance_id`	`string`	已启动的 workflow 实例的 ID。

GetWorkflow

检索 workflow 实例的当前状态和元数据。

Workflow Protocol - Execution API

Mon, 01 Jan 0001 00:00:00 +0000

Workflow Execution API (Task Hub Protocol)

Workflow Execution API 是一个低级 gRPC 协议，Dapr Workflow SDK 通过它充当"Worker"。SDK 通过此协议连接 Dapr sidecar 以轮询任务并报告完成状态。

该服务名为 TaskHubSidecarService。

Service Definition (gRPC)

service TaskHubSidecarService {
 rpc GetWorkItems(GetWorkItemsRequest) returns (stream WorkItem);
 rpc CompleteOrchestratorTask(OrchestratorResponse) returns (CompleteBatchResponse);
 rpc CompleteActivityTask(ActivityResponse) returns (CompleteBatchResponse);
 // ... other management methods
}

Worker 生命周期

连接：SDK 打开一个到 GetWorkItems 的长连接双向流。
轮询：SDK 从流中接收 WorkItem 消息。
执行：
- 如果工作项是 Orchestration，SDK 获取并重放历史事件以确定下一步操作。
- 如果工作项是 Activity，SDK 执行活动逻辑。
完成：
- 对于 Orchestration，SDK 调用 CompleteOrchestratorTask 并附带要执行的操作列表。
- 对于 Activity，SDK 调用 CompleteActivityTask 并附带结果或失败信息。

gRPC Service: `TaskHubSidecarService`

GetWorkItems

打开流以接收 orchestration 和 activity 的工作项。

Workflow Protocol - Orchestration Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

编排生命周期

本文档从协议层面描述编排的生命周期，特别是 Dapr 引擎与 SDK 如何交互以可靠地执行工作流逻辑。

基于重放的执行

Dapr Workflow 使用 事件溯源 和重放来维护状态。Dapr 不是保存整个 worker 进程的状态（栈、变量等），而是保存已发生事件的历史记录。

重放循环

工作项到达：Dapr 引擎通过 GetWorkItems 流向 SDK 发送一个 OrchestratorWorkItem。该工作项包含工作流实例的完整历史记录以及任何新事件（例如，activity 完成或外部事件）。
重建：SDK 从头开始执行编排函数。
确定性执行：随着函数的执行，它会遇到"任务"（例如，调用 activity、休眠）。
- 对于每个任务，SDK 会检查提供的 History 以查看该任务是否已完成。
- 如果任务在历史记录中，SDK 会立即返回记录的结果，而无需实际重新执行任务逻辑。
- 如果任务不在历史记录中，SDK 会记录该任务需要被调度并暂停编排函数的执行（通常通过抛出特殊异常或返回待处理的 promise）。
报告：一旦编排函数被暂停或完成，SDK 会向 Dapr 发送 CompleteOrchestratorTask 请求。该请求包含引擎应执行的一系列 Actions（例如 ScheduleTask、CreateTimer）。
状态提交：Dapr 引擎接收这些操作，在状态存储中更新工作流历史记录，并调度任何请求的任务（例如，通过向 activity worker 发送工作）。

分步示例

假设一个工作流：Activity A -> Activity B。

1. 工作流启动

引擎：将 ExecutionStarted 事件加入队列。
SDK：接收包含 [ExecutionStarted] 的 OrchestratorWorkItem。
SDK：运行函数。函数调用 Activity A。
SDK：检查历史记录。Activity A 不在其中。
SDK：暂停。发送包含 [ScheduleTask(Activity A)] 的 CompleteOrchestratorTask。
引擎：在历史记录中记录 TaskScheduled(Activity A)。

2. Activity A 完成

引擎：在历史记录中记录 TaskCompleted(Activity A, result="foo")。
SDK：接收包含 [ExecutionStarted, TaskScheduled(A), TaskCompleted(A)] 的 OrchestratorWorkItem。
SDK：从头开始运行函数。
SDK：函数调用 Activity A。SDK 在历史记录中找到 TaskCompleted(A)。返回 "foo"。
SDK：函数调用 Activity B。
SDK：检查历史记录。Activity B 不在其中。
SDK：暂停。发送包含 [ScheduleTask(Activity B)] 的 CompleteOrchestratorTask。
引擎：记录 TaskScheduled(Activity B)。

3. 工作流完成

Activity B 完成。
SDK：接收包含 A 和 B 都已完成的历史记录。
SDK：运行函数。A 和 B 都从历史记录返回结果。
SDK：函数完成并返回最终结果。
SDK：发送包含 [CompleteOrchestration(result="final")] 的 CompleteOrchestratorTask。
引擎：记录 OrchestrationCompleted 并将实例标记为 COMPLETED。

SDK 作者的关键要求

1. 确定性

编排函数必须是确定性的。它不能使用：

Workflow Protocol - Activity Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Activity 生命周期

Activity 是 Dapr Workflow 中的基本工作单元。与编排不同，Activity 不会重放，也不需要具有确定性。它们每次"调度"仅执行一次（尽管可能会发生重试）。

执行流程

调度：编排通过向 Dapr 引擎发送 ScheduleTask 操作来请求一个 Activity。
工作项分发：Dapr 引擎将 Activity 任务加入队列。当 Activity worker（SDK）可用时，引擎通过 GetWorkItems 流发送一个 ActivityWorkItem。
执行：SDK 接收 ActivityWorkItem，其中包含：
- name：要执行的 Activity 的名称。
- input：Activity 的输入数据。
- instance_id：调度该 Activity 的工作流实例的 ID。
- task_id：此特定 Activity 执行的唯一标识符。
- task_execution_id：此特定 Activity 的特定尝试的唯一标识符。这对于在 Activity 逻辑中实现幂等性很有用。
- completion_token：一个不透明 token，用于将响应与此特定工作项关联。
报告：Activity 逻辑完成后，SDK 向 Dapr 发送 CompleteActivityTask 请求。
- 成功：SDK 在 result 字段中提供序列化输出。
- 失败：SDK 提供 failure_details（错误消息、类型、堆栈跟踪）。

Task Execution ID

task_execution_id（也称为 Task Execution Key）是一个唯一的、运行时生成的字符串（通常是 UUID），用于标识执行 Activity 任务的特定尝试。

Workflow Protocol - State & History

Mon, 01 Jan 0001 00:00:00 +0000

状态和历史管理

Dapr Workflows 采用事件溯源模式，这意味着工作流的状态是从一系列事件中推导出来的。本文档描述了 Dapr 如何存储和管理这些历史记录和状态。

后端存储：Dapr Actors

默认情况下，Dapr Workflow 引擎使用 Dapr Actors 作为其存储后端。每个工作流实例都映射到一个唯一的 actor 实例。这提供了以下特性：

并发控制：Actors 确保在任意时刻只有一个操作在处理工作流实例。
可靠性：Actor 状态会持久化到配置好的 Dapr 状态存储中。
定时器：Dapr Actors 提供持久化提醒，用于实现工作流定时器。

工作流状态架构

工作流实例（actor）的状态由以下几个组件构成：

1. 元数据

存储有关该实例的高级信息：

instance_id：工作流的唯一 ID。
name：工作流的名称。
status：当前运行时状态（如 Running、Completed、Stalled 等）。
version：工作流版本的名称及任何活跃的补丁。
created_at：创建时间戳。
last_updated_at：最后活动时间戳。
input：原始输入数据。
output：最终输出数据（如已完成的）。

2. 历史记录

一系列 HistoryEvent 对象，记录工作流中发生的所有事件。为了优化大型历史记录，Dapr 通常将历史事件以分块或单独键值的形式存储在状态存储中：

键格式：wf-history-<instance_id>-<index>
事件内容：序列化的 protobuf 消息，包含事件类型、时间戳以及类型特定的数据（如 TaskScheduled、TaskCompleted）。

3. 收件箱（待处理事件）

已发生但尚未被编排器处理（重放）的事件集合。包括：

向工作流引发的外部事件。
已完成的 activity 结果。
已触发的定时器。

当编排器下次运行时，它会"排空"收件箱，将这些事件移入历史记录，然后重放逻辑。

重放与状态重建

当 Worker（SDK）收到工作项时，Dapr 提供历史事件。SDK 通过按顺序重放这些事件来重建编排的内部状态（例如本地变量、当前执行点）。

确定性原则与历史记录

历史记录是"真相的来源"。如果编排代码以非确定性的方式发生变化（例如在现有代码中间添加新的 activity 调用），重放将失败，因为代码的请求将与记录的历史记录不匹配。

工作流协议 - 版本控制

Mon, 01 Jan 0001 00:00:00 +0000

工作流版本控制

Dapr 工作流支持工作流定义的版本控制，允许你在现有实例继续运行其原始逻辑的同时更新工作流逻辑。

命名工作流版本控制

向 Dapr 引擎注册工作流时，你可以提供版本名称。这允许同一工作流的多个版本共存。

默认版本：一个工作流版本可被标记为默认版本。如果客户端仅通过名称启动工作流而不指定版本，则使用默认版本。
特定版本：客户端可以在启动新实例时请求工作流的特定版本。

注册 API

SDK 使用其任务注册表中的 AddVersionedOrchestrator（或类似）方法来注册版本化工作流。

// 示例（内部注册表 API）
registry.AddVersionedOrchestrator("MyWorkflow", "v2", true, MyWorkflowV2)
registry.AddVersionedOrchestrator("MyWorkflow", "v1", false, MyWorkflowV1)

边车版本控制

Dapr 边车会跟踪实例正在运行的工作流命名版本，以及在该工作流执行过程中已应用的补丁列表。此信息存储在工作流历史记录中，位于 OrchestratorStarted 事件的 version 字段内。

message OrchestrationVersion {
 string name = 1;
 repeated string patches = 2;
}

当实例恢复时（例如，在某个活动完成后），Dapr 引擎负责处理因客户端版本不匹配而导致的停滞。它通过监控 placement 表的变化来实现这一点，这表明有新的 SDK 客户端已连接（可能代表应用程序的较新副本实例），并调度重放最后一个事件以尝试重试该操作。这一次，如果 SDK 能够成功完成任务，运行时将把工作流状态从 Stalled 更改回 Running。

工作流协议 on Dapr 文档库

Workflow 协议 - 管理 API

Workflow 管理 API

gRPC 服务定义

StartWorkflow

GetWorkflow

Workflow Protocol - Execution API

Workflow Execution API (Task Hub Protocol)

Service Definition (gRPC)

Worker 生命周期

gRPC Service: TaskHubSidecarService

GetWorkItems

Workflow Protocol - Orchestration Lifecycle

编排生命周期

基于重放的执行

重放循环

分步示例

1. 工作流启动

2. Activity A 完成

3. 工作流完成

SDK 作者的关键要求

1. 确定性

Workflow Protocol - Activity Lifecycle

Activity 生命周期

执行流程

Task Execution ID

Workflow Protocol - State & History

状态和历史管理

后端存储：Dapr Actors

工作流状态架构

1. 元数据

2. 历史记录

3. 收件箱（待处理事件）

重放与状态重建

确定性原则与历史记录

工作流协议 - 版本控制

工作流版本控制

命名工作流版本控制

注册 API

边车版本控制

gRPC Service: `TaskHubSidecarService`