用途
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 步)
技能按顺序逐个引入概念,每步只给一个工作中的处理函数添加一个想法:
- 带日志副作用的服务处理函数:
restate.service、restate.run(参考references/handlers-and-state.md) - 类型化、可校验的输入输出:
restate.schemas({input, output}, fn) - 带持久状态、每个 key 单写者的实体:
restate.object、restate.state() - 与写者并行运行的读者:
options.handlers.X.shared、restate.sharedState() - 重试、终端失败、确定性:
run(..., {retry})、TerminalError、restate.date()、restate.rand()(参考references/side-effects-and-errors.md) - 持久调用其他处理函数:
restate.client(def[, key]).handler(input)(参考references/composition.md) - 即发即忘或延迟发送:
restate.sendClient、SendOpts.from({delay}) - 扇出与汇合、竞速、超时:
restate.all/any/race/allSettled/select、restate.spawn - 等待外部世界:
restate.sleep、restate.awakeable、restate.signal、invocation(id).signal(name)(参考references/waiting-and-signals.md) - 有自己 ID 的多步骤流程:
restate.workflow、restate.workflowPromise - 跨团队或工具共享的契约:
restate.iface.*、restate.implement - 服务、注册、调用与测试:
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-docsMCP 服务器(https://docs.restate.dev/mcp)。 - 本资料未说明收费、价格或支持的平台信息。