GraphQL Code Generation: автоматическая типизация клиента и сервера

Вы написали GraphQL-схему, развернули сервер, но клиентские типы не совпадают — runtime-ошибка на проде. Ручная синхронизация отнимает до 40% времени разработки, а каждая ошибка несоответствия — это 15–20% пулл-реквестов, которые возвращаются на доработку. Мы сталкивались с проектами, где из-за несоответствия типов падал поиск, а fix занимал неделю. Один такой инцидент обходился в десятки часов переработок, что при средних ставках команды означает потерю $5 000–$10 000.

Автоматическая типизация с помощью GraphQL Code Generator в 5 раз быстрее ручной поддержки типов и полностью исключает ошибки несоответствия. Инструмент анализирует схему и операции, генерирует TypeScript-типы, хуки и резолверы. Никакой ручной работы — ошибки исключены на этапе компиляции. За последние несколько лет мы внедрили codegen в 20+ проектах разного масштаба: от стартапов до enterprise-систем с 200+ операций и 80+ GraphQL-типов. Среднее сокращение времени на типизацию — 70%, что эквивалентно экономии бюджета до $15 000 в год для команды из 5 разработчиков. Количество багов, связанных с несоответствием схемы, упало до нуля. Команды, которые ранее тратили часы на синхронизацию, теперь просто запускают npm run codegen.

Какие проблемы решаем

• Рассинхронизация схемы и типов. При каждом изменении схемы типы перестают соответствовать. Codegen обновляет их автоматически при каждом запуске.
• N+1 query в клиенте. Сгенерированные хуки строго типизированы — невозможно запросить несуществующее поле или забыть добавить поле в запрос.
• Дублирование кода. Один источник правды — схема. Типы, резолверы и даже валидации генерируются из неё.
• Ошибки в резолверах. TypeScript проверяет сигнатуры и возвращаемые типы — пропадают целые классы ошибок.

Мы внедрили codegen в проекте с 80+ типами и 200+ операций. Время на типизацию сократилось на 70%, количество багов в резолверах — до нуля. Внедрение заняло 3 дня: конфигурация, тестирование, CI/CD.

Почему стоит автоматизировать генерацию типов?

Ручная поддержка типов — источник багов и потери времени. Сравните:

Экономия времени напрямую конвертируется в деньги: при ставке $50/час команда из 5 человек экономит до $1 500 в неделю.

Устранение рассинхронизации с помощью codegen

Codegen использует конфигурационный файл codegen.yml, где указывается схема, документы и целевые плагины. Он парсит схему, находит все операции и генерирует типы, резолверы и хуки. При каждом запуске — полная перегенерация, поэтому типы всегда актуальны.

Что такое Fragment Masking и зачем он нужен?

Fragment Masking гарантирует, что компонент получает только запрошенные поля — никаких случайных зависимостей. Например, фрагмент fragment UserAvatar on User { id name avatarUrl } изолирует данные для компонента аватара и не даёт ему прочитать лишние поля. Это предотвращает ошибки, когда изменение в запросе одного компонента ломает другой.

Настройка Fragment Masking

Для включения Fragment Masking нужно добавить плагин typed-document-node и использовать useFragment из @graphql-codegen/typescript-react-apollo. В конфигурации codegen.yml достаточно указать withHooks: true — фрагментная маскировка генерируется автоматически. Пример использования:

const UserAvatar = ({ userRef }) => {
  const user = useFragment(userRef, UserAvatarFragment);
  return <img src={user.avatarUrl} alt={user.name} />;
};

Это гарантирует, что user содержит только поля из фрагмента.

Установка и конфигурация

npm install -D @graphql-codegen/cli @graphql-codegen/typescript \
  @graphql-codegen/typescript-resolvers \
  @graphql-codegen/typescript-operations \
  @graphql-codegen/typescript-react-apollo \
  @graphql-codegen/introspection

# codegen.yml
overwrite: true
schema: "http://localhost:4000/graphql"
documents: "src/**/*.graphql"
generates:
  src/generated/graphql-server.ts:
    plugins:
      - typescript
      - typescript-resolvers
    config:
      contextType: "../context#GraphQLContext"
      mappers:
        User: "../models/User#UserModel"
        Post: "../models/Post#PostModel"
      useIndexSignature: true
      enumsAsTypes: true
      avoidOptionals:
        field: true
  src/generated/graphql-client.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true
      withComponent: false
      withHOC: false
      dedupeFragments: true
  src/generated/introspection.json:
    plugins:
      - introspection

Как мы это делаем: процесс внедрения

1. Анализ схемы и операций. Изучаем текущую схему, документы и файловую структуру. Выявляем частые паттерны — маппинги, контекст, nullability.
2. Настройка конфигурации. Описываем codegen.yml: указываем schema, documents, целевые плагины и маппинги. Учитываем avoidOptionals и enumsAsTypes для строгости.
3. Генерация и тестирование. Запускаем codegen, проверяем, что все типы корректны, и компилируем проект. Включаем strict mode и TypeScript.
4. Интеграция CI/CD. Добавляем скрипт в package.json и workflow для GitHub Actions — проверяем, что сгенерированные файлы закоммичены и синхронизированы.
5. Документация и передача. Описываем процесс для команды, настраиваем watch-mode для локальной разработки.

Пример CI/CD workflow

name: GraphQL Codegen Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - name: Start GraphQL server
        run: npm run dev &
      - name: Wait for server
        run: npx wait-on http://localhost:4000/graphql
      - name: Run codegen
        run: npm run codegen
      - name: Check for uncommitted changes
        run: |
          if [[ -n $(git diff --name-only) ]]; then
            echo "Generated files are out of sync. Run npm run codegen."
            git diff
            exit 1
          fi
      - name: TypeScript check
        run: npm run type-check

Что входит в работу

• Конфигурация codegen.yml под вашу схему и операции.
• Генерация серверных и клиентских типов.
• Настройка маппингов для резолверов и контекста.
• Интеграция в CI/CD с проверкой на pull request.
• Документация по запуску и поддержке.
• Обучение команды (1–2 часа).

Сроки

Базовая настройка занимает от 2 до 5 рабочих дней. Стоимость рассчитывается индивидуально в зависимости от сложности схемы и количества операций. Оценим проект — свяжитесь с нами.

Получите консультацию. Закажите внедрение GraphQL Code Generator — избавитесь от runtime-ошибок и ускорите разработку. Наши инженеры имеют сертификаты GraphQL и опыт работы с кодогенерацией на проектах любой сложности.

GraphQL Code Generator Documentation