Миграция на Headless Drupal: Практическое руководство и кейс перехода с монолита

Практический кейс для существующих проектов

Что такое headless Drupal и зачем это вам

Традиционный Drupal жёстко связывает управление контентом с рендерингом страниц: бэкенд хранит данные, а Twig-шаблоны и PHP отвечают за их вывод. В headless-архитектуре эта связка разрывается — Drupal остаётся только контентным API (через JSON:API, GraphQL или REST), а витрину строит отдельный фронтенд-фреймворк: React, Vue, Next.js.

На практике это даёт три заметных эффекта:

• Скорость и производительность. Статическая генерация или серверный рендеринг современных фреймворков снимает с Drupal накладные расходы на рендеринг PHP. По оценкам, decoupled-архитектуры ускоряют отклик в среднем на 35%.
• Мультиканальность. Один API обслуживает сайт, мобильное приложение, киоски и IoT-устройства — контент не нужно дублировать.
• Свобода фронтенда. Команда больше не обязана знать Twig и PHP, а может использовать привычный стек.

Когда переход оправдан (а когда нет)

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

Ключевой момент: ключ к успеху — это выравнивание архитектуры с целями, а не с трендами. Не переводите сайт в headless только ради того, чтобы «быть современными».

Две стратегии: полная и прогрессивная

Прежде чем говорить о шагах, важно определиться с глубиной развязки:

• Полный decoupled. Drupal работает только как API, темы не используются вовсе, весь рендеринг на фронтенде (React, Next.js, Gatsby, Nuxt). Максимальная гибкость, но теряются встроенные превью, Layout Builder и контекстное редактирование.
• Прогрессивный decoupled. Drupal отдаёт каркас страницы (шапка, подвал, навигация), а интерактивные блоки — React/Vue-компоненты внутри выведенной страницы. Сохраняются редакторские возможности, добавляется интерактив.

Опытные команды часто начинают с прогрессивного подхода и переходят к полному по мере роста зрелости фронтенд-команды. Это же и самый низкорисковый путь: сайт остаётся онлайн, редакторы сохраняют привычный интерфейс, а вы получаете современный фронтенд без большой миграции данных.

Пошаговый план миграции

Шаг 1. Аудит и инвентаризация

Начните с полной картины текущего сайта, а не с написания кода. Соберите:

• все типы контента, поля, таксономии и связи между сущностями;
• пользователей, роли и права;
• интеграции с внешними сервисами, включая прямые запросы к БД;
• точки входа трафика и SEO-критичные URL;
• статистику использования: как правило, 60% пользователей взаимодействуют лишь с 20% контента — это поможет расставить приоритеты.

Отдельно проаудитируйте кастомные модули. В Drupal бизнес-логика часто прячется в хуках hook_node_presave, hook_form_alter и в шаблонах — при переходе её придётся извлекать и переносить в API-роуты или serverless-функции фронтенда. Хорошо задокументированный код кратно снижает сложность миграции.

Шаг 2. Моделируйте контент как API-first

Это, пожалуй, самый недооценённый этап. Контент должен стать презентационно-нейтральным: уберите типы вроде «sidebar block» и вместо этого используйте поля и таксономии для классификации. Решите, как переедет ваше «тело» статьи — HTML-блоб остаётся разметкой, которую фронтенду придётся парсить, тогда как структурированный контент (блоки, ссылки, встроенные компоненты) — это данные, которые можно запрашивать и переиспользовать. Зафиксируйте схемы OpenAPI и прогоняйте их в Postman или Swagger до старта фронтенда — «сырой» меняющийся контракт заставит переписывать интеграции.

Шаг 3. Выберите API: JSON:API или GraphQL

JSON:API включён в ядро с Drupal 9 и автоматически раскрывает все типы контента, таксономии и медиа с фильтрацией, сортировкой и пагинацией — без написания кастомных эндпоинтов. GraphQL стоит взять для сложных моделей данных, где важна точность выборки.

Для продакшена обязательно: включите read-only режим для публичных API, настройте field-level контроль доступа через права Drupal, пропишите CORS в services.yml для вашего фронтенд-домена и настройте кэширование (Varnish или внутренний кэш Drupal). Модуль jsonapi_extras позволит переименовать ресурсы, отключить лишние эндпоинты и задать алиасы полей для чище ответов.

Шаг 4. Соберите фронтенд

Начните с репрезентативного среза, а не со всей витрины сразу: один тип контента, один роут, рабочие GraphQL/JSON:API-запросы, рендеринг, кэширование, превью и мониторинг. Этот срез становится эталонной реализацией и снижает неопределённость перед масштабированием на всю платформу.

Для Next.js есть пакет next-drupal, который берёт на себя выборку через JSON:API, резолв сущностей, preview-режим и алиасы путей. Стратегию рендеринга выбирайте под тип контента:

• SSG — для редко меняющихся страниц (блог, «О нас»);
• ISR — для регулярно обновляемых (новости, карточки товаров);
• SSR — для персонализированного и real-time контента.

Шаг 5. Мигрируйте контент

Используйте Migrate API и модули Migrate Plus / Drush: они позволяют отображать поля, обрабатывать связи и трансформации. Помните о типовой проблеме: сложная схема хранения полей (таблицы field_data_* и field_revision_*) требует аккуратного маппинга на целевую структуру — кардинальность полей, entity references и field collections нужно проектировать заранее.

