跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

Durable Object 基类

最后更新 查看 MarkdownAgent 设置

DurableObject 基类是所有 Durable Objects 继承的抽象类。此基类提供一组可选方法，通常称为处理程序方法，可响应事件，例如使用 WebSocket 休眠 API 时的 webSocketMessage。为提供具体示例，以下是 Durable Object MyDurableObject，它扩展 DurableObject 并实现 fetch 处理程序以向调用 Worker 返回 "Hello, World!"。

export class MyDurableObject extends DurableObject {
	constructor(ctx, env) {
		super(ctx, env);
	}

	async fetch(request) {
		return new Response("Hello, World!");
	}
}
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

    async fetch(request: Request) {
    	return new Response("Hello, World!");
    }

}
from workers import DurableObject, Response

class MyDurableObject(DurableObject):
	def __init__(self, ctx, env):
		super().__init__(ctx, env)

	async def fetch(self, request):
		return Response("Hello, World!")

方法

fetch

  • fetch(request Request) : Response | Promise<Response>
    • 接受 HTTP Request 并返回 HTTP Response。此方法允许 Durable Object 模拟一个 HTTP 服务器，在此服务器上绑定了该对象的 Worker 是客户端。
    • 此方法可以是 async（异步的）。
    • 自兼容性日期 2024-04-03 起，Durable Objects 支持 RPC 调用。当您的应用程序不遵循 HTTP 请求/响应流程时，RPC 方法优于 fetch()。

参数 (Parameters)

  • request Request - 传入的 HTTP 请求对象。

返回值 (Return values)

  • 一个 Response 或 Promise<Response>。

示例

export class MyDurableObject extends DurableObject {
	async fetch(request) {
		const url = new URL(request.url);
		if (url.pathname === "/hello") {
			return new Response("Hello, World!");
		}
		return new Response("Not found", { status: 404 });
	}
}
export class MyDurableObject extends DurableObject<Env> {
	async fetch(request: Request): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname === "/hello") {
			return new Response("Hello, World!");
		}
		return new Response("Not found", { status: 404 });
	}
}
from workers import DurableObject, Response
from urllib.parse import urlparse

class MyDurableObject(DurableObject):
    async def fetch(self, request):
        path = urlparse(request.url).path
        if path == "/hello":
            return Response("Hello, World!")
        return Response("Not found", status=404)

alarm

  • alarm(alarmInfo? AlarmInvocationInfo) : void | Promise<void>
    • 在到达计划的闹钟时间时由系统调用。
    • alarm() 处理程序保证至少执行一次，并且在失败时将使用指数退避算法进行重试，从两秒的延迟开始，最多重试六次。如果该方法由于未捕获的异常而失败，将执行重试。
    • 此方法可以是 async。
    • 有关更多信息，请参阅闹钟。

参数 (Parameters)

  • alarmInfo AlarmInvocationInfo (可选) - 包含重试信息的对象：
    • retryCount number - 该闹钟事件已被重试的次数。
    • isRetry boolean - 如果该闹钟事件是重试则为 true，否则为 false。

返回值 (Return values)

  • 无。

示例

export class MyDurableObject extends DurableObject {
	async alarm(alarmInfo) {
		if (alarmInfo?.isRetry) {
			console.log(`Alarm retry attempt ${alarmInfo.retryCount}`);
		}
		await this.processScheduledTask();
	}
}
export class MyDurableObject extends DurableObject<Env> {
	async alarm(alarmInfo?: AlarmInvocationInfo): Promise<void> {
		if (alarmInfo?.isRetry) {
			console.log(`Alarm retry attempt ${alarmInfo.retryCount}`);
		}
		await this.processScheduledTask();
	}
}
from workers import DurableObject

class MyDurableObject(DurableObject):
    async def alarm(self, alarm_info=None):
        if alarm_info and alarm_info.isRetry:
            print(f"Alarm retry attempt {alarm_info.retryCount}")
        await self.process_scheduled_task()

webSocketMessage

  • webSocketMessage(ws WebSocket, message string | ArrayBuffer) : void | Promise<void>
    • 当已接受的 WebSocket 收到消息时由系统调用。
    • 此方法不会针对 WebSocket 控制帧调用。系统会自动响应传入的 WebSocket 协议 ping ↗，而不会中断休眠。
    • 此方法可以是 async。

