building-restate-services

Restate

Restate 是一个持久执行运行时。它会将处理程序的每个步骤记录到日志中，因此如果进程崩溃，处理程序会从日志中重放，并从中断处准确继续执行。服务是使用 Restate SDK（TypeScript、Python、Java、Go）的常规应用程序，运行在 Restate Server 后面（一个 Rust 二进制文件，使用 8080 端口接收请求，使用 9070 端口提供管理界面）。

检测上下文

扫描项目以确定 SDK 和上下文：

1. 检测 SDK：

   • package.json 中包含 @restatedev/restate-sdk -> TypeScript
   • requirements.txt 或 pyproject.toml 中包含 restate-sdk -> Python
   • pom.xml 或 build.gradle 中包含 dev.restate -> Java
   • go.mod 中包含 github.com/restatedev/sdk-go -> Go
   • 如果未检测到 SDK，检查项目文件以确定语言，然后询问用户

2. 检测现有 Restate 代码：搜索 @restatedev、restate-sdk、dev.restate.sdk、github.com/restatedev

3. 检测 AI 框架：@ai-sdk/、openai-agents、google-adk、pydantic-ai、langchain、langgraph

4. 检测工作流编排器：temporalio、@temporalio、aws-cdk/aws-stepfunctions 等

核心参考（始终加载）

检测到 SDK 后，始终加载 SDK 参考文档：

• references/<sdk>/api-and-pitfalls.md - 检测到的 SDK 的设置、API 模式、确定性规则、错误处理和注意事项

基于上下文的参考（按需加载）

上下文	参考文档
设计新应用，选择服务类型	references/design-and-architecture.md
添加并发限制、多租户公平性、成本控制、作用域或限制键	references/flow-control-and-scopes.md
从工作流编排器或现有应用迁移	references/translate-to-restate.md
调用服务、与调用交互（取消、附加、幂等性、发送、Kafka）	references/invocation-lifecycle.md
设计 AI Agent、选择持久性边界，或使用不受支持的大模型 / Agent SDK	references/ai-agents.md
使用 Vercel AI SDK 构建 AI Agent	references/ts/restate-vercel-ai-agents.md
使用 OpenAI Agents SDK 构建 AI Agent	references/python/restate-openai-agents-agents.md
使用 Google ADK 构建 AI Agent	references/python/restate-google-adk-agents.md
使用 Pydantic AI 构建 AI Agent	references/python/restate-pydantic-ai-agents.md
使用 LangChain 或 LangGraph 构建 AI Agent	references/python/restate-langchain-agents.md
调试错误、卡住的调用、日志不匹配	references/debug-applications.md
注册部署、检查或管理调用、读取或编辑状态、查询服务端	Restate CLI
测试、部署、服务端配置、Kafka、高级主题	使用随附的 restate-docs MCP 服务
代码示例和模板	restate example --list --json、github.com/restatedev/examples、github.com/restatedev/ai-examples
完整的 TypeScript Agent 参考架构	restatedev/agent

Restate CLI

使用 restate CLI 操作正在运行的 Restate Server：注册部署、检查和管理调用、读取和编辑状态，以及使用 SQL 查询服务器内部信息。 CLI 会介绍自身用法，因此请询问它该运行什么命令，而不要猜测命令或标志：

• restate --help 说明 Agent 应如何使用 CLI。restate <command> --help 显示命令的标志和示例。
• restate search <what you want to do> 查找适用于某项任务的命令、标志或 SQL 表，例如 restate search retry a failed invocation。
• restate sql --help 列出 SQL 内省表，restate sql describe <table> 显示这些表的列。
• 对于命令未涵盖的内容，restate openapi 会打印 Admin API 规范。

运行时：

• 始终传入 --json。包括错误在内的输出会作为单个 JSON 文档写入 stdout，命令也绝不会提示输入。错误包含 kind，通常还会包含 next_steps，其中列出接下来要运行的命令。
• 更改内容的命令（注册、取消、终止、清除、编辑状态等）仅传入 --json 不会应用更改：它们会打印计划的更改，并显示 "applied": false 和 apply_command，然后以代码 3 退出。先向用户展示计划，再使用 --yes 重新运行命令。使用 --dry-run 可预览更改，而不应用更改。
• 运行 restate whoami --json，检查 CLI 正在连接哪个服务器。默认情况下，它连接本地服务器（位于 localhost:9070 的 admin API）。

这些功能需要 CLI 版本 1.8 或更高版本。如果没有 restate search 命令，请让用户升级 CLI。

设计前检查清单

设计任何 Restate 服务架构之前，请先检查：

问题	参考资料
Restate 服务类型、有状态实体、键控方式、并发？	references/design-and-architecture.md
并发限制、租户隔离或下游保护？	references/flow-control-and-scopes.md
项目中是否有非 Restate 编排器？	references/translate-to-restate.md
调用、取消、去重或关联到调用？	references/invocation-lifecycle.md
错误处理、补偿、Saga？	错误处理指南、Saga 指南
AI Agent 或大模型调用？	references/ai-agents.md，然后查阅相关框架参考资料

完成前务必验证

以下检查均为必需项。

• 所有副作用、外部 I/O 和数据库调用均封装在 ctx.run() 中
• 不使用原生随机数、时间、休眠或 UUID——请使用 ctx 辅助方法
• 仅使用 Restate 并发组合器（不使用 Promise.all、asyncio.gather/wait、CompletableFuture、goroutine + channel、select）
• 不在 ctx.run() 中执行 ctx 操作
• 对不可重试的失败抛出 TerminalError
• Python：不使用裸 except:
• AI Agent：加载 references/ai-agents.md，记录每次大模型调用和工具副作用，并设置有界重试策略
• 虚拟对象：不存在死锁循环
• 通过 curl 或 UI 注册并调用服务

重放测试——任何处理程序逻辑变更都必须执行

任何处理程序业务逻辑变更（新增 ctx 操作、调整步骤顺序、新增 ctx.run() 代码块、新增分支）都必须由启用 always-replay 的 Testcontainers 测试覆盖，并且该测试必须通过后才能宣布工作完成。Always-replay 会强制每次调用时都重放所有已记录的步骤，因此非确定性会导致测试失败，而不是在生产环境重试时才失败。

• TypeScript：在 RestateTestEnvironment.start 中设置 alwaysReplay: true
• Python：在 restate.create_test_harness 中设置 always_replay=True
• Java / Go：在 Restate 容器上设置 RESTATE_WORKER__INVOKER__INACTIVITY_TIMEOUT=0m

请参阅 references/<sdk>/api-and-pitfalls.md 的 Testing 部分，了解可用的脚手架。