@foliot/sdk

中文文档
0.11.0发布于 2026/11/12Apache-2.0TypeScriptESM + CJS近 30 天下载 1992

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

中文使用文档
文档目录8 节
  1. 定义工作流程
  2. 登记
  3. 处理台阶
  4. 上马
  5. 开始运行并发送信号
  6. 步骤和尝试键
  7. 文档
  8. 许可证

@ foliot/ sdk (英语)

客户端 SDK 为 组合一个工作流程指挥员. 引擎保存状态、时钟和历史;您的应用程序保存 商业逻辑.

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

npm install @foliot/sdk

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

定义工作流程

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 设置于 环境:

npx foliot push dist/workflows.js

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

处理台阶

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

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) 改为 选择下一步.

上马

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]),部署,然后放下 旧的.

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

FoliotModule.forRoot({ handler: taskHandler });

开始运行并发送信号

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: 从 快速启动 财务报告和审定财务报表 定义工作流程。 。 。 .

许可证

阿帕奇 - 2.0

版本与发布记录

@foliot/sdk 共发布 12 个版本,首次发布于 2026/09/25;过去 12 个月发布了 12 个版本。

版本发布日期距今
0.11.0latest2026/11/124 天前
0.10.02026/11/124 天前
0.9.02026/11/124 天前
0.8.02026/11/097 天前
0.7.02026/11/097 天前
0.6.02026/11/087 天前

关于 @foliot/sdk 的常见问题

@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 和提交记录判断。