Edge Computing with Cloudflare Workers & Deno · 课时

Durable Objects 详解

了解 Durable Objects 如何用于有状态的无服务器应用，并在全球范围内保持状态一致

Durable Objects 详解 是 CoddyKit 上的免费 Edge Computing with Cloudflare Workers & Deno 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Edge Computing with Cloudflare Workers & Deno 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Edge Computing with Cloudflare Workers & Deno 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

The State Problem at the Edge

Serverless functions, like Cloudflare Workers, are typically stateless. This means each request is processed independently, without remembering past interactions.

While great for scalability and cost-efficiency, what if you need to maintain a consistent piece of information across multiple requests or users globally? Think about a live chat room, a game lobby, or a shared counter.

Introducing Durable Objects

Cloudflare Durable Objects solve this fundamental challenge. They are a powerful primitive for building stateful serverless applications directly at the edge.

They provide a single-instance, globally consistent object.
Each Durable Object instance has a unique ID and its own private storage.
They act like tiny, persistent servers that live at the edge.

Unique IDs & Global Consistency

The core concept behind Durable Objects is their unique identity. When you create or retrieve a Durable Object using a specific ID, Cloudflare ensures that only one instance of that object exists and runs globally.

No matter where a request originates from (e.g., Tokyo, New York, London), if it targets the same Durable Object ID, it will be routed to that single, consistent instance. This eliminates the need for complex distributed synchronization.

Anatomy of a Durable Object

A Durable Object is defined as a standard JavaScript class. It must have:

A constructor(state, env) method, where state provides access to its storage and env holds environment variables.
An async fetch(request) method, which processes incoming HTTP requests, similar to a regular Worker.

It's essentially a self-contained, stateful mini-Worker.

Persistent Storage with state.storage

Each Durable Object instance has its own private, durable key-value storage, accessible via this.state.storage. This allows the object to persist data across invocations and even across restarts.

await this.state.storage.put('key', value): Stores data.
await this.state.storage.get('key'): Retrieves data.
await this.state.storage.delete('key'): Removes data.

Values can be any JSON-serializable type, making it versatile for various data needs.

Code: Counter Worker & DO

This example shows a Cloudflare Worker interacting with a simple Counter Durable Object. The DO maintains a count that persists across requests and is globally consistent.

To run this, you'd define the Counter Durable Object binding in your wrangler.toml file.

export class Counter {
  constructor(state, env) {
    this.state = state;
    this.env = env;
  }

  async fetch(request) {
    let url = new URL(request.url);
    // Retrieve current count from storage, default to 0
    let currentCount = (await this.state.storage.get("value")) || 0;

    if (url.pathname === "/increment") {
      currentCount++;
      await this.state.storage.put("value", currentCount);
      return new Response(`Count: ${currentCount}`);
    } else if (url.pathname === "/decrement") {
      currentCount--;
      await this.state.storage.put("value", currentCount);
      return new Response(`Count: ${currentCount}`);
    } else if (url.pathname === "/get") {
      return new Response(`Count: ${currentCount}`);
    }

    return new Response("Not found", { status: 404 });
  }
}

export default {
  async fetch(request, env) {
    // Get a unique Durable Object ID based on a name
    // 'COUNTER' is the binding name configured in wrangler.toml
    let id = env.COUNTER.idFromName("global-counter");
    // Get a 'stub' (a proxy) to interact with the Durable Object
    let stub = env.COUNTER.get(id);

    // Forward the incoming request to the Durable Object's fetch method
    return stub.fetch(request);
  }
};

How the Counter Code Works

1. The Counter class defines the Durable Object's behavior, handling /increment, /decrement, and /get routes and persisting its value.

2. The main Worker's fetch handler:

It uses env.COUNTER.idFromName("global-counter") to obtain a deterministic ID for our counter.
env.COUNTER.get(id) returns a stub, which is a network proxy to the Durable Object.
stub.fetch(request) forwards the original request to the Durable Object instance, allowing it to process the request and update its state.

Global Consistency in Action

Imagine users from different locations (e.g., Europe, Asia, Americas) all interacting with the /increment endpoint of your Worker. Because they all target the "global-counter" ID, Cloudflare guarantees they will all interact with the exact same instance of the Counter Durable Object.

This ensures that the count is always consistent, regardless of the user's location, simplifying complex distributed state management that would otherwise be very challenging.

Common Use Cases for DOs

Durable Objects are ideal for scenarios requiring strong consistency and shared, mutable state at the edge:

Real-time Collaboration: Shared whiteboards, document editing.
Gaming: Game lobbies, player state, matchmaking.
Live Chat: Chat rooms, message queues for real-time communication.
Stateful APIs: Managing user sessions, shopping carts, or unique resource locks.

They bring traditional stateful patterns to the serverless edge, making complex applications simpler to build.

Quick Check: Durable Objects

Which of the following best describes the primary benefit of Cloudflare Durable Objects?

Recap: Durable Objects Explained

In this lesson, we explored Cloudflare Durable Objects, a powerful tool for stateful serverless applications.

They provide globally consistent, single-instance state at the edge.
Each DO has a unique ID and private, durable storage (state.storage).
Workers interact with DOs by obtaining stubs and forwarding requests.
They are ideal for real-time, collaborative, and stateful applications that demand strong consistency.

Durable Objects bridge the gap between stateless serverless and traditional stateful services, simplifying complex distributed systems.

常见问题解答

「Durable Objects 详解」课时是免费的吗？

是的 — 「Durable Objects 详解」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Edge Computing with Cloudflare Workers & Deno 课程的其余内容，请升级到 CoddyKit PRO。 Edge Computing with Cloudflare Workers & Deno 课程共包含 4 节课。

「Durable Objects 详解」这节课中我会学到什么？

了解 Durable Objects 如何用于有状态的无服务器应用，并在全球范围内保持状态一致你通过在浏览器中直接运行的动手代码来练习 Edge Computing with Cloudflare Workers & Deno，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Edge Computing with Cloudflare Workers & Deno 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Edge Computing with Cloudflare Workers & Deno 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「Durable Objects 详解」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Edge Computing with Cloudflare Workers & Deno 课中编写并运行代码吗？

能。每节 Edge Computing with Cloudflare Workers & Deno 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Edge Computing with Cloudflare Workers & Deno