Durable Object 的基础 API (Base API)

这篇文档描述的是 Durable Object 的基础 API (Base API)，可以理解为每个 Durable Object 都必须具备的“骨架”和与外部世界交互的基本规则。

我将用“专属管家”的比喻来为您详细解释这个基础 API 的各个组成部分。

核心概述

Base API 定义了三件大事：

如何定义一个管家 (The Class)：你的管家是什么样子的，有什么能力。
管家如何处理工作 (The Fetch Handler)：当有人找他时，他的标准工作流程是什么。
如何从外部找到并呼叫这个管家 (The Namespace)：作为客户，你如何联系到特定的管家。

1. `DurableObject` - 管家的“蓝图”

这就是你编写的那个 class。它规定了你这类“管家”的行为模式。

  
export class MyDurableObject {
  
  // ... 管家的具体实现 ...
  
}

export: 这个关键字很重要，它告诉 Cloudflare 运行时：“这是一个可以被实例化的 Durable Object 蓝图”。

2. `constructor(state, env)` - 管家的“唤醒与准备”

这是管家被唤醒（从冷启动到热状态）时要做的第一件事。它在每个实例的生命周期中只运行一次。

  
export class MyDurableObject {
  
  constructor(state, env) {
  
    // state 包含了这个管家独有的工具箱
  
    this.state = state; 
  
    
  
    // env 包含了外部环境信息，比如密钥
  
    this.env = env; 
  
  }
  
  // ...
  
}

state (类型为 DurableObjectState): 这是最重要的参数，它就像是管家随身携带的**“专属工具箱”。这个工具箱里的工具是与这个具体管家实例强绑定**的。它包含：
- state.id: 管家的唯一身份ID（一个 DurableObjectId 对象）。这是他的“身份证号”，全球唯一且不可变。
- state.name: 如果你通过名字创建对象，这里就是管家的名字（字符串）。
- state.storage: 通往管家“私人储藏室”的钥匙，让你能使用 Storage API（键值对或SQL）。
- state.blockConcurrencyWhile(): 一个“请勿打扰”的牌子，用于在执行关键初始化任务时，阻止其他请求进入。
env: 这是管家工作时所处的**“环境”**。它包含了你在 wrangler.toml 文件中配置的所有绑定，比如：
- KV 命名空间
- R2 存储桶
- Secrets (密钥)
- 其他服务的绑定

比喻小结：constructor 就是管家被叫醒后，立刻检查自己的身份证 (state.id)，拿起自己的工具箱 (state)，并了解今天的工作环境 (env) 的过程。

3. `fetch(request)` - 管家的“核心工作”

这是处理外部 HTTP 请求的入口点。当一个普通 Worker 通过“存根 (Stub)” 调用这个 Durable Object 时，这个 fetch 方法就会被执行。

  
export class MyDurableObject {
  
  // ... constructor ...
  

  
  async fetch(request) {
  
    // 读取管家自己的ID
  
    const id = this.state.id.toString();
  

  
    // 根据收到的请求，进行处理
  
    const url = new URL(request.url);
  
    if (url.pathname === "/increment") {
  
      // ... 做一些事情 ...
  
      return new Response("Value incremented!");
  
    }
  
    
  
    // 必须返回一个标准的 Response 对象
  
    return new Response(`Hello from Durable Object with ID: ${id}`);
  
  }
  
}

它的工作模式和普通的 Worker 完全一样：接收一个 Request 对象，必须返回一个 Response 对象。
这是你实现大部分业务逻辑的地方。

4. `DurableObjectNamespace` - “管家调度中心”

这个东西不存在于 Durable Object 的类内部。它是在调用方（通常是一个普通的 Worker）中使用的。它就像一个“管家调度中心”，负责创建、查找和联系管家。

你在 wrangler.toml 中绑定了 Durable Object 后，就可以在 Worker 的 env 中访问到它。

  
// 在一个普通的 Worker 中 (caller.js)
  
export default {
  
  async fetch(request, env) {
  
    // env.MY_OBJECT 就是那个调度中心
  
    const namespace = env.MY_OBJECT;
  

  
    // --- 如何找到一个管家？ ---
  

  
    // 1. 按名字找 (如果名字不存在，会自动创建一个)
  
    // 这会生成一个确定性的、唯一的ID
  
    let id = namespace.idFromName("example-object-name");
  

  
    // 2. 创建一个全新的、匿名的管家
  
    // 每次调用都会生成一个全新的唯一ID
  
    let uniqueId = namespace.newUniqueId();
  

  
    // --- 如何呼叫这个管家？ ---
  

  
    // 使用 ID 从调度中心获取一个“存根 (Stub)”
  
    // Stub 就像是管家的一个“直达分机号码”
  
    let stub = namespace.get(id);
  

  
    // 通过存根的 fetch() 方法，把请求转发给真正的 Durable Object
  
    // 这就是触发管家 `fetch()` 方法执行的操作
  
    return stub.fetch(request);
  
  }
  
}

idFromName(name): 确保同一个名字总是对应同一个管家ID。非常适合为每个用户、聊天室或文档分配一个固定的对象。
newUniqueId(): 用于创建完全匿名的、一次性的对象。
get(id): 这是最关键的一步。它不会返回对象本身，而是返回一个轻量级的引用——“存根(stub)”。
stub.fetch(): 你对存根调用 fetch，Cloudflare 网络会负责将这个请求路由到世界上正确的那个 Durable Object 实例上，并在需要时唤醒它。

总结

| API 组件 | 角色 | 作用 | 比喻 |

| :--- | :--- | :--- | :--- |

Durable Object 的基础 API (Base API)

核心概述

1. DurableObject - 管家的“蓝图”

2. constructor(state, env) - 管家的“唤醒与准备”

3. fetch(request) - 管家的“核心工作”

4. DurableObjectNamespace - “管家调度中心”

总结

1. `DurableObject` - 管家的“蓝图”

2. `constructor(state, env)` - 管家的“唤醒与准备”

3. `fetch(request)` - 管家的“核心工作”

4. `DurableObjectNamespace` - “管家调度中心”