Durable Objects 说明文档

# Cloudflare Durable Objects 构建基于 Cloudflare Durable Objects 的有状态应用程序的专家指南。 ## 阅读顺序 1. **初次接触？** 阅读此概述 + 快速入门 2. **进行设置？** 查看 [配置](./configuration.md) 3. **构建功能？** 使用下方的决策树 → [模式](./patterns.md) 4. **调试问题？** 查看 [注意事项](./gotchas.md) 5. **深入研究？** [API](./api.md) 和 [DO 存储](../do-storage/README.md) ## 概述 Durable Objects 将计算与存储结合在全局唯一、强一致性的包中： - **全局唯一实例**：每个 DO 都有唯一的 ID，用于多客户端协调 - **同位存储**：与计算紧密结合的快速、强一致性存储 - **自动放置**：对象在首次请求位置附近生成 - **有状态无服务器**：内存状态 + 持久化存储 - **单线程**：串行请求处理（无竞态条件） ## Durable Objects 的规则 防止大多数生产问题的关键规则： 1. **每个 DO 一个闹钟** - 通过队列模式调度多个事件 2. **每个 DO 最大约 1K req/s** - 通过分片实现更高吞吐量 3. **构造函数在每次唤醒时运行** - 保持初始化轻量；使用懒加载 4. **休眠会清除内存** - 内存状态会丢失；持久化关键数据 5. **使用 `ctx.waitUntil()` 进行清理** - 确保在发送响应后完成操作 6. **不要使用 setTimeout 进行持久化** - 使用 `setAlarm()` 进行可靠调度 ## 核心概念 ### 类结构 所有 DO 都继承自 `DurableObject` 基类，构造函数接收 `DurableObjectState`（存储、WebSocket、闹钟）和 `Env`（绑定）。 ### 生命周期状态 [未创建] → [活跃] ⇄ [休眠] → [驱逐] ↓ [销毁] - **未创建**：DO ID 存在但实例从未生成 - **活跃**：正在处理请求，内存状态有效，按 GB-小时计费 - **休眠**：WebSocket 连接打开但无计算，无费用 - **驱逐**：从内存中移除；下一次请求触发冷启动 - **销毁**：数据通过迁移或手动删除被删除 ### 从 Workers 访问 Workers 使用绑定获取存根 (Stub)，然后直接调用 RPC 方法（推荐）或使用 fetch 处理程序（旧版）。 **RPC 与 fetch() 决策：** ├─ 新项目 + 兼容日期 ≥2024-04-03 → RPC（类型安全，更简单） ├─ 需要 HTTP 语义（标头、状态） → fetch() ├─ 将请求代理到 DO → fetch() └─ 旧版兼容性 → fetch() 参见 [模式: RPC 与 fetch()]