Durable Objects

使用 Durable Objects 在 Cloudflare 边缘构建有状态、协调的应用程序。

检索来源

你对 Durable Objects API 和配置的了解可能已过时。优先检索而非依赖预训练，以处理任何 Durable Objects 任务。

| 资源 | URL | |----------|-----| | 文档 | https://developers.cloudflare.com/durable-objects/ | | API 参考 | https://developers.cloudflare.com/durable-objects/api/ | | 最佳实践 | https://developers.cloudflare.com/durable-objects/best-practices/ | | 示例 | https://developers.cloudflare.com/durable-objects/examples/ |

实现功能时，请获取相关文档页面。

何时使用

• 为有状态协调创建新的 Durable Object 类
• 实现 RPC 方法、警报或 WebSocket 处理程序
• 审查现有 DO 代码是否符合最佳实践
• 为 DO 绑定和迁移配置 wrangler.jsonc/toml
• 使用 Cloudflare 的 Vitest 集成编写测试
• 设计分片策略和父子关系

参考文档

• ./references/rules.md - 核心规则、存储、并发、RPC、警报
• [测试参考](./references/testing.md) - 当前 Vitest 文档、迁移选择和测试选择
• ./references/workers.md - Workers 处理程序、类型、wrangler 配置、可观测性

搜索：blockConcurrencyWhile, idFromName, getByName, setAlarm, sql.exec

核心原则

将 Durable Objects 用于

| 需求 | 示例 | |------|---------| | 协调 | 聊天室、多人游戏、协作文档 | | 强一致性 | 库存、预订系统、回合制游戏 | | 按实体存储 | 多租户 SaaS、按用户数据 | | 持久连接 | WebSockets、实时通知 | | 按实体计划任务 | 订阅续订、游戏超时 |

不得用于

• 无状态请求处理（使用普通 Workers）
• 需要最大全球分布
• 高扇出独立请求

快速参考

Wrangler 配置

// wrangler.jsonc
{
  "durable_objects": {
    "bindings": [{ "name": "MY_DO", "class_name": "MyDurableObject" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }]
}

基本 Durable Object 模式

import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DO: DurableObjectNamespace<MyDurableObject>;
}

export class MyDurableObject extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec(`
        CREATE TABLE IF NOT EXISTS items (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          data TEXT NOT NULL
        )
      `);
    });
  }

  async addItem(data: string): Promise<number> {
    const result = this.ctx.storage.sql.exec<{ id: number }>(
      "INSERT INTO items (data) VALUES (?) RETURNING id",
      data
    );
    return result.one().id;
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stub = env.MY_DO.getByName("my-instance");
    const id = await stub.addItem("hello");
    return Response.json({ id });
  },
};

关键规则

1. 围绕协调原子进行建模 - 每个聊天室/游戏/用户一个 DO，而不是一个全局 DO
2. 使用 getByName() 进行确定性路由 - 相同输入 = 相同 DO 实例
3. 使用 SQLite 存储 - 在迁移中配置 new_sqlite_classes
4. 在构造函数中初始化 - 仅使用 blockConcurrencyWhile() 进行架构设置
5. 使用 RPC 方法 - 而不是 fetch() 处理程序（兼容性日期 >= 2024-04-03）
6. 先持久化，再缓存 - 在更新内存状态之前始终写入存储
7. 每个 DO 一个警报 - setAlarm() 会替换任何现有警报

反模式（NEVER）

• 单个全局 DO 处理所有请求（瓶颈）
• 在每个请求上使用 blockConcurrencyWhile()（降低吞吐量）
• 仅将关键状态存储在内存中（在驱逐/崩溃时丢失）
• 在相关存储写入之间使用 await（破坏原子性）
• 在 fetch() 或外部 I/O 期间持有 blockConcurrencyWhile()

Stub 创建

// Deterministic - preferred for most cases
const stub = env.MY_DO.getByName("room-123");

// From existing ID string
const id = env.MY_DO.idFromString(storedIdString);
const stub = env.MY_DO.get(id);

// New unique ID - store mapping externally
const id = env.MY_DO.newUniqueId();
const stub = env.MY_DO.get(id);

存储操作

// SQL (synchronous, recommended)
this.ctx.storage.sql.exec("INSERT INTO t (c) VALUES (?)", value);
const rows = this.ctx.storage.sql.exec<Row>("SELECT * FROM t").toArray();

// KV (async)
await this.ctx.storage.put("key", value);
const val = await this.ctx.storage.get<Type>("key");

警报

// Schedule (replaces existing)
await this.ctx.storage.setAlarm(Date.now() + 60_000);

// Handler
async alarm(): Promise<void> {
  // Process scheduled work
  // Optionally reschedule: await this.ctx.storage.setAlarm(...)
}

// Cancel
await this.ctx.storage.deleteAlarm();

测试

在配置测试套件或编写 Durable Object 测试之前，请阅读[测试参考](./references/testing.md)。它会引导到当前设置、API 和示例，并确定需要覆盖的行为。