Прогоняйте миграцию итерациями на staging, сверяя выборки, пока целостность данных не подтвердится.

Шаг 6. Параллельный запуск и поэтапное переключение

Главный принцип — никакого «большого взрыва» или «одномоментного запуска». Запустите старый и новый сайты одновременно через reverse proxy (Nginx), который маршрутизирует трафик по URL-паттернам. Два практичных инструмента для валидации:

• Shadow traffic. Дублируйте часть реального трафика на новый стек «в фоне», незаметно для пользователей. Начните с 5–10%, сверяйте аналитику, затем увеличивайте до 25%, 50% и 100%.
• Поэтапный публичный роллаут. Сначала мигрируйте низкорисковые, но заметные страницы: лендинги, промо-микросайты, статичный контент. Затем блог, новости и ресурсный центр — зоны значимого органического трафика.

После переезда всех публичных страниц отключите старую тему, но не CMS — Drupal остаётся системой контента.

Шаг 7. SEO и редиректы

Это самая частая точка потери трафика при миграции. Перед запуском зафиксируйте текущий набор индексируемых URL, canonical-теги, schema-разметку и open-graph-превью. Составьте полную карту 301-редиректов — для сотен и тысяч старых URL-паттернов понадобятся скрипты миграции. Один сломанный тег или редирект обрушит кликабельность в день запуска.

Подводные камни, о которых молчат гайды

Потеря Views. Переход в headless лишает возможности «просто отобразить» представления. Вы по-прежнему отдаёте данные в JSON, но теперь за получение данных, их рендеринг и отслеживание изменений отвечает код фронтенда.

Бизнес-логика в хуках. В Drupal 7 (и не только) часть логики живёт в хуках и модулях, у которых нет прямого аналога в headless — её нужно аккуратно извлекать и переносить.

Двойной стек и DevOps. С headless вы переходите от одного рантайма к нескольким. Зафиксируйте, кому принадлежит инцидент — Drupal, API-слою или фронтенду, иначе скорость реагирования упадёт.

Версионирование API. Начинайте с /v1/ и планируйте переход на /v2/ заранее, иначе клиенты (например, мобильное приложение) будут ломаться после обновлений бэка.

Практический кейс: учебный портал

Соберём всё воедино на гипотетическом, но реалистичном примере — крупный учебный портал на Drupal 7. Задача та же, что у многих: D7 подходит к концу поддержки, маркетинг не может менять страницы без разработчиков, а бизнесу нужен мобильный клиент на том же контенте.

Что сделали:

1. Аудит + ревизия. Обнаружили, что 40% функциональности почти не используется, а структура курсов — это десятки разрозненных полей. Вместо прямого переноса перепроектировали модель: компоненты через Paragraphs вместо десятков полей.
2. Новый бэкенд на Drupal 10/11. Включили JSON:API, настроили CORS и read-only режим, спроектировали чистую API-модель.
3. Фронтенд на Next.js. Выбрали ISR для страниц курсов и SSG для статики. Мобильное приложение подключилось к тому же API.
4. Инкрементальная миграция. Начали с самых популярных разделов, перенесли контент через Migrate API с трансформацией данных (примеры: обновление формата изображений, склейка нескольких полей в один paragraph-компонент).
5. Параллельный запуск. Старый и новый сайты жили одновременно через reverse proxy; трафик переключали по разделам, сверяя аналитику shadow-трафика.
6. SEO-карта. Полная карта 301-редиректов сохранила индексацию и позиции.

Результат: единый API для сайта и приложения, страницы отдаются за сотни миллисекунд вместо 2–3 секунд, новые фичи выходят за дни вместо недель, а маркетинг получил компоненты, которые собирает без разработчика.

Что сделали бы иначе: с самого начала зафиксировали бы OpenAPI-контракты и мониторинг (Sentry, Loki) — первые баги API ловили пользователи, а не команда.

FAQ по миграции

• Как мигрировать Views?
  • Разбейте логику Views на отдельные эндпоинты API или перенесите в серверные функции (Serverless Functions), если они нужны для динамического рендеринга.
• Что делать с кастомными модулями?
  • Извлеките бизнес-логику из хуков, перепишите её как отдельные роуты или middleware, затем постепенно отключайте старый код.
• Как сохранить редакторские возможности?
  • Используйте прогрессивный decoupled подход: Drupal отдаёт каркас страницы, а редактор работает в привычном интерфейсе, но контент рендерится на фронтенде.

Выводы

Переход на headless — это не «перенесли и переключили DNS», а управляемая эволюция с измеримыми критериями качества. Три принципа, которые уберегут от провала:

1. Инвентаризация и аудит сначала. Логика, спрятанная в хуках и шаблонах, и недокументированные интеграции — главный источник сюрпризов.
2. Никакого «большого взрыва» или «одномоментного запуска». Параллельный запуск, shadow-трафик, поэтапный роллаут — риск изолируется на подмножестве роутов в любой момент времени.
3. Сохраняйте то, что работает. Отключайте тему, но не CMS: редакторские процессы и структура контента, которые уже работают, должны жить дальше.

Headless-миграция Drupal — это не столько перенос данных, сколько возможность переосмыслить проект: убрать технический долг и заложить фундамент для новых каналов. Делайте это вдумчиво, по фазам, и ваш портал получит не «новый Drupal», а платформу, готовую к будущему.