# @datarster/workflow-engine 中文文档

规范地址：https://npmcn.com/package/%40datarster/workflow-engine/

版本：0\.0\.21
npm 元数据更新时间：2025-07-14T13:00:17.540Z
中文译文更新时间：2026-11-11T18:15:02.699Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40datarster/workflow-engine
原文对照：https://npmcn.com/package/%40datarster/workflow-engine/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：97.9 kB，27 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2025-02-25T07:29:55.369Z
- 最新版本发布：2025-07-14T13:00:17.315Z
- 近 30 天下载量：5497（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 0 个）

## 中文简介

Workflow引擎是一个强大的工具,旨在自动化和管理复杂的工作流程. 它允许用户轻松地定义,执行并监控工作流程.

## 安装

```sh
npm install @datarster/workflow-engine
```

也可以使用：`pnpm add @datarster/workflow-engine`、`yarn add @datarster/workflow-engine`、`bun add @datarster/workflow-engine`

## README

# 工作流程引擎

## 概览

`@datarster/workflow-engine` 是用于Node.js的强大而可扩展的工作流程管理库。 它能够使用基于JSON的工作流程定义执行工作流程. 此引擎支持相继,平行,有条件,循环,开关等基于事件的工作流程,在出现故障时可选择回滚功能.

## 特征

-   支持各种工作流程步骤类型:任务、决定、平行、循环、等待、承诺、执行 当时 等待和切换.
-   事件驱动的执行,具有工作流程恢复能力.
-   与Redis合并,用于州管理和工作流程缓存.
-   MongoDB 为工作流程执行历史进行记录 .
-   倒转支持失败步骤 与自定义倒转工人.
-   动态工人登记,提供超时支持.
-   有条件执行的切换/大小写逻辑.
-   Redis 和 MongoDB 连接的灵活配置 .

## 安装

```sh
npm install @datarster/workflow-engine
```

## 使用量

### 导入和初始化引擎

```javascript
import { WorkflowEngine } from "@datarster/workflow-engine";

const config = {
    redis: { host: "localhost", port: 6379 },
    useLogging: true,
    mongo: { uri: "mongodb://localhost:27017", database: "workflowDB", collection: "logs" }
};

const engine = new WorkflowEngine();
await engine.init(config);
```

### 定义工作流程

```javascript
const workflow = {
    name: "Order Processing",
    steps: [
        { 
            id: "1", 
            type: "task", 
            name: "Validate Order", 
            worker: "validateOrder",
            workerTimeout: 30000,
            rollback: {
                id: "1_rollback",
                name: "Rollback Validation",
                type: "task",
                worker: "validateOrderRollback"
            }
        },
        { id: "2", type: "task", name: "Process Payment", worker: "processPayment" },
        { id: "3", type: "task", name: "Ship Order", worker: "shipOrder" }
    ]
};

await engine.registerWorkflow("order_processing", workflow);
```

### 登记工人

```javascript
engine.registerWorker("validateOrder", async (data) => {
    console.log("Validating order", data);
    // Your validation logic here
});

engine.registerWorker("validateOrderRollback", async (data) => {
    console.log("Rolling back order validation", data);
    // Your rollback logic here
});

engine.registerWorker("processPayment", async (data) => {
    console.log("Processing payment", data);
    // Your payment logic here
});

engine.registerWorker("shipOrder", async (data) => {
    console.log("Shipping order", data);
    // Your shipping logic here
});
```

### 执行工作流程

```javascript
const executionId = await engine.executeWorkflow({
    workflowId: "order_processing",
    inputData: { orderId: 12345 },
    callbackOptions: {
        onStepComplete: (step, result) => {
            console.log(`Step ${step.name} completed:`, result);
        },
        onError: (step, error) => {
            console.error(`Step ${step.name} failed:`, error);
        }
    }
});
console.log("Workflow execution started with ID:", executionId);
```

### 随事件恢复工作流程

```javascript
// Resume a waiting workflow with an event
await engine.resumeWorkflow(executionId, "external_approval_received", {
    approved: true,
    approver: "manager@example.com"
});
```

### 获取工作流程日志

```javascript
const log = await engine.fetchWorkflowLog(executionId);
console.log("Execution Log:", log);
```

## 支持的工作流程步骤类型

| 步骤类型 | 说明 |
| --- | --- |
| `task` | 执行注册工人的职能. |
| `decision` | 评估一个条件并执行一个真/假分支. |
| `parallel` | 并行运行多步. |
| `loop` | 根据条件重复执行. |
| `wait` | 在收到事件之前暂停执行 . |
| `execute_then_wait` | 执行任务然后等待外部事件. |
| `switch` | 评估字段值并执行匹配大小写. |
| `commit` | 将工作流程步骤标为承诺步骤. |
| `switch_case` | 表示切换步骤内的一个大小写(内部用于切换逻辑). |

## 公共 API 方法

以下方法可供参考: `WorkflowEngine` 类 :

| 方法 | 说明 |
| --- | --- |
| `init(config)` | 以 Redis 和/或 MongoDB 配置初始化引擎 . |
| `registerWorkflow(id, workflow)` | 将工作流程定义注册为唯一标识. |
| `registerWorker(name, worker)` | 登记工人的职称. |
| `executeWorkflow(options)` | 执行已注册的工作流程。 返回执行ID. |
| `resumeWorkflow(executionId, eventName, inputData, options?)` | 收到事件时恢复等待工作流程. |