参数 (Parameters)

  • ws WebSocket - 接收到消息的 WebSocket ↗。使用此引用发送响应或访问序列化的附件。
  • message string | ArrayBuffer - 消息数据。文本消息作为 string 抵达，二进制消息作为 ArrayBuffer 抵达。

返回值 (Return values)

  • 无。

示例

export class MyDurableObject extends DurableObject {
	async webSocketMessage(ws, message) {
		if (typeof message === "string") {
			ws.send(`Received: ${message}`);
		} else {
			ws.send(`Received ${message.byteLength} bytes`);
		}
	}
}
export class MyDurableObject extends DurableObject<Env> {
	async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
		if (typeof message === "string") {
			ws.send(`Received: ${message}`);
		} else {
			ws.send(`Received ${message.byteLength} bytes`);
		}
	}
}
from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketMessage(self, ws, message):
        if isinstance(message, str):
            ws.send(f"Received: {message}")
        else:
            ws.send(f"Received {len(message)} bytes")

webSocketClose

  • webSocketClose(ws WebSocket, code number, reason string, wasClean boolean) : void | Promise<void>
    • 在 WebSocket 连接关闭时由系统调用。
    • 使用 web_socket_auto_reply_to_close 兼容性标志（在 2026-04-07 或更晚的兼容性日期默认启用），运行时会在调用此处理程序之前自动发送互惠的 Close 帧并将 readyState 转换为 CLOSED。您不需要调用 ws.close()——但这样做是安全的（调用会被默默忽略）。
    • 在较旧的兼容性日期（2026-04-07 之前），您必须在此处理程序中调用 ws.close(code, reason) 以完成 WebSocket 关闭握手。未能互惠关闭将导致客户端上出现 1006 错误，这代表符合 WebSocket 规范的异常关闭。
    • 此方法可以是 async。

参数 (Parameters)

  • ws WebSocket - 已关闭的 WebSocket ↗。
  • code number - 对端发送的 WebSocket 关闭代码 ↗（例如，正常关闭为 1000，离开为 1001）。
  • reason string - 表示连接关闭原因的字符串。可能为空。
  • wasClean boolean - 如果连接通过正确的关闭握手干净地关闭则为 true，否则为 false。

返回值 (Return values)

  • 无。

示例

export class MyDurableObject extends DurableObject {
	async webSocketClose(ws, code, reason, wasClean) {
		// 使用 web_socket_auto_reply_to_close (compat date >= 2026-04-07),
		// 运行时已自动完成关闭握手。
		// 在更旧的 compat date 上，需在此处调用 ws.close(code, reason)。
		ws.close(code, reason);
		console.log(`WebSocket closed: code=${code}, reason=${reason}`);
	}
}
export class MyDurableObject extends DurableObject<Env> {
	async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
		// 使用 web_socket_auto_reply_to_close (compat date >= 2026-04-07),
		// 运行时已自动完成关闭握手。
		// 在更旧的 compat date 上，需在此处调用 ws.close(code, reason)。
		ws.close(code, reason);
		console.log(`WebSocket closed: code=${code}, reason=${reason}`);
	}
}
from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketClose(self, ws, code, reason, was_clean):
        ws.close(code, reason)
        print(f"WebSocket closed: code={code}, reason={reason}")

webSocketError

  • webSocketError(ws WebSocket, error unknown) : void | Promise<void>
    • 在 WebSocket 连接上发生非断开连接错误时由系统调用。
    • 此方法可以是 async。

参数 (Parameters)

  • ws WebSocket - 遇到错误的 WebSocket ↗。
  • error unknown - 发生的错误。可能是 Error 对象或其他类型，取决于错误来源。

返回值 (Return values)

  • 无。

示例

export class MyDurableObject extends DurableObject {
	async webSocketError(ws, error) {
		const message = error instanceof Error ? error.message : String(error);
		console.error(`WebSocket error: ${message}`);
	}
}
export class MyDurableObject extends DurableObject<Env> {
	async webSocketError(ws: WebSocket, error: unknown) {
		const message = error instanceof Error ? error.message : String(error);
		console.error(`WebSocket error: ${message}`);
	}
}
from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketError(self, ws, error):
        print(f"WebSocket error: {error}")

属性 (Properties)

ctx

ctx 是 DurableObjectState 类型的只读属性，提供对存储、WebSocket 管理以及其他实例特定功能的访问。

env

env 包含此 Durable Object 可用的环境绑定，如您的 Wrangler 配置中所定义。

相关资源

这篇文档对您有帮助吗？