Durable Objects

这一课你将能做到

1. 创建一个 Durable Object 类并通过 Worker 路由访问
2. 用 Durable Object 实现强一致的计数器、聊天室、协同编辑状态
3. 理解 Durable Object 的「单线程」语义和存储模型

为什么要学

KV 最终一致、Queue 至少一次、D1 写走中心——这些都不适合「强一致、低延迟、高并发」的场景。比如：

• 实时聊天室：谁在线、消息顺序、未读数
• 协同编辑：多个用户同时改同一文档
• 游戏房间：玩家状态、回合制、实时同步

人话：Durable Object 就是一个「全局唯一的、有状态的、单线程的」对象实例。全世界只有一个 chatroom-123 实例，所有对 chatroom-123 的请求都会路由到同一个节点、同一个线程、同一份内存状态。这就是强一致的来源。

先建立图像

普通 Worker:                     Durable Object:
                                 
[请求1] ──> [北京节点]            [请求1] ──> [chatroom-123 实例]
[请求2] ──> [纽约节点]            [请求2] ──> [chatroom-123 实例]
[请求3] ──> [伦敦节点]            [请求3] ──> [chatroom-123 实例]
   │            │                  │
   ▼            ▼                  ▼
 无共享状态    无共享状态          共享内存状态 + 持久化存储

跟着做

步骤 1：定义 Durable Object 类

export class ChatRoom {
  state: DurableObjectState;
  
  constructor(state: DurableObjectState) {
    this.state = state;
  }
  
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    
    if (url.pathname === '/join') {
      const userId = url.searchParams.get('userId')!;
      const users = await this.state.storage.get<string[]>('users') ?? [];
      if (!users.includes(userId)) {
        users.push(userId);
        await this.state.storage.put('users', users);
      }
      return Response.json({ users });
    }
    
    if (url.pathname === '/message') {
      const { userId, text } = await request.json();
      const messages = await this.state.storage.get<any[]>('messages') ?? [];
      messages.push({ userId, text, timestamp: Date.now() });
      await this.state.storage.put('messages', messages);
      return Response.json({ messages });
    }
    
    return new Response('Not Found', { status: 404 });
  }
}

步骤 2：在 Worker 中路由到 Durable Object

wrangler.toml：

name = "chat-worker"
main = "src/index.ts"

[[durable_objects.bindings]]
name = "CHAT_ROOM"
class_name = "ChatRoom"

export interface Env {
  CHAT_ROOM: DurableObjectNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const roomId = url.searchParams.get('roomId') ?? 'default';
    
    // 根据 roomId 获取或创建 Durable Object 实例
    const id = env.CHAT_ROOM.idFromName(roomId);
    const stub = env.CHAT_ROOM.get(id);
    
    // 把请求转发给 Durable Object
    return stub.fetch(request);
  },
} satisfies ExportedHandler<Env>;