Cloudflare Durable Objects 开发助手

为什么需要这个技能

Durable Objects 的入门示例只有几十行：一个 class、一个 storage、一个 WebSocket 回声。但把它用到真实业务里时，翻车的方式非常集中：

• 把所有租户塞进同一个 DO 实例，协调单元变成了全局瓶颈；
• 关键状态只放内存，实例被驱逐或崩溃后数据直接消失；
• 在两次有关联的存储写入之间加了 await，破坏了单线程的原子性保证；
• 在每个请求上调用 blockConcurrencyWhile()，吞吐量断崖式下跌；
• 还在写 fetch() 处理器，不知道 RPC 方法已经成为推荐路径。

更麻烦的是，Durable Objects 的 API 和配置项在持续演进，模型里记住的写法很可能已经过时。

这个技能做什么

它首先确立一条工作纪律：任何 DO 任务都先检索，而不是依赖预训练知识。检索目标包括官方 Docs、API Reference、Best Practices 和 Examples，拿到当前文档页面后再动手实现。

落地时遵循七条关键规则：

1. 围绕协调单元建模——每个聊天室、每局游戏、每个用户对应一个 DO，而不是一个全局 DO；
2. 用 getByName() 做确定性路由，相同输入永远命中同一个实例；
3. 用 SQLite 做存储，在 migrations 里配置 new_sqlite_classes；
4. 只在构造函数里配合 blockConcurrencyWhile() 初始化表结构；
5. 使用 RPC 方法，而不是 fetch() 处理器（兼容性日期需 >= 2024-04-03）；
6. 先持久化，再缓存——永远先写存储，再更新内存状态；
7. 每个 DO 只保留一个 Alarm，setAlarm() 会替换已有定时器。

同时它明确划出红线：禁止用单个全局 DO 承接所有请求，禁止在每次请求上持有锁，禁止只把关键状态放在内存，禁止在关联写入之间插入 await，禁止在 blockConcurrencyWhile() 里做跨 fetch() 或外部 I/O 的阻塞。

配套的参考文档覆盖三块：核心规则与存储并发（rules.md）、Vitest 测试配置（testing.md）、Workers 处理器与 wrangler 配置（workers.md）。常见检索关键词包括 blockConcurrencyWhile、idFromName、getByName、setAlarm、sql.exec。

它适合这几类场景：多实体协调（聊天室、多人游戏、协作文档）、强一致性（库存、预约、回合制）、单实体存储（多租户 SaaS、按用户分片）、持久连接（WebSocket、实时通知）、单实体定时任务（续费、超时）。

适用边界

Durable Objects 的单实例模型天然偏向一致性，代价是分布能力受限。以下需求不该用它：纯无状态请求处理请直接用普通 Workers；需要最大程度全球分发的读路径；高扇出且相互独立的请求，这类负载放在 Workers 上横向扩展更合适。

如果你的场景里没有"必须串行化"的协调单元，那么引入 DO 只会带来复杂度和成本，而没有收益。