GraphQL

01Схемы, типы и резолверы

Представьте REST API как комплексный обед: каждый эндпоинт возвращает фиксированную тарелку. GraphQL — шведский стол с точным бланком заказа: клиент перечисляет блюда и порции, которые хочет. Сервер описывает всё доступное в схеме, написанной на Schema Definition Language (SDL). У объектных типов (Product, Order) есть поля с типами; скаляры — базовые типы (String, Int, Boolean, ID); восклицательный знак означает non-null; списки обозначаются квадратными скобками. Специальные корневые типы задают точки входа: Query — для чтения, Mutation — для записи, Subscription — для обновлений в реальном времени. За каждым полем стоит резолвер — функция, возвращающая его значение. Сервер разбирает запрос, проверяет его по схеме, затем вызывает резолверы поле за полем, собирая ответ, который повторяет форму запроса. Неизвестные поля отклоняются ещё до выполнения какого-либо кода.

1type Product {
2  id: ID!
3  name: String!
4  price: Int!
5  category: Category!
6}
7 
8type Category {
9  id: ID!
10  name: String!
11}
12 
13type Query {
14  products(first: Int = 20, after: String): [Product!]!
15  product(id: ID!): Product
16}
17 
18type Mutation {
19  renameProduct(id: ID!, name: String!): Product!
20}

02Query, mutation и subscription

Query запрашивает данные; клиент выбирает поля и может в одном запросе пройти по связям, например получить товары с названиями их категорий. Переменные делают запросы статичными и переиспользуемыми, а заодно позволяют использовать persisted queries. Фрагменты переиспользуют наборы полей между компонентами, и многие клиентские библиотеки размещают их рядом с UI-компонентами. Mutation изменяет данные и возвращает обновлённый объект, так что клиентский кэш может обновиться без дополнительного запроса; мутации в одном запросе выполняются последовательно. Проектируйте мутации вокруг бизнес-действий (placeOrder, cancelSubscription), а не общих обновлений таблиц, и возвращайте структурированные ошибки для ожидаемых сбоев, например валидации, внутри payload'а. Subscription'ы пушат обновления клиенту, обычно через WebSocket или server-sent events, — для вещей вроде статуса заказа или чата. Они добавляют stateful-соединения, которые нужно масштабировать и защищать, поэтому используйте их там, где живые обновления действительно важны.

03Проблема N+1 и DataLoader

Поскольку у каждого поля свой резолвер, наивный сервер выполняет один запрос за списком из 50 товаров, а затем по запросу на каждый товар за его категорией: 51 запрос на один запрос клиента. Это и есть проблема N+1, а вложенные запросы делают её хуже. Стандартное решение — батчинг с помощью DataLoader. Вместо немедленной выборки каждый резолвер запрашивает ключ у loader'а; loader собирает все ключи, запрошенные в одном такте event loop, достаёт их одним запросом (WHERE id IN ...) и возвращает результаты в правильном порядке. Он также кэширует в пределах запроса, так что одна и та же категория загружается один раз. Создавайте loader'ы на каждый запрос, никогда — глобально, чтобы кэшированные данные не могли утечь между пользователями. Мониторьте время резолверов и число запросов к базе на операцию, чтобы ловить регрессии.

1import DataLoader from "dataloader";
2 
3// One set of loaders per request, so caching never leaks between users
4export function createLoaders(db: Db) {
5  return {
6    categoryById: new DataLoader<string, Category | null>(async (ids) => {
7      const rows = await db.category.findMany({ where: { id: { in: [...ids] } } });
8      const byId = new Map(rows.map((c) => [c.id, c]));
9      return ids.map((id) => byId.get(id) ?? null);
10    }),
11  };
12}
13 
14export const resolvers = {
15  Product: {
16    category: (p: Product, _args: unknown, ctx: Ctx) =>
17      ctx.loaders.categoryById.load(p.categoryId),
18  },
19};

04Кэширование и безопасность

REST выигрывает от HTTP-кэширования: каждый URL — ресурс, который могут кэшировать браузеры, CDN и прокси. GraphQL обычно отправляет POST-запросы на один эндпоинт, так что этот слой исчезает. Ответы на это: нормализованные клиентские кэши (Apollo Client, urql, Relay), которые хранят объекты по типу и ID; persisted queries, отправляемые как GET с хэшем, что снова делает возможным кэширование в CDN; и серверное кэширование результатов резолверов с аккуратным разграничением по пользователям. Безопасность требует не меньшего внимания. Клиент может написать глубоко вложенный или огромный запрос, который обойдётся серверу в целое состояние, поэтому ограничивайте максимальную глубину, сложность или стоимость запроса, размер страниц и время выполнения. Ограничивайте частоту по стоимости, а не только по числу запросов. В продакшене подумайте об отключении introspection для приватных API или, что лучше, разрешите только persisted queries от ваших собственных клиентов. Авторизуйте в резолверах или бизнес-слое, при необходимости на уровне полей, — и никогда только на эндпоинте.

• Лимиты глубины и сложности плюс обязательная пагинация списков.
• Persisted queries: меньше запросы, кэширование в CDN, безопасный allow-list.
• Авторизация на уровне полей и DataLoader'ы на каждый запрос.

05GraphQL, REST или tRPC

