building-restate-services

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Restate

Restate is a durable execution runtime. It records every step of a handler in a journal, so if the process crashes, the handler replays from the journal and resumes exactly where it left off. Services are regular applications using the Restate SDK (TypeScript, Python, Java, Go) that run behind a Restate Server (a single Rust binary on ports 8080 for ingress and 9070 for admin UI).

Restate是一个持久化执行运行时。它会将处理器的每一步操作记录在日志中，因此如果进程崩溃，处理器会从日志中重放操作，并精确地从中断处恢复执行。服务是使用Restate SDK（支持TypeScript、Python、Java、Go）开发的常规应用，运行在Restate Server（一个单独的Rust二进制程序，8080端口用于入口，9070端口用于管理UI）之后。

Detect context

检测上下文

Scan the project to determine the SDK and context:

Detect SDK:
- ```
package.json
```
  with
```
@restatedev/restate-sdk
```
  -> TypeScript
- ```
requirements.txt
```
  or
```
pyproject.toml
```
  with
```
restate-sdk
```
  -> Python
- ```
pom.xml
```
  or
```
build.gradle
```
  with
```
dev.restate
```
  -> Java
- ```
go.mod
```
  with
```
github.com/restatedev/sdk-go
```
  -> Go
- If no SDK detected, check for project files to determine language, then ask the user

Detect existing Restate code: Grep for

@restatedev

restate-sdk

dev.restate.sdk

github.com/restatedev

Detect AI frameworks:

@ai-sdk/

openai-agents

google-adk

pydantic-ai

Detect workflow orchestrators:

temporalio

@temporalio

aws-cdk/aws-stepfunctions

, etc.

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

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

检测现有Restate代码: 搜索

@restatedev

restate-sdk

dev.restate.sdk

github.com/restatedev

检测AI框架:

@ai-sdk/

openai-agents

google-adk

pydantic-ai

检测工作流编排器:

temporalio

@temporalio

aws-cdk/aws-stepfunctions

, etc.

Core reference (always load)

核心参考（始终加载）

After detecting the SDK, always load the SDK reference:

```
references/<sdk>/api-and-pitfalls.md
```
- Setup, API patterns, determinism rules, error handling, and pitfalls for the detected SDK

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

```
references/<sdk>/api-and-pitfalls.md
```
- 针对检测到的SDK的设置、API模式、确定性规则、错误处理以及常见陷阱

Context-based references (load when relevant)

基于上下文的参考（相关时加载）

Context	Reference
Design a new application, choose service types	`references/design-and-architecture.md`
Convert from a workflow orchestrator or existing app	`references/translate-to-restate.md`
Invoking services, interacting with invocations (cancel, attach, idempotency, sends, Kafka)	`references/invocation-lifecycle.md`
Build AI agent with Vercel AI SDK	`references/ts/restate-vercel-ai-agents.md`
Build AI agent with OpenAI Agents SDK	`references/python/restate-openai-agents-agents.md`
Build AI agent with Google ADK	`references/python/restate-google-adk-agents.md`
Build AI agent with Pydantic AI	`references/python/restate-pydantic-ai-agents.md`
Debug errors, stuck invocations, journal mismatches	`references/debug-applications.md`
Testing, deployment, server config, Kafka, advanced topics	Use the bundled restate-docs MCP server
Code examples and templates	`github.com/restatedev/examples` , `github.com/restatedev/ai-examples`

上下文	参考文档
设计新应用，选择服务类型	`references/design-and-architecture.md`
从工作流编排器或现有应用迁移至Restate	`references/translate-to-restate.md`
调用服务、与调用交互（取消、附加、幂等性、发送、Kafka）	`references/invocation-lifecycle.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`
调试错误、卡住的调用、日志不匹配	`references/debug-applications.md`
测试、部署、服务器配置、Kafka、高级主题	使用内置的restate-docs MCP服务器
代码示例和模板	`github.com/restatedev/examples` , `github.com/restatedev/ai-examples`