> **说明:** 这个 `fetchWorkflowLog` 方法在用法示例中显示,但在主类中没有被执行. 对于工作流程日志,请使用您自己的MongoDB查询或根据需要扩展引擎.

## 工作流程Step 接口( 高级)

每个工作流程步骤都支持以下领域:

-   `id` (字符串):该步骤的独特标识符.
-   `type` (字符串):步骤类型(参见所支持的工作流步骤类型).
-   `name` (字符串):阶下名.
-   `worker` (弦,可选): 要执行的工人函数名称 .
-   `condition` (弦,可选):决定/跳跃步骤的条件.
-   `true_branch` 编号 : `false_branch` (阵列,可选): 决策分支的步骤.
-   `parallel_steps` (阵列,可选): 平行运行的步骤.
-   `switch_cases` (阵列,可选): 切换步骤的案例.
-   `switch_case_steps` (阵列,可选): 特定切换例的步骤 .
-   `event_name` (字符串,可选):等待的事件(等待/执行 当时 等待).
-   `rollback` (对象,可选): 步骤执行回滚 .
-   `status` (弦,可选): 步骤状况.
-   `createdAt` 编号 : `updatedAt` (字符串,可选):时间戳.
-   `workerTimeout` (数目,可选): 工时超时数.
-   `field` 编号 : `value` (任何,可选):用于开关/大小写逻辑.
-   `default_case` (对象,可选): 切换的默认步骤 .

## 高级工作流程示例

### 切换/案件工作流程

```javascript
const switchWorkflow = {
    name: "Order Status Processing",
    steps: [
        {
            id: "1",
            type: "switch",
            name: "Process Based on Status",
            switch_cases: [
                {
                    id: "case1",
                    field: "status",
                    value: "COMMITTED",
                    switch_case_steps: [
                        { id: "1.1", type: "task", name: "Handle Committed", worker: "handleCommitted" }
                    ]
                },
                {
                    id: "case2", 
                    field: "status",
                    value: "CANCELLED",
                    switch_case_steps: [
                        { id: "1.2", type: "task", name: "Handle Cancelled", worker: "handleCancelled" }
                    ]
                }
            ],
            default_case: {
                id: "default",
                type: "task",
                name: "Handle Default",
                worker: "handleDefault"
            }
        }
    ]
};
```

### 并行执行

```javascript
const parallelWorkflow = {
    name: "Parallel Processing",
    steps: [
        {
            id: "1",
            type: "parallel",
            name: "Process Multiple Tasks",
            parallel_steps: [
                { id: "1.1", type: "task", name: "Task A", worker: "workerA" },
                { id: "1.2", type: "task", name: "Task B", worker: "workerB" },
                { id: "1.3", type: "task", name: "Task C", worker: "workerC" }
            ]
        }
    ]
};
```

### 事件驱动工作流程

```javascript
const eventWorkflow = {
    name: "Event-Driven Process",
    steps: [
        { id: "1", type: "task", name: "Initial Task", worker: "initialWorker" },
        {
            id: "2",
            type: "wait",
            name: "Wait for Approval",
            event_name: "approval_received"
        },
        { id: "3", type: "task", name: "Final Task", worker: "finalWorker" }
    ]
};
```

## 配置选项

### Redis 配置

```javascript
const redisConfig = {
    host: "localhost",
    port: 6379,
    // OR provide your own Redis client
    redisClient: existingRedisClient
};
```

### MongoDB 配置

```javascript
const mongoConfig = {
    uri: "mongodb://localhost:27017",
    database: "workflowDB",
    collection: "logs",
    // OR provide your own MongoDB client
    mongoClient: existingMongoClient
};
```

## 处理和回滚出错

-   如果任务失败,工作流程引擎会触发回滚步骤,如果它们被定义的话.
-   回滚步骤按倒转顺序执行(LIFO - Last In, First Out).
-   倒滚步骤出错被记录,但不会停止倒滚进程.
-   每一步骤都可以在以下定义自己的回滚逻辑: `rollback` 属性.

## 州管理层

-   **红:** 用于缓存工作流程执行状态和已注册的工作流程.
-   **蒙哥达:** 存储详细的工作流程执行历史和日志(可选).
-   **记忆中:** 如果 Redis 没有配置, 则返回到内存中 .

## 类型脚本支持

库以 TypeScript 书写,并提供完整类型定义:

```typescript
import { WorkflowEngine, WorkflowStepType, WorkflowDefinition } from "@datarster/workflow-engine";
```

## 捐款

欢迎捐款! 在GitHub上随意提交问题或调取请求.

## 许可证

麻省理工学院

## 常见问题

### @datarster/workflow-engine 是什么？

Workflow引擎是一个强大的工具,旨在自动化和管理复杂的工作流程\. 它允许用户轻松地定义,执行并监控工作流程\.

### 如何安装 @datarster/workflow-engine？

在项目目录运行 npm install @datarster/workflow-engine，或使用 pnpm add / yarn add / bun add。

### @datarster/workflow-engine 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @datarster/workflow-engine 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @datarster/workflow-engine 可以商用吗？

@datarster/workflow-engine 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @datarster/workflow-engine 的下载量有多少？

根据 npm 官方下载统计，@datarster/workflow-engine 在 2026/10/12 – 2026/11/10 这 30 天内被下载 5,497 次，日均约 183 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @datarster/workflow-engine 还在维护吗？

最新版本 0\.0\.21 发布于 2025/07/14（1\.3 年前）；至今共发布 21 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/02/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。