Интеграция KeystoneJS с фронтендом через GraphQL API

Интеграция KeystoneJS с фронтендом через GraphQL API

Проблема: KeystoneJS генерирует GraphQL API, но при интеграции с фронтендом часто возникает рассогласование типов — фронтенд использует поля, которых нет в схеме, или допускает ошибки в мутациях. Пагинация через take/skip без правильного кэширования приводит к дублированию записей, а аутентификация требует аккуратной настройки middleware. Мы, команда с опытом работы с KeystoneJS более 5 лет, настраивали эту связку для 30+ проектов, что позволило сократить количество багов на 90% и ускорить релизы в 2 раза. Типичная интеграция на Next.js + Apollo Client с codegen занимает 3–5 дней под ключ. Получите аудит вашей схемы KeystoneJS — мы найдём узкие места и предложим план интеграции.

Что генерирует KeystoneJS

Для каждого List, например Post, создаются стандартные запросы и мутации (KeystoneJS GraphQL API):

• post(where: PostWhereUniqueInput!): Post
• posts(where: PostWhereInput, orderBy: [...], take: Int, skip: Int): [Post!]
• postsCount(where: PostWhereInput): Int
• createPost(data: PostCreateInput!): Post
• createPosts(data: [PostCreateInput!]!): [Post]
• updatePost(where: PostWhereUniqueInput!, data: PostUpdateInput!): Post
• deletePost(where: PostWhereUniqueInput!): Post

Это избавляет от написания повторяющегося кода. Однако без codegen легко ошибиться в имени поля или забыть выбрать вложенные связи (N+1 проблема), что увеличивает стоимость доработок на 30-50%.

Как настроить Apollo Client для KeystoneJS?

Apollo Client — самый популярный GraphQL-клиент для React. Настройка включает HTTP-ссылку на эндпоинт, middleware для аутентификации и обработку ошибок. Вот пример для Next.js с поддержкой cookie-сессий (Apollo Client documentation):

// lib/apollo.ts
import { ApolloClient, InMemoryCache, createHttpLink, from } from '@apollo/client';
import { setContext } from '@apollo/client/link/context';
import { onError } from '@apollo/client/link/error';

const httpLink = createHttpLink({
  uri: process.env.NEXT_PUBLIC_KEYSTONE_URL + '/api/graphql',
  credentials: 'include',
});

const authLink = setContext((_, { headers }) => ({
  headers: {
    ...headers,
    authorization: getToken() ? `Bearer ${getToken()}` : '',
  },
}));

const errorLink = onError(({ graphQLErrors }) => {
  if (graphQLErrors?.some(e => e.extensions?.code === 'UNAUTHENTICATED')) {
    window.location.href = '/login';
  }
});

export const apolloClient = new ApolloClient({
  link: from([errorLink, authLink, httpLink]),
  cache: new InMemoryCache({
    typePolicies: {
      Query: {
        fields: {
          posts: {
            keyArgs: ['where', 'orderBy'],
            merge: (existing = [], incoming) => [...existing, ...incoming],
          },
        },
      },
    },
  }),
});

Этот блок объединяет аутентификацию и пагинацию. По сравнению с прямым использованием fetch, Apollo Client даёт автоматическое кэширование, инвалидацию и удобные хуки — сокращение кода на 40%.

Почему codegen ускоряет разработку в 3 раза

GraphQL Code Generator создаёт TypeScript-типы и хуки по вашей схеме. Конфигурация тривиальна:

---
# codegen.yml
schema: http://localhost:3000/api/graphql
documents: "src/**/*.graphql"
generates:
  src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo

Пример запроса:

# src/queries/posts.graphql
query GetPosts($where: PostWhereInput, $take: Int, $skip: Int) {
  posts(where: $where, take: $take, skip: $skip, orderBy: [{ publishedAt: desc }]) {
    id
    title
    slug
    publishedAt
    status
    author {
      id
      name
    }
    tags {
      id
      name
    }
  }
  postsCount(where: $where)
}

После генерации вы получаете готовые хуки с автодополнением. Это полностью исключает ошибки в названиях полей и запросах, экономя до 60% времени на отладку.

Как использовать в Next.js Server Components

В Server Components запросы выполняются на стороне сервера. Используем серверный клиент Apollo:

// app/blog/page.tsx
import { getClient } from '@/lib/apollo-server';
import { GetPostsDocument } from '@/generated/graphql';

export default async function BlogPage({ searchParams }) {
  const page = Number(searchParams.page) || 1;
  const { data } = await getClient().query({
    query: GetPostsDocument,
    variables: {
      where: { status: { equals: 'published' } },
      take: 10,
      skip: (page - 1) * 10
    },
  });
  return <PostGrid posts={data.posts} total={data.postsCount} page={page} />;
}

Мутации в Client Components

Для операций записи используем клиентские компоненты:

'use client';
import { useMutation } from '@apollo/client';
import { CreatePostDocument } from '@/generated/graphql';

export function NewPostForm() {
  const [createPost, { loading, error }] = useMutation(CreatePostDocument, {
    update(cache, { data }) {
      cache.evict({ fieldName: 'posts' });
    },
  });

  const handleSubmit = async (formData) => {
    const { data } = await createPost({
      variables: {
        data: {
          title: formData.title,
          slug: formData.slug,
          content: { document: formData.content },
          author: { connect: { id: currentUserId } },
          status: 'draft',
        },
      },
    });
    router.push(`/admin/posts/${data?.createPost?.id}`);
  };
}

Сравнение Apollo Client vs fetch

Использование Apollo Client сокращает время разработки на 2–3 дня по сравнению с чистым fetch, что существенно экономит бюджет проекта.

Как избежать типичных ошибок при интеграции?

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

1. Анализ схемы KeystoneJS — проверка Lists, связей, разрешений и триггеров.
2. Настройка Apollo Client — создание серверного и клиентского инстансов с middleware.
3. Конфигурация codegen — генерация TypeScript-типов и хуков.
4. Реализация запросов — избранный List, пагинация, сортировка.
5. Реализация мутаций — CRUD для административных интерфейсов.
6. Аутентификация — сессионная или JWT, защита маршрутов.
7. Тестирование — Unit-тесты на Apollo MockedProvider.

Что входит в услугу интеграции

• Аудит существующей конфигурации KeystoneJS.
• Настройка Apollo Client с оптимизацией кэша.
• Генерация типов GraphQL Code Generator.
• Реализация запросов и мутаций для критических List’ов.
• Интеграция аутентификации (сессионная / JWT).
• Документация по использованию сгенерированных хуков.
• Поддержка 2 недели после сдачи.

Гарантируем, что все запросы проходят code review и тестирование. Закажите консультацию, чтобы мы проанализировали вашу текущую схему и предложили оптимальный план интеграции.

Опыт нашей команды

Мы работаем с KeystoneJS и GraphQL с 2019. За это время выполнили 30+ проектов, включая интеграцию с интернет-магазинами, SaaS-платформами и корпоративными порталами. Средний NPS — 9.2. Экономия бюджета заказчиков составила до 60% по сравнению с альтернативными решениями. Свяжитесь с нами, чтобы обсудить ваш проект.