Durable Objects в Cloudflare
Помогает писать и ревьюить Durable Objects в Cloudflare: объект на сущность, хранилище SQLite и миграции, RPC-методы, alarms, WebSocket и тесты на Vitest. Для случаев, когда приложению на Workers нужны общее состояние и координация.
durable-objects- Автор
- Cloudflare
- Источник
- cloudflare/skills/skills/durable-objects @ 5108325
- Лицензия
- Apache-2.0
Об этом скилле
Что делает
Скилл помогает агенту писать, отлаживать и ревьюить Durable Objects в Cloudflare — классы, которые держат состояние и хранилище одной сущности, например чат-комнаты или пользователя. В SKILL.md перечислено, где они к месту: координация, строгая согласованность для складских остатков или бронирований, хранилище на сущность, WebSocket, отложенная работа для каждой сущности.
Основное — семь правил. Первые четыре: один объект на единицу координации, а не один глобальный; getByName() для детерминированной маршрутизации; хранилище SQLite через миграции new_sqlite_classes; blockConcurrencyWhile() только для схемы в конструкторе. Ещё три: RPC-методы вместо обработчика fetch(); сначала запись в хранилище, потом в память; один alarm на объект, потому что setAlarm() заменяет прежний. Антипаттерны добавляют: никаких await между связанными записями — это ломает атомарность — и никакого внешнего I/O внутри blockConcurrencyWhile(). Доступ определяется тем Worker, который реализует объект; отдельных ролей нет.
references/rules.md сводит вопросы проектирования — от выбора между SQLite и старым KV-хранилищем до миграций и гибернации WebSocket — к страницам документации. testing.md ведёт к документации интеграции с Vitest и перечисляет, что проверять: например, состояние между вызовами и alarms без ожидания реального времени. workers.md — сторона Worker: конфигурация с биндингами KV, R2 и D1, валидация на Zod, CORS, таймауты, трейсы и Local Explorer. skill-feedback.md отправляет сообщение об ошибке в cloudflare/skills после того, как вы одобрите текст.
Когда включать и когда не надо
Для нового класса Durable Object, alarms, RPC и обработчиков WebSocket, миграций и ревью готовых объектов.
Сам скилл не советует их для обработчиков без состояния, максимального географического распределения и веерной рассылки множества независимых запросов.
Как поставить и вызвать
Команда установки ниже скачивает SKILL.md, четыре справочника и лицензию. Агент читает документацию по ссылкам, так что нужен доступ в сеть. Вызвать вручную:
- Claude Code:
/durable-objectsили попросить скилл по имени. - Codex:
$durable-objects. - Cursor: наберите
/в чате Agent и выберитеdurable-objects.
Пример: /durable-objects Спроектируй объект чат-комнаты с историей сообщений в SQLite и alarm на случай бездействия.
Чем отличается от похожих
Agents SDK от Cloudflare построен на тех же объектах: каждый класс агента — это Durable Object, к которому добавлены синхронизация состояния, расписания и RPC; этот скилл — для тех, кто пишет объекты сам. Лучшие практики Cloudflare Workers отвечают за Worker вокруг объектов и вопросы по Durable Objects отправляют сюда; учтите, что workers.md описывает Env вручную, а тот скилл считает это антипаттерном и предлагает wrangler types. Функции Neon Functions тоже держат WebSocket-соединения и состояние в памяти, но в одной долгоживущей функции рядом с Postgres, а не в отдельном объекте на сущность.
Установка
Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.
Скилл написан на английском — агент поймёт его и ответит вам по-русски.
curl -fsSL --create-dirs -o ~/.claude/skills/durable-objects/SKILL.md https://anymodel.org/en/skills/cloudflare/durable-objects/SKILL.md -o ~/.claude/skills/durable-objects/LICENSE https://anymodel.org/en/skills/cloudflare/durable-objects/LICENSE -o ~/.claude/skills/durable-objects/references/rules.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/rules.md -o ~/.claude/skills/durable-objects/references/skill-feedback.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/skill-feedback.md -o ~/.claude/skills/durable-objects/references/testing.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/testing.md -o ~/.claude/skills/durable-objects/references/workers.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/workers.md
curl -fsSL --create-dirs -o ~/.agents/skills/durable-objects/SKILL.md https://anymodel.org/en/skills/cloudflare/durable-objects/SKILL.md -o ~/.agents/skills/durable-objects/LICENSE https://anymodel.org/en/skills/cloudflare/durable-objects/LICENSE -o ~/.agents/skills/durable-objects/references/rules.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/rules.md -o ~/.agents/skills/durable-objects/references/skill-feedback.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/skill-feedback.md -o ~/.agents/skills/durable-objects/references/testing.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/testing.md -o ~/.agents/skills/durable-objects/references/workers.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/workers.md
foreach ($f in 'SKILL.md','LICENSE','references/rules.md','references/skill-feedback.md','references/testing.md','references/workers.md') { $p = Join-Path "$HOME\.claude\skills\durable-objects" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/cloudflare/durable-objects/$f" -UseBasicParsing -OutFile $p }foreach ($f in 'SKILL.md','LICENSE','references/rules.md','references/skill-feedback.md','references/testing.md','references/workers.md') { $p = Join-Path "$HOME\.agents\skills\durable-objects" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/cloudflare/durable-objects/$f" -UseBasicParsing -OutFile $p }Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/cloudflare/durable-objects/SKILL.md
SKILL.md
Durable Objects
Build stateful, coordinated applications on Cloudflare's edge using Durable Objects.
Retrieval Sources
Your knowledge of Durable Objects APIs and configuration may be outdated. Prefer retrieval over pre-training for any Durable Objects task.
Fetch the relevant doc page when implementing features.
When to Use
- Creating new Durable Object classes for stateful coordination
- Implementing RPC methods, alarms, or WebSocket handlers
- Reviewing existing DO code for best practices
- Configuring wrangler.jsonc/toml for DO bindings and migrations
- Writing tests with Cloudflare’s Vitest integration
- Designing sharding strategies and parent-child relationships
Reference Documentation
./references/rules.md- Core rules, storage, concurrency, RPC, alarms- Testing reference - Current Vitest documentation, migration choices, and test selection
- Workers reference - Workers handlers, types, configuration, tracing, and local debugging
Search: blockConcurrencyWhile, idFromName, getByName, setAlarm, sql.exec
Core Principles
Use Durable Objects For
| Need | Example |
|---|---|
| Coordination | Chat rooms, multiplayer games, collaborative docs |
| Strong consistency | Inventory, booking systems, turn-based games |
| Per-entity storage | Multi-tenant SaaS, per-user data |
| Persistent connections | WebSockets, real-time notifications |
| Scheduled work per entity | Subscription renewals, game timeouts |
Do NOT Use For
- Stateless request handling (use plain Workers)
- Maximum global distribution needs
- High fan-out independent requests
Quick Reference
Wrangler Configuration
// wrangler.jsonc
{
"durable_objects": {
"bindings": [{ "name": "MY_DO", "class_name": "MyDurableObject" }]
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }]
}
Basic Durable Object Pattern
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 });
},
};
Critical Rules
- Model around coordination atoms - One DO per chat room/game/user, not one global DO
- Use
getByName()for deterministic routing - Same input = same DO instance - Use SQLite storage - Configure
new_sqlite_classesin migrations - Initialize in constructor - Use
blockConcurrencyWhile()for schema setup only - Use RPC methods - Not fetch() handler (compatibility date >= 2024-04-03)
- Persist first, cache second - Always write to storage before updating in-memory state
- One alarm per DO -
setAlarm()replaces any existing alarm
Authorization
Durable Objects do not have separate roles or permissions; access follows the Worker that implements them. Retrieve the current Durable Objects authorization guidance before granting observability or Data Studio access, and scope the Workers role to the intended Worker or Workers product.
Anti-Patterns (NEVER)
- Single global DO handling all requests (bottleneck)
- Using
blockConcurrencyWhile()on every request (kills throughput) - Storing critical state only in memory (lost on eviction/crash)
- Using
awaitbetween related storage writes (breaks atomicity) - Holding
blockConcurrencyWhile()acrossfetch()or external I/O
Stub Creation
// 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);
Storage Operations
// 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");
Alarms
// 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();
Testing
Read the testing reference before configuring a suite or writing Durable Object tests. It routes to current setup, APIs, and examples and identifies the behavior to cover.
Skill feedback
If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.
Подключить через AnyModel API
Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.
AnyModel