SuperAPI AI 工具集

restate-gen-sdk

编程与开发

查看项目

更新于 11-06 21:46

技能介绍

用途

restate-gen-sdk 是针对 Restate 生成器式 TypeScript SDK(@restatedev/restate-sdk-gen)的开发技能,帮助开发者使用 function* 形式编写处理函数,构建和组合 Restate 服务(service)、虚拟对象(object)与工作流(workflow)。

主要能力

核心模型

Restate 将处理函数中的每个步骤记录到日志(journal)。崩溃或重启后处理函数会重放:已完成步骤返回记录结果,执行从第一个未完成步骤继续。生成器 SDK 将处理函数表达为 function*,每个持久化步骤通过 yield* 执行,例如:

import {serve} from "@restatedev/restate-sdk";
import * as restate from "@restatedev/restate-sdk-gen";

export const greeter = restate.service({
  name: "Greeter",
  handlers: {
    greet(name: string) {
      const id = yield restate.run(async () => sendWelcomeEmail(name), {name: "send email"});
      return `Hello ${name} (${id})`;
    },
  },
});

await serve({services: [greeter], port: 9080});

与 Promise 版 SDK 的关键差异:没有 ctx 参数;操作是 restate 上的自由函数(restate.run、restate.state()、restate.client(...)),它们自行找到当前调用。不得混用 ctx.run、ctx.serviceClient、async 处理函数或 Promise.all 等 Promise SDK 写法。

概念学习路径(12 步)

技能按顺序逐个引入概念,每步只给一个工作中的处理函数添加一个想法:

  1. 带日志副作用的服务处理函数:restate.service、restate.run(参考 references/handlers-and-state.md)
  2. 类型化、可校验的输入输出:restate.schemas({input, output}, fn)
  3. 带持久状态、每个 key 单写者的实体:restate.object、restate.state()
  4. 与写者并行运行的读者:options.handlers.X.shared、restate.sharedState()
  5. 重试、终端失败、确定性:run(..., {retry})、TerminalError、restate.date()、restate.rand()(参考 references/side-effects-and-errors.md)
  6. 持久调用其他处理函数:restate.client(def[, key]).handler(input)(参考 references/composition.md)
  7. 即发即忘或延迟发送:restate.sendClient、SendOpts.from({delay})
  8. 扇出与汇合、竞速、超时:restate.all/any/race/allSettled/select、restate.spawn
  9. 等待外部世界:restate.sleep、restate.awakeable、restate.signal、invocation(id).signal(name)(参考 references/waiting-and-signals.md)
  10. 有自己 ID 的多步骤流程:restate.workflow、restate.workflowPromise
  11. 跨团队或工具共享的契约:restate.iface.*、restate.implement
  12. 服务、注册、调用与测试:serve、restate deployments register、connect、RestateTestEnvironment(参考 references/running-and-testing.md)

要组合更大应用,可阅读 references/patterns.md,其中展示上述积木如何组合成编排器、saga、实体、发布/订阅流与人机协同流程。

服务类型选择

需求 使用
无状态逻辑,任意数量并发调用 restate.service
按 key 保存状态(用户、购物车、会话、对话),同一 key 的调用逐个执行 restate.object
每个 ID 只运行一次、运行期间可用共享处理函数发信号或查询的流程 restate.workflow

使用方式

  • 通过 package.json 检测:若存在 @restatedev/restate-sdk-gen 则适用本技能;同时仍需 @restatedev/restate-sdk 作为 peer 依赖(用于 serve、TerminalError、Opts、SendOpts)。
  • 若项目是 Restate reference agent(含 packages/libs/core 与 agent-config.ts),还需加载 restate-agent 技能。
  • 添加新积木前,先用 grep 搜索 restate.service(、restate.object(、restate.workflow( 查找已有构建块。

完成前检查清单

  • 每个处理函数都是生成器(*name() 或 function*),其使用的每个 Future 或 Operation 都以 yield* 消费。
  • 所有非确定性工作(HTTP、数据库、LLM、时间、随机、UUID)都经 restate.run,或经 restate.date() / restate.rand()。
  • await 与 promise 只出现在 restate.run(async () => ...) 闭包内,且该闭包内不调用任何 restate.*。
  • 每个 restate.run 都有名字:{name: "..."} 或具名函数。
  • 并发使用 restate.all/any/race/allSettled/select,绝不用 Promise.all。
  • 派生任务在处理函数返回前被汇合,或被中断后汇合,否则会被遗弃。
  • 不可重试的失败抛出 TerminalError(来自 @restatedev/restate-sdk)。
  • 只有独占对象处理函数与工作流的 run 写状态;共享处理函数使用 restate.sharedState() 且只读;共享处理函数即使接口使用 iface.shared.* 也需在选项中设置 shared: true。
  • 对象之间不存在独占调用环(同一 key 上 A→B→A 会死锁)。
  • 服务已注册,用 curl 调用过一次,并有重放测试覆盖(见 references/running-and-testing.md)。

适用场景

适合使用 Restate 生成器式 TypeScript SDK 开发持久化、可重放服务与工作流的项目,尤其是需要编排、分布式事务(saga)、按 key 状态实体、发布/订阅、人机协同流程的团队。

限制

  • 本技能只面向生成器 SDK;不得混用 Promise SDK 惯用法。
  • 部署、服务器配置、Kafka 及其他运维主题不在本技能正文中展开,需查询捆绑的 restate-docs MCP 服务器(https://docs.restate.dev/mcp)。
  • 本资料未说明收费、价格或支持的平台信息。