Cloudflare Durable Objects 设计模式实战从限流、分片到实时协作的完整实现指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读本文基于本仓库skills/.curated/cloudflare-deploy/references/durable-objects/patterns.md的权威内容系统梳理 Cloudflare Durable ObjectsDO在生产环境中高频使用的设计模式分布式限流、分布式锁、高吞吐分片、WebSocket 实时协作、会话管理、Alarm 事件调度等。你将学会按业务诉求选择正确模式与 ID 策略、在 RPC 与 fetch() 两种调用方式之间做决策并掌握如何在 WebSocket Hibernation休眠与单 Alarm 限制下写出状态可靠、可水平扩展的 Worker 应用。本文为“知识型”技能参考文档所有代码示例可直接用于基于cloudflare:workers的 TypeScript Worker 项目。配套深度资料见同目录的 README、API、Configuration 与 Gotchas。一、模式选型先想清楚“你需要什么”Durable Objects 的核心价值在于每个实例全局唯一、自带强一致性的本地存储、由平台自动放置到首个请求附近并且单线程串行处理请求天然消除竞态条件。但单实例能力有限约 1K req/s 吞吐上限、每实例仅 1 个 Alarm因此几乎所有生产模式都围绕“把合适的工作分给合适的 DO 实例”展开。patterns.md 开篇用一张决策表回答了“什么时候用哪种模式”业务诉求推荐模式ID 生成策略按用户/IP 限流Rate Limiting限流idFromName(identifier)互斥访问锁Distributed Lock分布式锁idFromName(resource)吞吐 1K req/sSharding分片newUniqueId()或哈希实时更新WebSocket 协作idFromName(room)用户会话Session Management会话管理idFromName(sessionId)后台清理任务Alarm 驱动任意策略选型逻辑很清晰需要“协调”的场景限流、锁、会话用确定性的idFromName()让同一标识符永远落在同一个 DO 实例上需要“分摊吞吐”的场景分片用随机或哈希 ID把负载均匀打散到多个实例。这一决策树与 README 的 Decision Trees 中的“What do you need?”分支完全一致。二、调用方式RPC 还是 fetch()在动手写模式之前先决定 Worker 如何调用 DO 实例的方法。patterns.md 给出了明确对比RPC推荐新项目默认要求compatibility_date ≥ 2024-04-03类型安全、调用简单直接在 stub 上调用 DO 的类方法。fetch()传统方式走 HTTP 语义适合需要请求头/状态码、需要把请求代理给 DO、或兼容旧项目的场景。两种调用方式的等价写法如下const count await stub.increment(); // RPC直接调用方法 const count await (await stub.fetch(req)).json(); // fetch()构造 Request 并解析响应从 README 的决策树可以看到更细的取舍规则├─ 新项目 compat ≥2024-04-03 → RPC类型安全、更简单 ├─ 需要 HTTP 语义请求头、状态码 → fetch() ├─ 需要把请求代理给 DO → fetch() └─ 兼容旧项目 → fetch()提示如果你的compatibility_date低于 2024-04-03RPC 调用会报 “RPC Method Not Found” 错误。这是 Gotchas 文档 中列出的常见错误之一解决办法是升级compatibility_date或退回 fetch()。三、高吞吐模式Sharding 分片单实例 DO 的吞吐软上限约为1K req/s这是 Gotchas 文档的限制表中反复强调的约束。当业务需要更高吞吐时必须把请求分片到多个 DO 实例。3.1 分片实现patterns.md 给出的典型实现在 Worker 入口处根据业务键如用户 ID计算哈希再取模映射到 N 个分片之一最后转发给对应 DOexport default { async fetch(req: Request, env: Env): PromiseResponse { const userId new URL(req.url).searchParams.get(user); const hash hashCode(userId) % 100; // 100 个分片 const id env.COUNTER.idFromName(shard:${hash}); return env.COUNTER.get(id).fetch(req); } }; function hashCode(str: string): number { let hash 0; for (let i 0; i str.length; i) hash ((hash 5) - hash) str.charCodeAt(i); return Math.abs(hash); }3.2 三个关键决策patterns.md 明确列出了分片设计时必须回答的三个问题分片数量典型范围 101000。文档建议从 100 开始先测量再调整。分片数越大单实例压力越小但实例数量和管理成本也越高。分片键用户 ID、IP、会话等。必须能均匀分布因此要用哈希而不是直接取模——真实业务键往往有倾斜如热门用户哈希可打散热点。聚合方式分片后跨实例的统计、排行等数据需要聚合可引入Coordinator DO协调者实例或外部系统D1、R2完成汇总。分片与 ID 策略的关系在 API 文档的 ID Generation 一节中有印证idFromName()用于确定性的命名协调限流、锁newUniqueId()生成随机 ID 用于分片高吞吐负载idFromString()则用于从既有 ID 还原实例。patterns.md 的分片示例使用idFromName(shard:${hash})既保证同一用户始终命中同一分片又通过哈希把用户均匀铺到 100 个分片。注意当单实例出现 “Durable Object Overloaded503 错误”时Gotchas 文档给出的标准解法就是分片印证了 1K req/s 软上限的存在。四、Rate Limiting基于 SQLite 的按用户/IP 限流由于 DO 单线程串行处理请求同一 DO 内的限流判断天然无竞态。patterns.md 用 SQLite 存储请求记录并实现滑动窗口限流async checkLimit(key: string, limit: number, windowMs: number): Promiseboolean { const req this.ctx.storage.sql.exec( SELECT COUNT(*) as count FROM requests WHERE key ? AND timestamp ?, key, Date.now() - windowMs ).one(); if (req.count limit) return false; this.ctx.storage.sql.exec( INSERT INTO requests (key, timestamp) VALUES (?, ?), key, Date.now() ); return true; }要点解读窗口判断timestamp Date.now() - windowMs统计的是窗口内的请求数实现滑动窗口语义limit与windowMs共同决定限流阈值。原子性由于 DO 单线程同一实例上的 SELECT INSERT 不会被其他请求打断但注意如果存在await屈服点仍可能交错详见下文“竞态”讨论。落库原因DO 会休眠/驱逐内存计数不可靠请求记录必须持久化到存储中Gotchas 文档明确指出休眠会清空内存状态。选型上限流场景用idFromName(identifier)identifier 通常就是用户 ID 或 IP——这保证了同一用户的请求永远落在同一个 DO 实例上从而共享同一份计数。五、Distributed Lock用 Alarm 兜底的互斥锁多实例并发操作同一资源时可以用 DO 实现分布式锁。patterns.md 的实现非常精妙——用 Alarm 作为锁的自动超时释放机制private held false; async acquire(timeoutMs 5000): Promiseboolean { if (this.held) return false; this.held true; await this.ctx.storage.setAlarm(Date.now() timeoutMs); // 超时自动释放 return true; } async release() { this.held false; await this.ctx.storage.deleteAlarm(); // 手动释放并取消 Alarm } async alarm() { this.held false; } // 超时自动释放设计亮点非重入acquire()在held已为 true 时直接返回 false保证互斥。防死锁持锁方崩溃或失联时Alarm 会在timeoutMs后触发alarm()自动释放锁避免永久锁死。这正是 README 的 Rules 中 “One alarm per DO” 约束下的正确用法——锁本身只占 1 个 Alarm。可靠性Alarm 是持久化调度API 文档的 Alarms 一节说明 Alarm 在 DO 被驱逐/重启后依然生效失败还会自动重试因此超时释放机制不会因实例驱逐而失效。需要注意的是this.held是内存状态DO 休眠会清空它对于关键场景锁的持有状态最好同时写入存储如 SQLite并以 Alarm 作为兜底。六、Hibernation-Aware让 WebSocket 协作“休眠后不丢状态”WebSocket Hibernation 是 DO 的招牌能力连接保持打开但实例进入休眠零计算、零成本。代价是休眠时内存被清空。因此凡是在休眠后还需要使用的数据都必须显式持久化。patterns.md 给出了标准解法——用serializeAttachment()保存连接元数据用存储保存业务状态async fetch(req: Request): PromiseResponse { const [client, server] Object.values(new WebSocketPair()); const userId new URL(req.url).searchParams.get(user); server.serializeAttachment({ userId }); // 休眠后仍可恢复 this.ctx.acceptWebSocket(server, [room:lobby]); server.send(JSON.stringify({ type: init, state: this.ctx.storage.kv.get(state) })); return new Response(null, { status: 101, webSocket: client }); } async webSocketMessage(ws: WebSocket, msg: string) { const { userId } ws.deserializeAttachment(); // 唤醒后恢复元数据 const state this.ctx.storage.kv.get(state) || {}; state[userId] JSON.parse(msg); this.ctx.storage.kv.put(state, state); for (const c of this.ctx.getWebSockets(room:lobby)) c.send(msg); }关键 API 与语义与 API 文档的 WebSocket Hibernation 一节一致ctx.acceptWebSocket(server, tags?)接收 WebSocket 并启用休眠第二个参数是分组标签如room:lobby用于定向广播。serializeAttachment() / deserializeAttachment()连接级元数据的持久化通道休眠后依然存活数据必须可 JSON 序列化且尽量小Gotchas 文档的 Hibernation Caveats 明确提示 attachment 有大小约束。ctx.getWebSockets(tag?)按标签获取连接列表实现“房间内广播”。ctx.storage.kv.get/put业务状态如文档内容、在线用户列表必须落存储因为休眠会清空内存。反模式警示Gotchas 文档 给出了一个经典反例——把userCount存在类的私有字段里休眠唤醒后计数归零。正确做法是读写this.ctx.storage.kv。七、Real-time Collaboration实时协作与重连处理7.1 广播核心逻辑在协作场景如多人编辑、聊天室中DO 的角色是“房间”接收消息、持久化、向房间内所有其他连接广播async webSocketMessage(ws: WebSocket, msg: string) { const data JSON.parse(msg); this.ctx.storage.kv.put(doc, data.content); // 先持久化 for (const c of this.ctx.getWebSockets()) if (c ! ws) c.send(msg); // 再广播跳过发送者 }配合前面的idFromName(room)策略每个房间一个 DO 实例天然实现房间隔离与广播。7.2 客户端指数退避重连网络抖动时客户端应自动重连并采用指数退避避免重连风暴class ResilientWS { private delay 1000; connect(url: string) { const ws new WebSocket(url); ws.onclose () setTimeout(() { this.connect(url); this.delay Math.min(this.delay * 2, 30000); // 1s → 2s → 4s … 封顶 30s }, this.delay); } }退避逻辑初始 1 秒每次失败翻倍最多 30 秒封顶。7.3 服务端断开清理服务端在webSocketClose中做清理——更新在线状态并广播用户离开事件async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) { const { userId } ws.deserializeAttachment(); this.ctx.storage.sql.exec(UPDATE users SET online false WHERE id ?, userId); for (const c of this.ctx.getWebSockets()) c.send(JSON.stringify({ type: user_left, userId })); }API 文档还列出了可选的webSocketError处理器用于连接异常时的兜底处理。八、Session Management带过期清理的会话存储会话天然适合 DOidFromName(sessionId)保证同一会话永远路由到同一实例。patterns.md 用 SQLite 表 Alarm 实现“创建会话 → 校验会话 → 到期批量清理”的完整闭环async createSession(userId: string, data: object): Promisestring { const id crypto.randomUUID(), exp Date.now() 86400000; // 默认 24h 过期 this.ctx.storage.sql.exec( INSERT INTO sessions VALUES (?, ?, ?, ?), id, userId, JSON.stringify(data), exp ); await this.ctx.storage.setAlarm(exp); // 到期触发清理 return id; } async getSession(id: string): Promiseobject | null { const row this.ctx.storage.sql.exec( SELECT data FROM sessions WHERE id ? AND expires_at ?, id, Date.now() ).one(); return row ? JSON.parse(row.data) : null; } async alarm() { this.ctx.storage.sql.exec(DELETE FROM sessions WHERE expires_at ?, Date.now()); }要点校验与过期一体getSession在 SQL 层同时过滤expires_at now过期会话直接查不到无需额外判断。清理策略Alarm 触发时批量删除所有已过期会话避免逐条清理。模式局限性这个实现每个会话一个 DO适合会话量可控的场景如果会话量极大可退化为“会话数据存 D1/KVDO 只做协调”的混合方案。九、Multiple Events单 Alarm 调度多个事件队列模式DO 每实例只能有一个 Alarm这是 README 的 Rules 与 API 文档反复强调的硬限制。需要调度多个定时任务时patterns.md 给出了“事件队列”模式把事件写进存储用最早事件的时间设置 AlarmAlarm 触发时处理所有到期事件并重排下一个 Alarmasync scheduleEvent(id: string, runAt: number) { await this.ctx.storage.put(event:${id}, { id, runAt }); const curr await this.ctx.storage.getAlarm(); if (!curr || runAt curr) await this.ctx.storage.setAlarm(runAt); // 只在更早时更新 Alarm } async alarm() { const events await this.ctx.storage.list({ prefix: event: }), now Date.now(); let next null; for (const [key, ev] of events) { if (ev.runAt now) { await this.processEvent(ev); // 处理到期事件 await this.ctx.storage.delete(key); // 处理后删除 } else if (!next || ev.runAt next) next ev.runAt; // 记录最近的下一个事件 } if (next) await this.ctx.storage.setAlarm(next); // 重新排定 Alarm }设计要点“只提前、不延后”的 Alarm 更新策略只有新事件的runAt早于当前 Alarm 时才调用setAlarm()它会覆盖已有 Alarm避免频繁改写。滚动调度每次alarm()处理完到期事件后用剩余事件中最早的runAt重新设置 Alarm实现“一个 Alarm 驱动 N 个任务”。可靠性API 文档说明 Alarm 在 DO 驱逐后依然可靠、失败自动重试但不保证恰好一次因此processEvent需要幂等设计。十、Graceful Cleanup用 waitUntil 延迟清理当响应已经可以返回、但还有收尾工作清理旧数据、写日志需要完成后用ctx.waitUntil()把异步任务挂到请求生命周期之外async myMethod() { const response { success: true }; this.ctx.waitUntil( this.ctx.storage.sql.exec(DELETE FROM old_data WHERE timestamp ?, cutoff) ); return response; // 响应立即返回清理在后台完成 }这与 API 文档的 Concurrency Control 中的分工一致waitUntil()响应发送后的后台工作清理、日志、非关键任务。blockConcurrencyWhile()初始化、迁移、关键状态建立时的临界区——它会阻塞其他所有请求直到回调完成避免初始化期间的竞态。这是 Gotchas 文档 针对“单线程下仍有竞态”问题的官方解法之一await是屈服点异步操作之间可能交错执行。十一、Best Practices五大维度速查patterns.md 在文末给出了生产环境的最佳实践清单这里逐条展开维度准则说明Design协调用idFromName()分片用newUniqueId()构造函数保持轻量构造函数在每次唤醒冷启动或休眠唤醒都会执行Gotchas 文档重活应懒加载Storage优先 SQLite、事务批量、Alarm 做清理、危险操作前用 PITRSQLite 支持事务与点恢复PITR可恢复 30 天内任意时刻仅 SQLite 后端支持见 DO StoragePerformance单实例约 1K req/s、内存缓存、Alarm 做延迟工作超过即分片DO 内存上限 128 MBGotchas 限制表Reliability503 用重试退避、为冷启动做设计、迁移先--dry-run冷启动无法消除可通过定时ping()关键实例“保温”Gotchas 文档的 Warming 示例SecurityWorker 侧校验输入、限制 DO 创建速率、用 jurisdiction 满足合规jurisdiction如eu、fedramp在 ID 创建时指定之后不可变Configuration 文档补充两条易被忽略的硬性约束详见 Gotchas 限制表存储配额单 DO 的 SQLite 存储上限 10 GBKV 单条键值上限 2 MB。CPU 时间单请求默认 30s可在 wrangler.jsonc 中通过limits.cpu_ms调到最高 300s。十二、快速落地从配置到部署以上模式都依赖正确的 wrangler 配置。最小可用配置来自 Configuration 文档{ name: my-worker, main: src/index.ts, compatibility_date: 2025-01-01, // ≥2024-04-03 才能用 RPC durable_objects: { bindings: [ { name: MY_DO, class_name: MyDO } ] }, migrations: [ { tag: v1, new_sqlite_classes: [MyDO] } // 优先 SQLite 后端 ] }开发与部署命令Configuration 文档的 Commands 一节npx wrangler dev # 本地开发含 DO npx wrangler dev --remote # 联调生产 DO npx wrangler deploy # 部署并自动应用迁移 npx wrangler deploy --dry-run # 仅校验迁移不真正部署 npx wrangler durable-objects list # 列出命名空间 npx wrangler durable-objects info namespace id # 检查指定 DO两个部署前必读的迁移规则迁移无回滚一旦部署无法回退务必先--dry-run验证Configuration 与 Gotchas 均有明确警告。deleted_classes会立即销毁全部数据且不可逆需要移动数据时改用transferred_classes。十三、深入阅读本文是durable-objects参考目录中 patterns 的完整展开同目录及关联目录提供更底层的内容durable-objects/README.md — DO 核心概念、生命周期状态、规则与决策树durable-objects/api.md — DurableObjectState 上下文方法、Alarm 与 WebSocket Hibernation 完整 APIdurable-objects/configuration.md — wrangler.jsonc 绑定、迁移、环境隔离、jurisdiction 配置durable-objects/gotchas.md — 常见错误、限制对照表、Hibernation 注意事项do-storage/README.md — SQLite/KV 存储 API、事务与 PITR 深入指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
