用途:在 Cloudflare 边缘构建有状态、可协调的应用,创建或审查 Durable Object 类,实现 RPC 方法、闹钟、WebSocket 处理,配置 wrangler.jsonc/toml 的 DO 绑定与迁移,并用 @cloudflare/vitest-pool-workers 编写测试。
主要能力:围绕协调原子建模(每个聊天室/游戏/用户一个 DO);用 getByName() 做确定性路由;使用 SQLite 存储;在构造函数中用 blockConcurrencyWhile() 初始化 schema;使用 RPC 方法而非 fetch() 处理器(兼容日期 >= 2024-04-03);先持久化后缓存;每个 DO 一个闹钟。
用法要点:wrangler 配置中声明 durable_objects.bindings 与 migrations(new_sqlite_classes);通过 env.MY_DO.getByName("room-123") 获取 stub,也可用 idFromString 或 newUniqueId;存储可用同步 SQL(storage.sql.exec)或异步 KV(storage.put/get);闹钟用 setAlarm/deleteAlarm 与 alarm() 处理器;测试从 cloudflare:test 导入 env。
适用场景:聊天室、多人游戏、协作文档、库存与预订、多租户 SaaS、每用户数据、WebSocket 实时通知、按实体的定时任务。
限制:不适用于无状态请求处理(用普通 Workers)、最大全球分布需求、高扇出独立请求。反模式包括单一全局 DO、每次请求都用 blockConcurrencyWhile()、仅内存保存关键状态、相关写入间使用 await、在 fetch 或外部 I/O 期间持有 blockConcurrencyWhile()。参考文档含 rules.md、testing.md、workers.md,可搜索 blockConcurrencyWhile、idFromName、getByName、setAlarm、sql.exec。