Вы написали 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.
Почему стоит автоматизировать генерацию типов?
Ручная поддержка типов — источник багов и потери времени. Сравните:
| Критерий | Без codegen | С codegen |
|---|---|---|
| Время на синхронизацию | 4–6 часов в неделю | 0 часов |
| Ошибки несоответствия | 15–20% PR | 0% |
| Уверенность в коде | Низкая | Высокая |
Экономия времени напрямую конвертируется в деньги: при ставке $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 Как мы это делаем: процесс внедрения
- Анализ схемы и операций. Изучаем текущую схему, документы и файловую структуру. Выявляем частые паттерны — маппинги, контекст, nullability.
- Настройка конфигурации. Описываем
codegen.yml: указываем schema, documents, целевые плагины и маппинги. УчитываемavoidOptionalsиenumsAsTypesдля строгости. - Генерация и тестирование. Запускаем codegen, проверяем, что все типы корректны, и компилируем проект. Включаем strict mode и TypeScript.
- Интеграция CI/CD. Добавляем скрипт в
package.jsonи workflow для GitHub Actions — проверяем, что сгенерированные файлы закоммичены и синхронизированы. - Документация и передача. Описываем процесс для команды, настраиваем 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 и опыт работы с кодогенерацией на проектах любой сложности.