# @foliot/sdk 中文文档

规范地址：https://npmcn.com/package/%40foliot/sdk/

版本：0\.11\.0
npm 元数据更新时间：2026-11-11T23:19:46.003Z
中文译文更新时间：2026-11-15T23:42:13.204Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40foliot/sdk
原文对照：https://npmcn.com/package/%40foliot/sdk/?lang=original
项目主页：https://docs.foliot.app/

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

- 包体积（解压后）：322 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：express \>=4，@nestjs/common \>=10，reflect-metadata \>=0\.1
- 首次发布：2026-09-25T12:16:36.032Z
- 最新版本发布：2026-11-11T23:19:45.763Z
- 近 30 天下载量：1992（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Foliot SDK:定义工作流程,处理步骤,启动运行并发送信号

## 安装

```sh
npm install @foliot/sdk
```

也可以使用：`pnpm add @foliot/sdk`、`yarn add @foliot/sdk`、`bun add @foliot/sdk`

## README

# @ foliot/ sdk (英语)

客户端 SDK 为 [组合](https://docs.foliot.app/)一个工作流程指挥员. **引擎保存状态、时钟和历史;您的应用程序保存 商业逻辑.**

您将工作流程定义为版本的步数列表 。 Foliot 推动每项任务 您的应用程序在 HTTPS 上签名, 记录每一次尝试, 用备份重试, 等待 用于计时器和信号,并让操作员重新驱动、倒带或跳过运行.

```sh
npm install @foliot/sdk
```

船舶既包括无害环境管理,也包括普通JS,因此在现代无害环境管理服务中以及在 CommunityJS NestJS app 不需动态导入.

## 定义工作流程

```ts
import { defineWorkflow, task, wait, choice, when, END, FAIL } from "@foliot/sdk";

export const orderFulfilment = defineWorkflow<Order>()({
  name: "order-fulfilment",
  version: 1,
  retry: { maxAttempts: 5, backoff: "exponential", initial: "10s", max: "1h" },
  steps: [
    task("reserve-stock", { timeout: "30s" }),
    task("charge-card", { timeout: "60s", onFailure: "release-stock" }),
    wait("shipped", { timeout: "5d" }),
    task("send-receipt", { next: END }),
    task("release-stock", { next: FAIL }),
  ],
});
```

## 登记

货包船a `foliot` CLI(英语:CLI). 指向输出您的模块 工作流程并运行在CI或部署时 `FOLIOT_URL` (单位:千美元)`https://api.foliot.app`, (中文(简体) ), `FOLIOT_TOKEN` 财务报告和审定财务报表 `FOLIOT_APP` 设置于 环境:

```sh
npx foliot push dist/workflows.js
```

`--url` 财务报告和审定财务报表 `--app` 可以用旗子来代替 保留 API 密钥 `FOLIOT_TOKEN` 而不是说 `--token`: 标记值可见于进程 列表和响应命令的 CI 日志. `foliot whoami` 显示一个符号 属于。 定义为: 版本: 运行在它开始的版本上, 因此推动新版本 从不打扰飞行中的工作.

## 处理台阶

每个任务步骤都有一个处理器——一个缺失的是一个编译错误,所以一个工作流程 不能提及无人执行的步骤.

```ts
export const handlers = orderFulfilment.handlers({
  "reserve-stock": async (ctx) =>
    inventory.reserve(ctx.input.items, { attemptKey: ctx.attemptKey }),
  "charge-card": async (ctx) =>
    payments.charge(ctx.input.card, ctx.input.amount, { attemptKey: ctx.attemptKey }),
  "send-receipt": async (ctx) => mail.send(ctx.input.email),
  "release-stock": async (ctx) => inventory.release(ctx.output("reserve-stock")),
});
```

掷出 `NonRetryableError` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}直接到 `onFailure`; 抛出其他任何东西 和重试政策决定。 返回时 `defer()` 回答 202 并稍后结束 与 `client.completeTask(token, output)`; 返回时 `jumpTo("step", output)` 改为 选择下一步.

## 上马

```ts
import { createTaskHandler } from "@foliot/sdk";
import { foliotExpress } from "@foliot/sdk/express";

const taskHandler = createTaskHandler({
  workflows: [handlers],
  signingSecret: process.env.FOLIOT_SIGNING_SECRET!,
});

// Express — mount BEFORE express.json(): signatures are over the raw body.
app.use("/foliot", foliotExpress(taskHandler));
```

要旋转签名密钥而不丢弃任务, 请同时通过新任务和任务 旧密件为数组( n)`signingSecret: [next, previous]`),部署,然后放下 旧的.

```ts
// NestJS — create the app with { rawBody: true } for the same reason.
import { FoliotModule } from "@foliot/sdk/nest";

FoliotModule.forRoot({ handler: taskHandler });
```

## 开始运行并发送信号

```ts
import { FoliotClient } from "@foliot/sdk";

const foliot = new FoliotClient({
  baseUrl: "https://api.foliot.app",
  token: process.env.FOLIOT_TOKEN!,
  app: "orders",
});

await foliot.start(orderFulfilment, {
  input: order,
  businessKey: order.id,
  idempotencyKey: order.id,
});

await foliot.signalByBusinessKey(orderFulfilment, order.id, {
  name: "shipped",
  payload: { tracking },
  idempotencyKey: eventId,
});

// Just the run, without its history:
const { run } = await foliot.getRunStatus(runId);
```

## 步骤和尝试键

一步可以跑不止一次: 当福利奥特无法分辨一个尝试是否完成时, 它再次尝试。 每项任务有两把钥匙,两者都不透明:

-   `ctx.stepKey` 每一个尝试 进入一步,和新的 当跑步返回步道时(一回回旋,一回回旋或回旋). 传过去 对任何你的操作者所做的, 只需要每一步发生一次, 例如 支付提供者的一能键.
-   `ctx.attemptKey` 独有的尝试, Foliot 从来没有发送过两次。 这个 操作者在运行步骤前记录下来 并将答案保存在下面 所以 两次到达的请求( 代理重发) 运行一次: 副本 得到相同答复的请求,以及一份副本 当第一个还在运行时就到了 回答 `503` 与 `Retry-After`: Foliot 再次尝试在新的下 `attemptKey` 和同样的 `stepKey`,没有使用 一步的尝试.

默认商店在记忆中,所以它只持有一个复制品. 还有更多 超过一个,通过 `idempotency` 他们共用的商店 内容 `claim(key)` 必须是 原子( Redis) `SET key value NX`,或插入到一列中,然后它 应至少保留一个签名容忍度加最长一步的密钥 运行.

重新开车前的迟答被拒绝.

## 文档

指南和完整的 HTTP API 参考文件在 [(原始内容存档于2018-03-29). docs.folot.app](https://docs.foliot.app/): 从 [快速启动](https://docs.foliot.app/quickstart/) 财务报告和审定财务报表 [定义工作流程](https://docs.foliot.app/defining-workflows/)。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @foliot/sdk 是什么？

Foliot SDK:定义工作流程,处理步骤,启动运行并发送信号

### 如何安装 @foliot/sdk？

在项目目录运行 npm install @foliot/sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 foliot，可以用 npx foliot 直接运行。

### @foliot/sdk 支持 TypeScript 吗？

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

### @foliot/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @foliot/sdk 可以商用吗？

@foliot/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @foliot/sdk 的下载量有多少？

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

### @foliot/sdk 还在维护吗？

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