Выбирайте по набору клиентов и устройству команды. GraphQL выигрывает, когда множество клиентов с разными потребностями работают с богатой связанной предметной областью, когда платформенная команда обслуживает несколько продуктовых или когда вы объединяете несколько бэкендов в один граф (federation). REST выигрывает для публичных API, простых моделей ресурсов, загрузки и скачивания файлов, вебхуков и всего, что выигрывает от HTTP-кэширования и привычных инструментов; с OpenAPI вы всё равно получаете типизированные клиенты. tRPC выигрывает в TypeScript-монорепозиториях, где одна команда владеет и сервером, и клиентом: процедуры вызываются как функции со сквозными типами и почти без накладных расходов на схему, но это только TypeScript, и он не задуман как публичный, независимый от языка API. Многие системы их смешивают: REST или tRPC для внутренних приложений, публичный REST API для партнёров и GraphQL только там, где его гибкость окупает его сложность.

06Внутренности выполнения: nullability и частичные результаты

Ответ GraphQL может содержать одновременно data и errors. Когда резолвер выбрасывает ошибку, она добавляется в массив errors с path до упавшего поля, а само поле становится null. Если поле объявлено non-null, null недопустим, поэтому null «всплывает» до ближайшего nullable-родителя и может стереть целый список или весь объект data. Поэтому nullability — это решение дизайна, а не украшение. Помечайте поля non-null, когда они действительно всегда есть и дёшевы (id, name), и оставляйте nullable поля, зависящие от другого сервиса или проверки прав, чтобы один сбой портил одно поле, а не всю страницу. Клиенты должны уметь работать с частичными данными. Порядок выполнения резолверов тоже важен: соседние поля query могут резолвиться параллельно, а поля верхнего уровня mutation выполняются последовательно.

• Ошибки содержат path; упавшее поле становится null.
• Non-null поля передают null вверх до ближайшего nullable-родителя.
• Делайте nullable поля, которые обращаются к ненадёжным зависимостям.

07Анализ стоимости и пагинация в масштабе

Одних ограничений глубины мало: неглубокий запрос на 100 товаров, у каждого по 100 отзывов, у каждого по 100 авторов, может запросить миллион объектов. Статический cost analysis назначает стоимость каждому полю, умножает списочные поля на запрошенный размер страницы и отклоняет запросы, превышающие бюджет, ещё до выполнения. Публикуйте стоимость в extension ответа, чтобы клиенты её видели, и ограничивайте скорость по стоимости в минуту. Сделайте пагинацию обязательной с максимальным размером страницы. Паттерн connections на курсорах (edges, node, pageInfo с endCursor и hasNextPage) — стандарт де-факто: курсоры непрозрачны, устойчивы к вставкам и позволяют избежать глубоких OFFSET-сканов, замедляющих базы. Кодируйте в курсоре ключ сортировки и ID, а под капотом используйте keyset-запрос (WHERE (created_at, id) < (...) ORDER BY created_at DESC, id DESC).

1type ProductConnection {
2  edges: [ProductEdge!]!
3  pageInfo: PageInfo!
4}
5 
6type ProductEdge {
7  cursor: String!
8  node: Product!
9}
10 
11type PageInfo {
12  hasNextPage: Boolean!
13  endCursor: String
14}
15 
16type Query {
17  products(first: Int! = 20, after: String): ProductConnection!
18}

08Federation: один граф из многих сервисов

Federation позволяет нескольким командам владеть каждая своим subgraph, а клиенты видят один supergraph. Subgraph объявляет сущности с ключом, например Product, идентифицируемый по id. Другой subgraph может расширить эту сущность своими полями, например reviews, и предоставляет reference resolver, который загружает дополнительные данные товара, имея только его ключ. Router собирает схемы subgraph, планирует каждый входящий запрос, вызывает subgraph в правильном порядке, часто параллельно, и склеивает результаты. Это сохраняет автономию команд и даёт клиентам единый API. Цена: проверки composition в CI становятся критичными, потому что один subgraph может сломать supergraph; планы запросов могут разворачиваться во множество внутренних вызовов, поэтому entity resolver обязаны батчить; а отладка требует трейсинга через router. Это подходит организациям с несколькими бэкенд-командами; для одной команды это лишние накладные расходы.

09Ошибки как данные, дизайн input и новые возможности спецификации

Используйте массив errors для неожиданных сбоев, а ожидаемые бизнес-исходы моделируйте в схеме. Mutation может возвращать union, например PlaceOrderResult = OrderPlaced | OutOfStock | PaymentDeclined, а клиенты обрабатывают каждый случай через fragment, получая типизированные поля для каждого исхода. Проектируйте input под каждое действие: placeOrder(input: PlaceOrderInput!) оставляет аргументы расширяемыми. Редакция спецификации GraphQL от сентября 2025 года, первая с 2021-го, добавила OneOf input-объекты, где должно быть передано ровно одно поле, — это аккуратно моделирует «найти товар по id или по sku». Incremental delivery с @defer и @stream, позволяющая медленным частям ответа приходить позже, поддерживается рядом серверов и клиентов, но всё ещё проходит процесс спецификации, поэтому проверьте поддержку в своём стеке, прежде чем на неё полагаться.

1union PlaceOrderResult = OrderPlaced | OutOfStock | PaymentDeclined
2 
3type OrderPlaced { order: Order! }
4type OutOfStock { productIds: [ID!]! }
5type PaymentDeclined { reason: String! }
6 
7input ProductLookup @oneOf {
8  id: ID
9  sku: String
10}
11 
12type Mutation {
13  placeOrder(input: PlaceOrderInput!): PlaceOrderResult!
14}
15 
16type Query {
17  product(by: ProductLookup!): Product
18}