workers-best-practices

Официальный навык Cloudflare для написания и ревью кода Workers, конфигурации wrangler.jsonc и проверки типичных производственных ошибок. Его область охватывает потоковую обработку, promises, состояние на уровне модуля, секреты, bindings и observability. Главный принцип навыка — не угадывать актуальные API по памяти: перед ревью или разработкой нужно получить свежие правила Workers, типы и схему конфигурации. В качестве ориентиров он указывает страницу Cloudflare Workers Best Practices, определения workers-types и схему Wrangler; это делает проверку зависимой от текущих опубликованных контрактов платформы, а не от устаревшего примера. Для новой конфигурации навык предлагает задать compatibility_date и периодически обновлять её в существующих проектах, включить nodejs_compat при необходимости Node.js built-ins, генерировать типы Env командой wrangler types и хранить настройки в wrangler.jsonc. Секреты не следует помещать в исходный код или конфигурацию: для них предусмотрен wrangler secret put. Важна и граница между настройкой и кодом: интерфейс окружения должен следовать реальным bindings, а не быть вручную написанным типом, который со временем расходится с конфигурацией. В обработке запросов навык рекомендует потоково читать большие или неизвестные по размеру ответы, а не безусловно вызывать response.text() для неограниченного тела. Работу после ответа нужно передавать через ctx.waitUntil(); контекст не следует деструктурировать, поскольку потеря привязки this приводит к ошибке Illegal invocation. Каждое Promise должно быть await-нуто, возвращено, явно погашено через void или передано в waitUntil. Это помогает не терять результаты и исключения фоновой работы. Архитектурные рекомендации сводятся к использованию in-process bindings для KV, R2, D1 и Queues вместо REST-вызовов Cloudflare, service bindings для обращений Worker к Worker и Hyperdrive для внешних подключений к PostgreSQL или MySQL. Очереди и Workflows подходят для асинхронной работы, которую не нужно держать на критическом пути ответа. Для наблюдаемости навык выделяет observability, head_sampling_rate и структурированные JSON-логи. Для безопасности он требует Web Crypto, например crypto.randomUUID() или crypto.getRandomValues(), вместо Math.random() для токенов и идентификаторов, а ошибки предлагает обрабатывать явным try/catch со структурированным ответом, не пряча проблему через passThroughOnException. Практический сценарий — пройти этот чеклист перед публикацией Worker или при ревью pull request: сверить compatibility date, bindings и типы Env; найти плавающие promises и глобальное состояние запроса; проверить streaming и waitUntil; убедиться, что секреты не попали в git; затем проверить настройки observability и вызовы внешних сервисов. Навык не является самостоятельным security-аудитом и не заменяет актуальную документацию Cloudflare: для Durable Objects, Workflows и CLI-команд он прямо направляет к специализированным источникам. Его ценность — в воспроизводимой проверке тех мест, где короткий пример Worker легко становится проблемой памяти, утечкой состояния, потерянной фоновой задачей или неявной ошибкой конфигурации.