Edit: Durable Object 的基础 API (Base API)

编辑文章

标题 *

URL 别名 *

内容 * (支持 Markdown 格式)

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

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

---

### 核心概述

Base API 定义了三件大事：

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

---

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

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

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

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

---

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

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

```javascript
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` 方法就会被执行。

```javascript
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` 中访问到它。

```javascript
// 在一个普通的 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 实例上，并在需要时唤醒它。

### 总结

配图 (可多选)

选择新图片文件或拖拽到此处

标签