源码模块地图

这一章不是逐行读 Restate 源码，而是建立“看到模块名知道它在系统里负责什么”的地图。Restate 仓库是 Rust workspace，公开的 Cargo.toml 显示核心模块集中在 crates/*、server、cli、service-protocol 等目录。

从仓库结构看系统边界

text

restate/
├── server/                 # restate-server binary
├── cli/                    # restate CLI
├── crates/
│   ├── ingress-http/       # HTTP ingress
│   ├── ingress-kafka/      # Kafka ingestion
│   ├── worker/             # partition processor manager / event loop
│   ├── invoker-impl/       # service invocation and protocol driving
│   ├── bifrost/            # durable log abstraction
│   ├── log-server/         # replicated log storage
│   ├── partition-store/    # materialized state, journals, timers
│   ├── metadata-server/    # metadata consensus server
│   ├── metadata-store/     # metadata model and storage APIs
│   ├── service-protocol/   # protocol shared with SDK services
│   ├── sharding/           # key to partition mapping
│   ├── timer/              # durable timer logic
│   └── types/              # shared domain types
└── tools/                  # benchmarks, diagnostics, admin tools

按请求链路串起来

这条链路对应一次 durable handler 调用：

阶段	可能涉及模块	你应该关注的问题
请求进入	`ingress-http`	如何解析 service/handler/key/idempotency
路由	`sharding`, `types`	key 如何决定 partition
提交事件	`worker`, `bifrost`, `log-server`	什么动作必须先进入日志
执行服务	`invoker-impl`, `service-protocol`	SDK 和 Server 如何流式交换 journal/action
物化读取	`partition-store`	Journal、state、timer index 如何被快速查询
定时唤醒	`timer`	sleep 和 delayed message 如何跨进程存活
运维控制	`metadata-*`, `node`	leader、epoch、placement 如何维护

关键模块的学习顺序

如果你准备继续读 Restate 源码，建议按这个顺序：

types：先理解 Invocation、Journal entry、Service ID 等领域对象。
service-protocol：理解 SDK 和 Server 的通信边界。
worker：看 partition processor 如何驱动状态机。
partition-store：看日志物化成哪些索引和状态。
bifrost / log-server：看复制日志和 segment 设计。
metadata-*：最后再看集群控制面。

本教程如何映射这些模块

Restate 模块	教学版文件
`ingress-http`	`examples/durable-mini/backend/app/main.py`
`worker`	`examples/durable-mini/backend/app/engine.py`
`partition-store`	`examples/durable-mini/backend/app/models.py` + MySQL
`timer`	`DurableContext.sleep()`
`service-protocol`	直接函数调用，不实现网络协议
`sharding`	暂不实现，单分区
`metadata-server`	暂不实现，单节点

源码阅读时的常见误区

不要只找“重试代码”

Durable Execution 的重点不是某个 retry loop，而是 retry loop 背后的 Journal、提交点、状态机和 fencing。只看“哪里 catch exception”会错过系统设计。

先看数据流

读分布式运行时源码时，优先追踪“事件从哪里写入、何时提交、谁消费、如何去重”，比追踪具体函数调用更稳定。

源码模块地图 ​

从仓库结构看系统边界 ​

按请求链路串起来 ​

关键模块的学习顺序 ​

本教程如何映射这些模块 ​