Durable Objects

Durable Object 是一種特別的 Worker，它把「運算（執行程式碼）」和「自己專屬的儲存」獨特地結合在一起。對於同一個名稱，全世界永遠只有「一個」實例（instance），住在同一個地方，所有人都跟它對話。

「Stateful（有狀態）」是指它在請求之間會「記住」事情。一般的 Worker 一做完就忘光光，這叫「stateless（無狀態）」。Durable Object 則會保留它的資料（同時放在記憶體和持久儲存裡），所以下一個請求看得到上一個請求留下的東西。

讓很多使用者「即時協調」是軟體中最難的問題之一。一般來說你得用資料庫、鎖（lock）、訊息中介來避免大家互相覆蓋。Durable Objects 把這件事變簡單：因為每個名稱只有「一個」實例，它自然就成了唯一的協調點。

只要有多人或多個請求需要「共享並對齊同一份即時狀態」，就該想到 Durable Objects。

你把 Durable Object 寫成一個 JavaScript / TypeScript 類別，在 wrangler.jsonc 裡用一個 binding（綁定）和一個 migration（遷移）登記它，然後在一般的 Worker 裡「用名稱查到它」並呼叫它。

1. 建立 Worker 專案

   從 Hello World 範本開始，再把你的 Durable Object 類別加進程式碼。

   bashcontent_copy複製

   npm create cloudflare@latest -- my-do-app
   cd my-do-app

2. 登記物件

   在 wrangler.jsonc 裡加上一個 binding（Worker 用來呼叫它的名稱）和一個 migration（告訴 Cloudflare 這是一個新的、用 SQLite 儲存的類別）。

   jsonccontent_copy複製

   {
     "durable_objects": {
       "bindings": [
         { "name": "MY_DURABLE_OBJECT", "class_name": "MyDurableObject" }
       ]
     },
     "migrations": [
       { "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }
     ]
   }

3. 部署

   發佈到 Cloudflare 的網路。你請求的每個不同名稱，都會自動拿到屬於自己的實例。

   bashcontent_copy複製

   npx wrangler deploy

import { DurableObject } from "cloudflare:workers";

export class MyDurableObject extends DurableObject {
  // Run a query against this object's own private SQLite database
  async sayHello() {
    const row = this.ctx.storage.sql
      .exec("SELECT 'Hello, World!' AS greeting")
      .one();
    return row.greeting;
  }
}

export default {
  async fetch(request, env) {
    // getByName returns the ONE instance for this name (creating it if needed)
    const stub = env.MY_DURABLE_OBJECT.getByName("room-42");
    // Call a method on it directly via RPC
    const greeting = await stub.sayHello();
    return new Response(greeting);
  },
};

值得記住的限制

• 物件數量：每帳號 / 每類別都是無上限
• 每個物件儲存：付費方案最多 10 GB 的 SQLite
• 吞吐量：每個物件約 1,000 請求/秒 的軟性上限
• CPU 時間：預設 30 秒，最多可設定到 5 分鐘
• SQLite 的鍵 + 值合計：最多 2 MB