Before-you-design checklist

设计前检查清单

Before designing any Restate service architecture, check:

Question	Consult
Restate service types, stateful entities, keying, concurrency?	`references/design-and-architecture.md`
Non-Restate orchestrator in the project?	`references/translate-to-restate.md`
Invoking, cancelling, deduplicating, or attaching to invocations?	`references/invocation-lifecycle.md`
Error handling, compensation, sagas?	Error handling guide, Sagas guide
AI agent or LLM calls?	The relevant agent integration reference

在设计任何Restate服务架构之前，请检查以下内容：

问题	参考文档
Restate服务类型、有状态实体、键控、并发？	`references/design-and-architecture.md`
项目中存在非Restate编排器？	`references/translate-to-restate.md`
调用、取消、去重或附加到调用？	`references/invocation-lifecycle.md`
错误处理、补偿、Sagas？	Error handling guide, Sagas guide
AI Agent或LLM调用？	对应的Agent集成参考文档

Always verify before finishing

完成前必须验证

All checks below are mandatory.

All side effects, external I/O, and DB calls wrapped in
```
ctx.run()
```
No native random, time, sleep, or UUID -- use ctx helpers
Restate concurrency combinators only (no
```
Promise.all
```
,
```
asyncio.gather
```
/
```
wait
```
,
```
CompletableFuture
```
, goroutines + channels,
```
select
```
)
No ctx operations inside
```
ctx.run()
```
```
TerminalError
```
raised for non-retryable failures
Python: no bare
```
except:
```
AI agents: set a retry policy for LLM calls
Virtual Objects: no deadlock cycles
Service registered and invoked via curl or the UI

以下所有检查均为必填项.

所有副作用、外部I/O和数据库调用都包裹在
```
ctx.run()
```
中
不使用原生随机数、时间、睡眠或UUID——使用ctx助手函数
仅使用Restate并发组合器（不使用
```
Promise.all
```
,
```
asyncio.gather
```
/
```
wait
```
,
```
CompletableFuture
```
, goroutines + channels,
```
select
```
）
```
ctx.run()
```
内部不包含ctx操作
针对不可重试的失败抛出
```
TerminalError
```
Python：不使用裸
```
except:
```
AI Agent：为LLM调用设置重试策略
虚拟对象：无死锁循环
服务已注册并通过curl或UI调用

Replay test - required on any handler logic change

重放测试 - 处理器逻辑变更时必填

Any change to handler business logic (new

ctx

operations, reordered steps, new

ctx.run()

blocks, new branches) must be covered by a Testcontainers test with always-replay enabled, and that test must pass before declaring the work done. Always-replay forces every journaled step to replay on every invocation, so non-determinism fails the test instead of failing in production on retry.

TypeScript:

alwaysReplay: true

RestateTestEnvironment.start

Python:
```
always_replay=True
```
in
```
restate.test_harness
```

Java / Go:

RESTATE_WORKER__INVOKER__INACTIVITY_TIMEOUT=0m

on the Restate container

See the Testing section of

references/<sdk>/api-and-pitfalls.md

for the working scaffold.

任何对处理器业务逻辑的变更（新增

ctx

操作、调整步骤顺序、新增

ctx.run()

块、新增分支）都必须通过启用always-replay的Testcontainers测试，且测试通过后才能宣告工作完成。Always-replay会强制每次调用都重放所有已记录的步骤，这样非确定性问题会在测试阶段暴露，而非在生产环境重试时失败。

TypeScript:

alwaysReplay: true

RestateTestEnvironment.start

Python:
```
always_replay=True
```
in
```
restate.test_harness
```

Java / Go:

RESTATE_WORKER__INVOKER__INACTIVITY_TIMEOUT=0m

on the Restate container

有关可用的测试框架，请查看

references/<sdk>/api-and-pitfalls.md

的测试部分。