Cloudflare Workers + D1: архитектура быстрой API-интеграции без VPS

Webhook-интеграция начинает тормозить не только из-за внешнего API. Частая причина — сама цепочка обработки: событие приходит в один сервис, тот каждый раз читает удалённую таблицу, затем вызывает ещё один сервис и только после этого отвечает пользователю.

Для ботов, каталогов, CRM-связок и других сценариев с большим количеством коротких запросов полезно отделить рабочий контур от панели управления. Cloudflare Worker может принимать события и выполнять бизнес-логику, а D1 — хранить данные, которые нужны этой логике прямо сейчас.

Ниже — практическая схема, которая помогает понять, когда связка Cloudflare Workers + D1 уместна, как организовать синхронизацию, защиту от дублей и секреты и где лучше выбрать другой инструмент.

Почему Worker и D1 стоит разделять по ролям

Worker — это место выполнения кода. Он принимает HTTP-запрос, проверяет подпись или секрет, нормализует входные данные, выбирает сценарий и вызывает внешние API. D1 — SQL-хранилище, доступное Worker через binding. В конфигурации binding получает имя, по которому база доступна в коде.

Такое разделение полезно тем, что бизнес-логика не превращается в набор обращений к Google Sheets, CRM или другому внешнему источнику на каждом пользовательском действии. Таблица может остаться удобной панелью для менеджера, но Worker читает рабочую копию настроек из D1.

Если требуется спроектировать подобную цепочку под заявки, каталог или внутренний сервис, это относится к автоматизации бизнес-процессов и API/CRM-интеграциям.

Какие данные имеет смысл хранить в D1

Не нужно переносить в D1 всё подряд. Начать лучше с данных, которые участвуют в обработке запросов и должны быстро находиться по ключу.

Персональные и чувствительные данные стоит минимизировать: хранить только то, что действительно требуется сценарию, определить срок жизни записей и не использовать базу как бесконтрольный архив входящих payload.

Подключение D1 к Worker

Cloudflare документирует D1 binding как штатный способ обращаться к базе из Worker. Имя binding становится переменной окружения, например DB. Идентификатор базы относится к конфигурации, а секретные API-ключи внешних сервисов туда помещать не нужно.

[[d1_databases]]
binding = "DB"
database_name = "integration-db"
database_id = "YOUR_DATABASE_ID"

Для пользовательских значений в SQL лучше применять prepared statements и параметры. В документации D1 отдельный Workers Binding API строится вокруг подготовки выражения, bind и выполнения запроса. Метод exec() Cloudflare рекомендует оставлять для служебных и разовых операций; для прикладных запросов подготовленные выражения безопаснее и обычно удобнее.

const row = await env.DB
  .prepare('SELECT value FROM settings WHERE key = ?1')
  .bind('catalog_enabled')
  .first();

Синхронизация: панель управления отдельно, рабочая база отдельно

Если сотрудники привыкли менять товары, цены, FAQ или сценарии в Google Sheets, необязательно заставлять их работать с новой админкой. Таблица может остаться источником редактирования, а небольшой sync-скрипт отправляет в Worker только изменившиеся записи.

Лучше передавать изменения, а не всю таблицу

Для каждой записи полезно иметь стабильный внешний ID и отметку обновления. Worker получает пакет изменений, валидирует поля и делает upsert в D1. Полная пересборка каталога тоже возможна, но её разумнее оставлять для первоначальной загрузки или восстановления.

POST https://example.com/sync
Content-Type: application/json
Authorization: Bearer EXAMPLE_TOKEN

{
  "items": [
    {"external_id": "p-101", "name": "Example", "active": true}
  ]
}

В рабочем проекте токен нельзя записывать в код, JSON статьи или публичный репозиторий. На стороне Worker Cloudflare предлагает хранить API-ключи и токены в Secrets и получать их через env.

Защита от повторных webhook

Повторная доставка события — нормальная ситуация для интеграций. Сетевой таймаут не означает, что предыдущая попытка не успела выполнить действие. Поэтому обработчик должен быть идемпотентным.

Практический вариант — перед основной операцией записывать уникальный event_id в таблицу событий с уникальным индексом. Если тот же идентификатор приходит повторно, Worker возвращает успешный ответ без второго создания заказа, сообщения или карточки.

CREATE TABLE processed_events (
  event_id TEXT PRIMARY KEY,
  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);

Для действий, где внешняя система сама поддерживает idempotency key, полезно передавать тот же стабильный ключ дальше по цепочке. Если такой возможности нет, соответствие локального события и внешнего ID нужно хранить у себя.

Обработка ошибок без бесконечных повторов

Ошибки стоит разделять хотя бы на три группы. Ошибка валидации означает, что payload нужно отклонить и зафиксировать причину. Временная ошибка внешнего API допускает ограниченный повтор. Логическая ошибка — например, отсутствующее соответствие товара — требует отдельного статуса и проверки данных.

Нельзя автоматически повторять любую ошибку без лимита. Такой цикл способен умножить запросы и создать дубли в системе назначения. В логах при этом не должны появляться секреты, полные заголовки Authorization и лишние персональные данные.

Безопасность Worker-интеграции

Cloudflare прямо рекомендует использовать Secrets для API-ключей и токенов, а не plaintext variables в конфигурации. Локальные .dev.vars и .env также не следует коммитить в Git.

Кроме хранения секретов, для входящего endpoint нужны проверка метода, Content-Type, ограничение размера тела, аутентификация отправителя и строгая схема допустимых полей. Если источник поддерживает подпись webhook, лучше проверять подпись, а не доверять одному публичному URL.

Когда Workers + D1 подходит

Связка особенно удобна для webhook, ботов, небольших каталогов, таблиц соответствий, настроек, idempotency и API-шлюзов, где запросы короткие, а данные естественно укладываются в SQL-модель. D1 доступна и на Workers Free, и на Workers Paid; актуальные лимиты и тарификацию перед запуском нужно сверять на официальной странице pricing, потому что они могут меняться.

Cloudflare указывает ограничение размера отдельной D1-базы в 10 GB и описывает подход с несколькими меньшими базами для отдельных пользователей, арендаторов или сущностей. Это важно учитывать заранее, если интеграция должна хранить большой исторический массив.

Когда лучше выбрать другой вариант

D1 не является универсальной заменой PostgreSQL, очереди, аналитического хранилища или файлового storage. Если система требует тяжёлых транзакций, больших объёмов аналитики, специфичных расширений PostgreSQL либо уже построена вокруг существующей SQL-базы, стоит сравнить D1 с внешней базой и Hyperdrive.

Если задача состоит только из нескольких действий раз в день, иногда проще оставить Google Apps Script, Make или n8n. Архитектура должна сокращать количество движущихся частей, а не добавлять Worker и базу ради самого факта использования Cloudflare.

Что проверить после запуска

Проверка должна включать не только успешный запрос. Отправьте одно событие дважды, временно подставьте несуществующий внешний ID, проверьте невалидный JSON и имитируйте недоступность API назначения. После этого убедитесь, что D1 содержит ожидаемое состояние, а повторный webhook не создал второй объект.

Если нужна архитектура под конкретный каталог, бот, CRM или синхронизацию, можно описать задачу A.S Groups: источник данных, куда их нужно передавать, частоту изменений и текущие ограничения.

Официальные источники

• Cloudflare D1 — Workers Binding API
• Cloudflare D1 — D1 Database API
• Cloudflare Workers — Wrangler configuration
• Cloudflare Workers — Secrets
• Cloudflare Workers — Connect to databases
• Cloudflare Workers — Pricing