Durable Object Namespace

Durable Object namespace 是一组由同一 Durable Object 类 支持的 Durable Objects。每个类只有一个 Durable Object namespace。一个 Durable Object namespace 可以包含任意数量的 Durable Objects。

DurableObjectNamespace 接口用于获取对新或现有 Durable Objects 的引用。该接口可通过 Cloudflare Worker 的 fetch 处理器上的 env 参数访问，这是在 Wrangler 配置文件 中声明的绑定的标准接口。

此接口定义了多种方法，可用于为 Durable Object 创建 ID。请注意，为 Durable Object 创建 ID 不会创建 Durable Object。Durable Object 在调用 DurableObjectNamespace::get 从 DurableObjectId 创建 DurableObjectStub 后延迟创建。这确保对象在实际访问之前不会被构造。

import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
  ...
}

// Worker
export default {
  async fetch(request, env) {
    // A stub is a client Object used to invoke methods defined by the Durable Object
    const stub = env.MY_DURABLE_OBJECT.getByName("foo");
    ...
  }
}

import { DurableObject } from "cloudflare:workers";

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

// Durable Object
export class MyDurableObject extends DurableObject {
  ...
}

// Worker
export default {
  async fetch(request, env) {
    // A stub is a client Object used to invoke methods defined by the Durable Object
    const stub = env.MY_DURABLE_OBJECT.getByName("foo");
    ...
  }
} satisfies ExportedHandler<Env>;

from workers import DurableObject, WorkerEntrypoint

# Durable Object
class MyDurableObject(DurableObject):
  pass

# Worker
class Default(WorkerEntrypoint):
  async def fetch(self, request):
    # A stub is a client Object used to invoke methods defined by the Durable Object
    stub = self.env.MY_DURABLE_OBJECT.getByName("foo")
    # ...

idFromName 创建唯一的 DurableObjectId，指向 Durable Object 类的单个实例。命名 Durable Objects 是引用 Durable Objects 的最常见方法。

const fooId = env.MY_DURABLE_OBJECT.idFromName("foo");
const barId = env.MY_DURABLE_OBJECT.idFromName("bar");

• 必需字符串，用于生成对应 Durable Object 名称的 DurableObjectId。

• 指向 Durable Object 类实例的 DurableObjectId。

newUniqueId 创建随机生成且唯一的 DurableObjectId，指向 Durable Object 类的单个实例。使用 newUniqueId 创建的 ID 需要存储为字符串，以便将来再次引用同一 Durable Object。例如，ID 可以存储在 Workers KV、另一个 Durable Object 或用户浏览器的 cookie 中。

const id = env.MY_DURABLE_OBJECT.newUniqueId();
const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" });

• 可选对象，键为 jurisdiction，值为司法管辖区字符串。

• 指向 Durable Object 类实例的 DurableObjectId。

idFromString 从已转换为字符串的先前生成的 ID 创建 DurableObjectId。如果 ID 无效（例如 ID 不是从同一 DurableObjectNamespace 创建的），此方法会抛出异常。

// 创建一个新的唯一 ID
const id = env.MY_DURABLE_OBJECT.newUniqueId();
// 将 ID 转换为字符串以便保存在其他地方，例如会话 cookie
const session_id = id.toString();

...
// 从该字符串重新创建 ID
const id = env.MY_DURABLE_OBJECT.idFromString(session_id);

• 必需字符串，对应于先前由 newUniqueId 或 idFromName 生成的 DurableObjectId。

• 指向 Durable Object 类实例的 DurableObjectId。

get 从 DurableObjectId 获取 DurableObjectStub，可用于调用 Durable Object 上的方法。

此方法立即返回 stub，通常在与 Durable Object 建立连接之前。这允许立即向实例发送请求，无需等待网络往返。

const id = env.MY_DURABLE_OBJECT.newUniqueId();
const stub = env.MY_DURABLE_OBJECT.get(id);

• 必需的 DurableObjectId
• 可选对象，键为 locationHint，值为 locationHint 字符串。

• 指向 Durable Object 类实例的 DurableObjectStub。

getByName 从提供的名称获取 DurableObjectStub，可用于调用 Durable Object 上的方法。

此方法立即返回 stub，通常在与 Durable Object 建立连接之前。这允许立即向实例发送请求，无需等待网络往返。

const fooStub = env.MY_DURABLE_OBJECT.getByName("foo");
const barStub = env.MY_DURABLE_OBJECT.getByName("bar");

• 必需字符串，用于生成对应于具有所提供名称的 Durable Object 类实例的 DurableObjectStub。
• 可选对象，键为 locationHint，值为 locationHint 字符串。

• 指向 Durable Object 类实例的 DurableObjectStub。

jurisdiction 从 namespace 创建子 namespace，从该子 namespace 创建的所有 Durable Object ID 和引用将限制在指定的司法管辖区。

const subnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
const euStub = subnamespace.getByName("foo");

• 必需的司法管辖区字符串。

• 限定在特定监管或地理司法管辖区的 DurableObjectNamespace。更多地理司法管辖区在持续评估中，请在 Durable Objects Discord 频道 ↗ 分享请求。

• Durable Objects: Easy, Fast, Correct – Choose Three ↗。