# @dapr/durabletask-js 中文文档

规范地址：https://npmcn.com/package/%40dapr/durabletask-js/

版本：1\.0\.0
npm 元数据更新时间：2026-03-27T23:35:44.274Z
中文译文更新时间：2026-11-11T11:36:47.288Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dapr/durabletask-js
原文对照：https://npmcn.com/package/%40dapr/durabletask-js/?lang=original
项目主页：https://github.com/dapr/durabletask-js#readme
源码仓库：https://github.com/dapr/durabletask-js

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

- 包体积（解压后）：764 kB，87 个文件
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2024-11-27T16:56:12.341Z
- 最新版本发布：2026-03-27T23:35:43.831Z
- 近 30 天下载量：245612（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 1 个）

## 中文简介

兼容 Dapr Workflow 及其基本持久任务引擎的持久任务 Javascript SDK

## 安装

```sh
npm install @dapr/durabletask-js
```

也可以使用：`pnpm add @dapr/durabletask-js`、`yarn add @dapr/durabletask-js`、`bun add @dapr/durabletask-js`

## README

# 持久任务 Javascript

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

此 repo 包含一个 Javascript 客户端 SDK , 用于与 [长期任务框架](https://github.com/microsoft/durabletask-go) 财务报告和审定财务报表 [Dapr 工作流程](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/)。使用这个SDK,您可以使用普通的Javascript代码定义、安排和管理持久的管弦乐.

> 该SDK目前正在积极开发中,尚未准备好用于生产.

请注意,这个项目是: **没有** 目前隶属于联合国 [持久函数](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview) azure 函数项目.

⚠️ **该SDK目前正在积极开发中,尚未准备好用于生产.** ⚠️

## 支持的模式

目前支持以下管弦乐模式.

### 函数链

管弦乐可以使用下列语法将一系列函数调用连锁:

```typescript
function hello(ctx: ActivityContext, name: string): string {
  return `Hello ${name}!`;
}

const sequence: TOrchestrator = async function* (ctx: OrchestrationContext): any {
  const cities = [];

  const result1 = yield ctx.callActivity(hello, "Tokyo");
  cities.push(result1);
  const result2 = yield ctx.callActivity(hello, "Seatle");
  cities.push(result2);
  const result3 = yield ctx.callActivity(hello, "London");
  cities.push(result3);

  return cities;
};
```

你可以找到完整的样本 [这里](https://npmcn.com/package/%40dapr/durabletask-js/examples/activity-sequence.ts)。 。 。 .

### 范-出/范-因

管弦乐可以同时扇出动态数函数调用,然后使用以下语法扇入结果:

```typescript
# activity function for getting the list of work items
function getWorkItems (ctx: ActivityContext): string[] {
    //...
}

function processWorkItem(ctx: ActivityContext): number {
    //...
}

const orchestrator: TOrchestrator = async function* (ctx: OrchestrationContext): any {
    const tasks = [];
    const workItems = yield ctx.callActivity(getWorkItems);
    for (const workItem of workItems) {
    tasks.push(ctx.callActivity(processWorkItem, workItem));
    }
    const results = yield whenAll(tasks);
    return results
}
```

你可以找到完整的样本 [这里](https://npmcn.com/package/%40dapr/durabletask-js/examples/fanout-fanin.ts)。 。 。 .

### 人类互动和持久的定时器

一个管弦乐团可以等待用户定义的事件,比如人类的认可事件,然后推向下一步. 此外,管弦乐还可以创建一个具有任意持续时间的定时器,如果外部事件没有收到,则触发一些替代动作:

```typescript
const orchestrator: TOrchestrator = async function* (ctx: OrchestrationContext, order: Order): any {
  if (order.cost < 1000) {
    return "Auto-approvied";
  }

  yield ctx.callActivity(sendApprovalRequest, order);
  const approvalEvent = ctx.waitForExternalEvent("approval_received");
  const timerEvent = ctx.createTimer(10 * 60);
  const winner = yield whenAny([approvalEvent, timerEvent]);
  if (winner == timerEvent) {
    return "Canceled";
  }

  ctx.callActivity(placeOrder, order);
  const approvalDetails = approvalEvent.getResult();
  return `Approved by ${approvalDetails.approver}`;
};
```

顺便说一句,你也会注意到上面的"管弦乐"这个例子与自定义的商业对象有作用. 支持自定义商务对象包括支持自定义类,自定义数据类,并被命名为tuples. 这些物体的串行和去串行由SDK自动处理.

你可以找到完整的样本 [这里](https://npmcn.com/package/%40dapr/durabletask-js/examples/human_interaction.ts)。 。 。 .

## 特征概述

目前支持以下功能:

### 管弦乐

使用普通 Python 函数执行管弦 `OrchestrationContext` 作为他们的第一参数。 这个 `OrchestrationContext` 提供API, 以启动儿童管弦乐、安排活动和等待外部活动等。 管弦乐团是容错和耐久的,意思是它们可以自动从故障中恢复,并重建其局部执行状态. 整形器的功能必须是决定性的,即它们必须始终产生相同的输入输出.

### 活 动

使用普通 Python 函数执行活动 `ActivityContext` 作为他们的第一参数。 活动功能由管弦乐安排,并有至少一次执行的保证,这意味着它们至少会被执行一次,但在瞬间失败时可能会被多次执行. 活动功能是任何管弦乐的真正"工作"完成的地方.

### 持久计时器

管弦可以使用 `create_timer` API (英语). 这些计时器具有耐用性,这意味着它们会活过管弦乐手重启并会开火,即使管弦乐手在记忆中并不积极. 耐用计时器可以是任何持续时间,从毫秒到几个月.

### 分节奏

管弦乐可以使用 `call_sub_orchestrator` API (英语). 儿童管弦乐有助于封装复杂的逻辑,并可以将大型管弦乐分解为更小,更可管理的片段.

### 外部活动

管弦乐可以使用 `wait_for_external_event` API (英语). 外部活动对于实施人类互动模式很有用,例如等待用户在继续前批准订单.

### 继续更新

管弦乐可以继续作为新的使用 `continue_as_new` API (英语). 这个API允许一个管弦乐从头开始重启,可以选择使用新的输入.

### 暂停、恢复和终止

管弦可以使用 `suspend_orchestration` 客户端 API 并将暂停,直到恢复使用 `resume_orchestration` 客户端 API. 暂停的管弦乐将停止处理新事件,但将继续缓冲任何偶然到达的事件,直到恢复,确保不丢失数据. 也可以使用 `terminate_orchestration` 客户端 API. 终止的管弦乐将停止处理新事件,并放弃任何缓冲事件.

### 重试政策( TODO)

管弦乐团可以规定活动和子管弦乐的重试政策. 这些政策控制了发生瞬间出错时某项活动或分会有多少次和多少次重复试验.

## 开始

### 先决条件

-   节点.js 18或以上
-   与任务相容的长相机车 [Dapr 工作流程](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/)

### 运行样本

见 [实例](https://npmcn.com/package/%40dapr/durabletask-js/examples) 样本管弦乐列表和如何操作的指令目录.

## 发展

### 生成原生体

Protobuf定义储存在 [./分模块/可完成的任务](https://npmcn.com/package/%40dapr/durabletask-js/submodules/durabletask-proto) 目录,这是一个子模块。 要更新子模块, 请从工程根运行以下命令 :

```sh
git submodule update --init
```

一旦子模块可用,相应的源代码可以使用以下命令从项目根重生成: 1

```sh
npm install grpc_tools_node_protoc_ts --save-dev

# generate js codes via grpc-tools
grpc_tools_node_protoc \
--js_out=import_style=commonjs,binary:src/proto \
--grpc_out=grpc_js:src/proto \
--plugin=protoc-gen-grpc=`which grpc_tools_node_protoc_plugin` \
-I ./submodules/durabletask-protobuf/protos orchestrator_service.proto

protoc \
--plugin=protoc-gen-ts=./node_modules/.bin/protoc-gen-ts \
--ts_out=grpc_js:src/proto \
-I ./submodules/durabletask-protobuf/protos orchestrator_service.proto
```

### 运行单元测试

单位测试可以使用以下来自项目根的指令运行. 单位测试 _别_ 需要运行侧车进程.

```sh
npm run test:unit
```

### 运行 E2E 测试

要运行 E2E 测试, 请从工程根运行以下命令 :

```sh
npm run test:e2e
```

此命令将启动一个耐用任务旁车道克容器(cgillum/可耕地- sidecar:latest).

## 捐款

该项目欢迎各方的贡献和建议。 大多数捐款要求您同意 撰稿人许可协议(CLA)宣布,你有权并且实际上确实给了我们 有权使用您的贡献。 详情请访问 [https://cla.opensource.microsoft.com 互联网档案馆的存檔,存档日期2014-10-02](https://cla.opensource.microsoft.com/)。 。 。 .

当您提交拉拉请求时, CLA bot 会自动确定您是否需要提供 a CLA并适当装饰PR(如状态检查、评论)。 只要听从指示 由机器人提供。 你只需要用我们的CLA 一次就能完成.

该项目通过了 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息见 [《行为守则》](https://opensource.microsoft.com/codeofconduct/faq/) 或者说 联系人 [打开码@ microsoft.com](mailto:opencode@microsoft.com) 并附上任何其他问题或评论.

## 商标

本项目可能包含项目,产品或服务的商标或标志. 授权使用微软 商标或标志必须遵循 [微软的商标和品牌准则](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general)。 。 。 . 在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助. 任何使用第三方商标或标志的行为都必须遵守这些第三方的政策.

## 常见问题

### @dapr/durabletask-js 是什么？

兼容 Dapr Workflow 及其基本持久任务引擎的持久任务 Javascript SDK

### 如何安装 @dapr/durabletask-js？

在项目目录运行 npm install @dapr/durabletask-js，或使用 pnpm add / yarn add / bun add。

### @dapr/durabletask-js 支持 TypeScript 吗？

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

### @dapr/durabletask-js 可以商用吗？

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

### @dapr/durabletask-js 的下载量有多少？

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

### @dapr/durabletask-js 还在维护吗？

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