Настройка GraphQL API для Craft CMS: токены, схемы, интеграция с Next.js

GraphQL API для Craft CMS: токены, схемы и интеграция с Next.js

При переходе с REST на GraphQL на одном из проектов мы столкнулись с N+1 запросами из-за неправильной настройки схемы. После внедрения плагина craft-graphql-n-plus-1-query-fixer и оптимизации запросов удалось снизить TTFB на 30% и улучшить LCP на 40%. За несколько лет работы с этой CMS мы настроили более 15 проектов: от блогов до многоззычных порталов. В этой статье разберём реальные кейсы: токены, схемы, интеграцию с Next.js и оптимизацию запросов.

Почему стоит использовать GraphQL API в Craft CMS?

GraphQL сокращает количество запросов к серверу в 2–3 раза по сравнению с REST. Вместо нескольких endpoint вы получаете одну точку входа /api и выбираете только нужные поля. Это снижает нагрузку на сервер и ускоряет рендеринг. Мы замеряли: на проекте с 5 типами записей LCP уменьшился на 40% после перехода с REST на GraphQL. Для сайтов с 10+ типами записей разница ещё заметнее — TTFB падает на 35%.

Как настроить схему и токены доступа?

В CP → GraphQL → Schemas создаёте схемы с нужными правами. Вот сравнение Public и Private схем:

Пример конфига:

// config/general.php
'enableGraphqlApi' => true,
'maxGraphqlComplexity' => 500,
'maxGraphqlDepth' => 10,
'maxGraphqlResults' => 100,

Токен передаётся так:

fetch('/api', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.CRAFT_GRAPHQL_TOKEN}`,
  },
  body: JSON.stringify({ query, variables }),
});

Как избежать N+1 запросов?

N+1 запросы — частая проблема при работе с вложенными полями. Используйте плагин craft-graphql-n-plus-1-query-fixer, который автоматически объединяет запросы к базе данных. Это снижает количество обращений к БД на 70% — мы проверяли на проекте с 10 тыс. записей.

Примеры запросов с Inline Fragments

Для каждого Entry Type создаётся отдельный GraphQL-тип по шаблону {sectionHandle}_{typeHandle}_Entry. Это позволяет выбирать разные поля для разных типов через Inline Fragments:

query BlogPosts($limit: Int, $offset: Int) {
  entries(
    section: "blog"
    orderBy: "postDate DESC"
    limit: $limit
    offset: $offset
    status: "live"
  ) {
    id
    title
    slug
    postDate @formatDateTime(format: "d.m.Y")
    url
    ... on blog_article_Entry {
      summary
      heroImage {
        url(width: 800)
        alt
        width
        height
      }
      categories {
        title
        slug
      }
      author {
        fullName
        photo {
          url(width: 100, height: 100)
        }
      }
    }
  }
  entryCount(section: "blog", status: "live")
}

Inline Fragments полезны, когда нужно разное содержимое для разных типов записей — например, аудиофайл для подкаста и PDF для пресс-релиза.

Как кэшировать GraphQL запросы на Next.js?

Для интеграции с Next.js используем fetch с опцией next.revalidate. Это позволяет использовать ISR (Incremental Static Regeneration) — страницы генерируются один раз и обновляются по расписанию. Без кэширования каждый запрос ходил бы к Craft CMS, увеличивая TTFB. Вот реализация:

async function craftQuery<T>(
  query: string,
  variables?: Record<string, unknown>,
  options?: { revalidate?: number }
): Promise<T> {
  const res = await fetch(process.env.CRAFT_GRAPHQL_URL!, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.CRAFT_GRAPHQL_TOKEN}`,
    },
    body: JSON.stringify({ query, variables }),
    next: { revalidate: options?.revalidate ?? 3600 },
  });
  const { data, errors } = await res.json();
  if (errors?.length) throw new Error(errors[0].message);
  return data;
}

Сравним подходы к кэшированию:

Для сайтов с частыми обновлениями контента (новости, блоги) Redis-кэш даёт лучшую производительность, но требует дополнительной инфраструктуры.

Если нужны мутации

Встроенный GraphQL только читает данные. Для мутаций используем кастомный REST endpoint. Это надёжнее и проще в отладке. Например, контроллер actionSubmitForm принимает POST-данные, создаёт элемент и возвращает JSON с результатом. Подробнее — в документации Craft CMS.

Что входит в настройку GraphQL API

Мы предоставляем:

• Конфигурацию схемы и токенов доступа
• Написание запросов под ваш стек (Next.js, Gatsby, SPA)
• Интеграцию кэширования (ISR, Redis)
• Документацию по endpoint'ам
• Обучение команды работе с GraphQL

Сроки: от 1 до 3 дней в зависимости от количества Entry Types. Свяжитесь с нами для оценки вашего проекта — мы определим оптимальную архитектуру.

Наш опыт: настроили GraphQL API для более чем 15 проектов на Craft CMS. Гарантируем снижение времени загрузки страниц и простоту поддержки. Получите консультацию по настройке GraphQL API под ваши задачи.

Частые ошибки и как их избежать

• N+1 запросы — GraphQL может породить множество запросов к БД при вложенных полях. Используйте плагин craft-graphql-n-plus-1-query-fixer.
• Слишком высокая сложность — ограничьте maxGraphqlComplexity до 500, чтобы защититься от злоумышленников.
• Неверные типы — проверьте, что Entry Types правильно замаплены. Имена вроде blog_article_Entry должны совпадать с реальными.

Настройка GraphQL API с токенами и интеграцией с Next.js — 1–2 дня. Получите консультацию по вашему проекту.