Developer

graphql-codegen и graphql-request

↑ 5.4 Работа с API: REST, GraphQL, WebSocket · ← Предыдущая · → Следующая

Обязательно~3 мин чтенияУровень: middle

Зачем это на собесе

Типобезопасный GraphQL-клиент: как получить типы из схемы и документов.

Объяснение

GraphQL Code Generator читает схему (schema.graphql или URL/introspection) и документы (*.graphql, gql в коде) и генерирует TypeScript-типы и типизированные операции.

# codegen.ts
import type { CodegenConfig } from "@graphql-codegen/cli";
const config: CodegenConfig = {
  schema: "http://localhost:5000/graphql",
  documents: ["src/**/*.graphql", "src/**/*.vue"],
  generates: {
    "src/gql/": { preset: "client", presetConfig: { fragmentMasking: false } },
    // либо: "src/generated.ts": { plugins: ["typescript", "typescript-operations", "typed-document-node"] },
  },
  config: { scalars: { DateTime: "string", Decimal: "string" } },
};
export default config;
# src/orders/orders.graphql
query Orders($first: Int!, $after: String) { orders(first: $first, after: $after) { edges { node { id number status } } pageInfo { hasNextPage endCursor } } }
import { graphql } from "@/gql";                                  // preset client: типизированная функция gql
const OrdersQuery = graphql(`query Orders($first: Int!) { orders(first: $first) { edges { node { id number } } } }`);
 
const client = new GraphQLClient("/graphql");
const data = await client.request(OrdersQuery, { first: 20 });    // data и variables типизированы
const { data: q } = useQuery({ queryKey: ["orders"], queryFn: () => client.request(OrdersQuery, { first: 20 }) });

graphql-request — минимальный клиент (fetch), не имеет кэша (кэшем занимается Vue Query). Поддерживает заголовки, middleware, rawRequest, batchRequests, загрузку файлов.

Практика:

  • Скрипт codegen (graphql-codegen --watch в dev), генерация в CI; артефакты не коммитить или коммитить осознанно.
  • Скалярные типы (DateTime, Decimal, Upload) мапить явно.
  • Фрагменты рядом с компонентами; типы FragmentType для маскирования данных.
  • Проверка запросов относительно схемы (graphql-eslint).
  • Валидация ответов не нужна для типов, но контракт должен проверяться (сравнение схем в CI).

Нюансы и подводные камни

  • Схема на сервере меняется: генерация должна быть частью пайплайна.
  • Сгенерированные типы описывают запрошенные поля; лишние поля недоступны.
  • any в скалярах при отсутствии маппинга.
  • Скачивание схемы с продовой среды в CI — используйте зафиксированный файл схемы.

Практика

  1. Настройте codegen и типизированные операции для 2–3 запросов.
  2. Подключите graphql-request к Vue Query.
  3. Добавьте проверку схемы и запросов в CI.

Вопросы с ответами

Связанные темы

Вид графа

Обратные ссылки