Skip to content

GraphQL Шпаргалка

Язык запросов и среда выполнения для API.

01

Начало работы

Базовый запрос

GraphQL позволяет клиенту указать, какие именно данные нужны. Запрос получает данные, а ответ повторяет форму запроса. Это избавляет от избыточной и недостаточной выборки, типичной для REST API.

graphql
# Query - read data
query {
  user(id: 1) {
    id
    name
    email
    posts {
      title
      content
    }
  }
}

# Response
{
  "data": {
    "user": {
      "id": 1,
      "name": "Alice",
      "email": "[email protected]",
      "posts": [
        { "title": "Hello", "content": "World" }
      ]
    }
  }
}

Запрос с переменными

Переменные параметризуют запросы, чтобы одну операцию можно было переиспользовать с разными входными данными. Они объявляются в заголовке операции как $name: Type. Строка запроса остаётся неизменной, меняется только JSON переменных при каждом вызове.

graphql
# Declare variables with operation name
query GetUser($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

# Variables sent alongside the query
{
  "id": "1",
  "withPosts": true
}

Основы мутаций

Мутации изменяют данные и возвращают набор полей так же, как запросы. По соглашению после них читают изменённые данные. GraphQL выполняет мутации последовательно (одну за другой), а поля запроса — параллельно.

graphql
# Mutation - write data, then return the result
mutation {
  createUser(input: { name: "Bob", email: "[email protected]" }) {
    id
    name
  }
}

# Response
{
  "data": {
    "createUser": {
      "id": "42",
      "name": "Bob"
    }
  }
}

Поля и наборы полей

Набор полей — это список полей в фигурных скобках. Скаляры и enum возвращают листовые значения; объектные типы требуют вложенного набора полей. Забыть подвыборку для объектного типа — частая ошибка валидации.

graphql
# You must select fields - GraphQL never returns whole objects
query {
  user(id: 1) {
    # this block is a "selection set"
    name
    email
  }
}

# Selecting a scalar returns its value directly
# Selecting an object REQUIRES a sub-selection set
query {
  user(id: 1) {
    name          # scalar - OK
    posts {       # object - needs { ... }
      title
    }
  }
}

GraphQL против REST

REST предоставляет много endpoint с фиксированной формой; GraphQL — один endpoint, форму задаёт клиент. Это сокращает число обращений и исключает избыточную и недостаточную выборку. Цена — более сложный сервер и кеширование через POST.

graphql
# REST: multiple round trips, fixed shapes
GET /users/1            -> { id, name, email, address, ... }
GET /users/1/posts      -> [ { id, title, body, author, ... } ]

# GraphQL: one request, client-defined shape
query {
  user(id: 1) {
    name
    posts { title }
  }
}

# One endpoint, one POST request
POST /graphql
{ "query": "...", "variables": { ... } }

Интроспекция

Интроспекция позволяет клиентам изучать схему во время выполнения. На ней основаны GraphiQL, Apollo Studio и генераторы кода. Корневые поля __schema и __type — точки входа. В production интроспекцию иногда отключают, чтобы скрыть внутреннее устройство.

graphql
# Ask the schema what types and fields it has
{
  __schema {
    types {
      name
      kind
    }
  }
}

# Inspect a specific type's fields
{
  __type(name: "User") {
    name
    fields {
      name
      type { name kind ofType { name kind } }
    }
  }
}
02

Схема и система типов

Объявление схемы

Блок schema связывает корневые типы операций. Если корневые типы называются Query, Mutation и Subscription, Apollo/GraphQL.js выводит схему автоматически, и это объявление можно опустить.

graphql
# SDL - Schema Definition Language
schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

# In most servers the schema is inferred from the
# Query/Mutation/Subscription types, so this block is optional.

Корневые типы

Query, Mutation и Subscription — точки входа схемы. Query — единственный обязательный корневой тип. Каждое корневое поле становится операцией, которую может выполнить клиент. Принято называть мутации глаголами (createUser), а запросы — существительными.

graphql
type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

type Subscription {
  postAdded: Post!
}

Определения типов

Типы объявляются ключевым словом type и списком полей. У каждого поля есть имя и тип возврата. Суффикс ! означает non-null; [Type!] — список элементов non-null; [Type!]! — non-null список элементов non-null.

graphql
# Object type - the most common building block
type User {
  id: ID!
  name: String!
  age: Int
  email: String
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  author: User!
}

Добавление описаний

Строки в тройных кавычках (или однострочные строки перед определением) попадают в схему как описания. Они видны в документации GraphiQL и в интроспекции. Обычные комментарии # существуют только для разработки и вырезаются, поэтому для пользовательской документации используйте тройные кавычки.

graphql
"""A registered user of the platform."""
type User {
  """The unique, immutable identifier."""
  id: ID!

  "Display name shown publicly."
  name: String!

  # plain # comments are NOT exposed to clients
  email: String
}

Схема с расширениями

extend type добавляет поля к типу, объявленному в другом месте. Так большой схему делят по файлам или добавляют поля конкретного модуля. Тип можно объявить один раз и расширять многократно, но каждое поле определяется только один раз.

graphql
# Extend an existing type without redefining it
type User {
  id: ID!
  name: String!
}

extend type User {
  age: Int
  posts: [Post!]!
}

# Useful for splitting a schema across files,
# or for adding fields only in certain modules.

Schema-first против code-first

Schema-first предполагает ручное написание SDL и привязку резолверов (классический подход Apollo). Code-first строит схему программно через TypeScript-декораторы и билдеры (Nexus, TypeGraphQL, Pothos), получая типобезопасность между схемой и резолверами. Оба дают одинаковую runtime-схему.

graphql
# 1) Schema-first: write SDL, bind resolvers
const typeDefs = `
  type Query { hello: String }
`;
const resolvers = { Query: { hello: () => "world" } };
const server = new ApolloServer({ typeDefs, resolvers });

# 2) Code-first: build with builders (Nexus, TypeGraphQL)
export const Query = queryType({
  definition(t) {
    t.string("hello", { resolve: () => "world" });
  },
});
03

Скалярные типы

Встроенные скаляры

GraphQL включает пять встроенных скаляров: Int, Float, String, Boolean и ID. ID сериализуется как строка, но семантически означает идентификатор — клиенты должны считать его непрозрачным. Встроенных Date или DateTime нет; их определяют самостоятельно.

graphql
type Example {
  id: ID!          # unique identifier, serialized as string
  name: String!    # UTF-8 text
  age: Int         # 32-bit integer
  score: Float     # double-precision float
  active: Boolean! # true / false
}

Свои скаляры

Свои скаляры позволяют представить примитивы предметной области. После объявления нужно предоставить резолвер, который сериализует (в JSON), разбирает (из переменных) и при желании разбирает литералы (из AST). Иначе значение передаётся как есть.

graphql
# Declare a custom scalar in SDL
scalar DateTime
scalar URL
scalar JSON

type Event {
  id: ID!
  at: DateTime!
  link: URL
  metadata: JSON
}

Резолверы скаляров

У резолвера скаляра три необязательных метода. serialize преобразует внутреннее значение в JSON для вывода. parseValue преобразует входную переменную во внутреннюю форму. parseLiteral преобразует встроенный литерал из AST запроса во внутреннюю форму. Определите все три для полностью типизированного скаляра.

graphql
const resolvers = {
  DateTime: {
    // value -> JSON sent to client
    serialize: (value: Date) => value.toISOString(),
    // variable value -> internal value
    parseValue: (value: string) => new Date(value),
    // inline AST literal -> internal value
    parseLiteral: (ast) => {
      if (ast.kind === "StringValue") {
        return new Date(ast.value);
      }
      return null;
    },
  },
};

Скаляр Date/DateTime

Пакет graphql-scalars содержит проверенные временем скаляры: DateTime, Date, Time, EmailAddress, URL, UUID, BigInt, JSON и другие. Предпочитайте его ручной реализации, особенно для разбора дат ISO 8601, где полно крайних случаев.

graphql
# Use graphql-scalars for well-tested common types
import { DateTimeResolver } from "graphql-scalars";

const resolvers = {
  DateTime: DateTimeResolver,
  Date: DateResolver,
  Time: TimeResolver,
};

# In SDL
scalar DateTime

type Query {
  now: DateTime!
}

Скаляр JSON

Скаляры JSON пропускают произвольные данные — полезно для динамической конфигурации или метаданных. Цена: теряется типобезопасность и проверка на уровне полей, а клиенты не могут выбирать подполя. Используйте редко: типизированный объектный тип почти всегда лучше.

graphql
scalar JSON

type Query {
  # accept arbitrary JSON as input or output
  config: JSON
  setConfig(value: JSON): JSON
}

# The simplest pass-through resolver
const resolvers = {
  JSON: {
    serialize: (v) => v,
    parseValue: (v) => v,
    parseLiteral: (ast) => parseJsonLiteral(ast),
  },
};
04

Объектные типы

Определение объектных типов

Объектный тип — набор именованных полей с типами возврата. Объектные типы образуют граф: они ссылаются друг на друга, выстраивая связи (у User есть Posts, у Post есть Author). Объектные типы — выходные; для входных данных используйте input-типы.

graphql
type User {
  id: ID!
  name: String!
  email: String
  createdAt: String!
}

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
}

Поля и их типы

Каждое поле объявляет тип возврата. Nullable — по умолчанию; ! делает его non-null. Списки оборачиваются в []. Позиция ! важна: [String] может быть null и содержать null; [String!] может быть null, но элементы — нет; [String!]! не может быть null и не содержит null.

graphql
type Product {
  id: ID!                # non-null ID
  name: String!          # non-null string
  price: Float!          # non-null float
  discount: Float        # nullable float
  tags: [String!]!       # non-null list of non-null strings
  reviews: [Review]      # nullable list of nullable reviews
}

Non-null и списки

Размещение ! управляет допустимостью null на каждом уровне. Non-null мощно, но рискованно: если резолвер вернёт null для non-null поля, ошибка поднимется вверх и обнулит родительское поле. По умолчанию делайте поля nullable и включайте non-null там, где значение действительно гарантировано.

graphql
type Example {
  a: [String]       # may be null; items may be null
  b: [String!]      # may be null; items NOT null
  c: [String]!      # NOT null; items may be null
  d: [String!]!     # NOT null; items NOT null

  name: String      # may be null
  name2: String!    # NOT null - errors if null returned
}

Вложенные объекты

Объектные типы ссылаются друг на друга, образуя граф, что позволяет запросам проходить по связям (пользователь -> посты -> автор -> профиль). Циклические ссылки между типами допустимы и обычны. Именно граф делает GraphQL графом, а не деревом endpoint.

graphql
type User {
  id: ID!
  name: String!
  profile: Profile!
  posts: [Post!]!
}

type Profile {
  bio: String
  avatar: String
}

type Post {
  id: ID!
  title: String!
  author: User!   # back-reference creates the graph
}

Аргументы полей объектов

Любое поле, не только корневое, может принимать аргументы. Это позволяет одному типу давать отфильтрованные и постраничные представления связанных данных (например, user.posts(limit: 10)). Аргументы со значениями по умолчанию становятся необязательными в запросах.

graphql
type User {
  id: ID!
  name: String!
  # an object field can take arguments
  posts(limit: Int = 5, after: ID): [Post!]!
  role(type: RoleType!): Role
}

type Query {
  user(id: ID!): User
}
05

Запросы

Тип Query

Тип Query — точка входа для всех чтений. Каждое его поле — операция верхнего уровня, которую может запросить клиент. Держите его сосредоточенным на чтении; записи помещайте в Mutation. Принято называть поля существительными (users, user, search).

graphql
type Query {
  me: User!
  user(id: ID!): User
  users(limit: Int = 20, offset: Int = 0): [User!]!
  search(term: String!): [SearchResult!]!
}

# Clients run these as operations:
# query { me { name } }
# query { user(id: "1") { name } }

Несколько полей

Запрос может выбирать несколько корневых полей за один раз. GraphQL выполняет их параллельно (кроме мутаций). Так связанные выборки объединяются в один сетевой вызов — ключевой выигрыш по сравнению с REST.

graphql
# Several fields in one request - executed in parallel
query {
  me { name email }
  user(id: "1") { name }
  users(limit: 3) { id name }
}

# Response contains all three under "data"
{
  "data": {
    "me": { "name": "Alice", "email": "[email protected]" },
    "user": { "name": "Bob" },
    "users": [ { "id": "1", "name": "Bob" }, ... ]
  }
}

Псевдонимы

Псевдонимы переименовывают поля в ответе. Они обязательны при выборе одного и того же поля с разными аргументами: ключи JSON-объекта должны быть уникальны. Псевдонимы также удобны для более коротких и осмысленных ключей ответа.

graphql
# Same field twice with different args needs aliases
query {
  alice: user(id: "1") { name }
  bob:   user(id: "2") { name }
}

# Response keys match the aliases
{
  "data": {
    "alice": { "name": "Alice" },
    "bob":   { "name": "Bob" }
  }
}

Вложенные запросы

Обход связей — суперсила GraphQL. Клиент проходит граф (пользователь -> посты -> комментарии -> автор) одним запросом. Сервер вычисляет каждое поле своим резолвером; глубокая вложенность допустима, но следите за N+1 запросами на бэкенде.

graphql
query {
  user(id: "1") {
    name
    posts {            # traverse relationship
      title
      comments {        # and another level
        author {
          name
        }
      }
    }
  }
}

Запрос с аргументами

Аргументы могут быть встроенными литералами или переменными. Литералы удобны для статических значений; используйте переменные, когда значение приходит от пользователя или меняется при каждом вызове. Переменные сохраняют кешируемость запроса и избавляют от склейки строк.

graphql
# Schema
type Query {
  user(id: ID!, includeEmail: Boolean = false): User
}

# Inline arguments
query {
  user(id: "1", includeEmail: true) {
    name
    email
  }
}

# Prefer variables for dynamic values
query($uid: ID!, $withEmail: Boolean!) {
  user(id: $uid, includeEmail: $withEmail) {
    name
    email
  }
}

Имя операции

Именовать операции (query GetUserProfile) необязательно, но настоятельно рекомендуется. Именованные операции проще отлаживать, они попадают в логи и Apollo Studio, а также обязательны при отправке нескольких операций в одном документе и для persisted queries.

graphql
# Give operations a name - required in production
query GetUserProfile($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
  }
}
06

Мутации

Тип Mutation

Тип Mutation — точка входа для записи. По соглашению поля мутаций называют глаголами (createUser, updatePost). Мутации выполняются последовательно в порядке объявления, поэтому зависимые по порядку побочные эффекты безопасны в одном запросе.

graphql
type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
  createPost(input: CreatePostInput!): Post!
}

# Client mutation
mutation {
  createUser(input: { name: "Alice", email: "[email protected]" }) {
    id
    name
  }
}

Мутация с input

Используйте input-типы для аргументов мутаций. Они группируют связанные поля, делают сигнатуру чистой и безопасно развиваются (можно добавлять необязательные поля, не ломая клиентов). Всегда передавайте данные мутации через переменные, а не встроенные литералы.

graphql
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

mutation($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
  }
}

# { "input": { "name": "Bob", "email": "[email protected]" } }

Возврат payload

Частый паттерн — объект payload, оборачивающий результат вместе с ошибками, флагом успеха или client mutation ID. Это гибче, чем бросать исключение: можно вернуть частичный успех и структурированные ошибки валидации рядом с сущностью.

graphql
# Return the changed entity AND related fields like errors
type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

type UserError {
  field: String
  message: String!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

Несколько мутаций

В отличие от запросов (параллельных), мутации в одной операции выполняются последовательно в объявленном порядке. Это гарантирует, что вторая мутация увидит результат первой. Если одно поле падает, следующие всё равно выполняются — проверяйте входные данные и используйте транзакции где нужно.

graphql
# Multiple mutations run SERIALLY in declared order
mutation {
  createPost(input: { title: "A" }) {
    id
  }
  publishPost(id: "1") {
    publishedAt
  }
}

Идемпотентность

Сетевые повторы могут дублировать записи. Ключ идемпотентности позволяет серверу распознать повтор и вернуть исходный результат вместо создания дубликата. Это необходимо для платежей, заказов и любых необратимых действий.

graphql
# Use a client mutation id or idempotency key
input CreateOrderInput {
  idempotencyKey: String!
  productId: ID!
  quantity: Int!
}

type Mutation {
  createOrder(input: CreateOrderInput!): Order!
}

# Clients retry with the SAME idempotencyKey on failure
# Server returns the original order instead of creating a duplicate
07

Подписки

Тип Subscription

Подписки передают данные от сервера клиенту при наступлении событий, обычно через WebSocket. Это долгоживущие операции. Держите payload маленьким: клиенты обычно запрашивают подробные данные отдельным запросом, а не получают поток больших объектов.

graphql
type Subscription {
  postAdded: Post!
  userJoined(roomId: ID!): User!
  messageReceived(userId: ID!): Message!
}

# Client subscribes (usually over WebSocket)
subscription {
  postAdded {
    id
    title
    author { name }
  }
}

Подписка на события

Резолвер подписки предоставляет функцию subscribe, возвращающую AsyncIterator. Мутации (или любой серверный код) публикуют события в тот же топик через pubsub. Необязательная функция resolve преобразует опубликованный payload в форму поля.

graphql
# Server-side resolver with asyncIterator
const resolvers = {
  Subscription: {
    postAdded: {
      subscribe: () => pubsub.asyncIterator(["POST_ADDED"]),
      resolve: (payload) => payload.postAdded,
    },
  },
};

# Trigger from a mutation
const resolvers = {
  Mutation: {
    createPost: async (_, args, { pubsub }) => {
      const post = await createPost(args);
      await pubsub.publish("POST_ADDED", { postAdded: post });
      return post;
    },
  },
};

PubSub

PubSub из graphql-subscriptions работает в пределах одного экземпляра сервера. Для нескольких экземпляров за балансировщиком нужен общий брокер — redis-pubsub, MQTT или pubsub на базе Kafka, — чтобы события доходили до клиентов на любом экземпляре.

graphql
import { PubSub } from "graphql-subscriptions";

const pubsub = new PubSub();

// publish an event
pubsub.publish("POST_ADDED", { postAdded: post });

// consume in a subscription resolver
subscribe: () => pubsub.asyncIterator(["POST_ADDED"])

# For multi-instance production, swap PubSub for
# Redis, NATS, or Kafka-based implementations.

Подписка с фильтрами

withFilter позволяет каждому подключённому клиенту получать только релевантные события, например адресованные ему сообщения. Функция фильтра получает опубликованный payload и переменные подписки. Фильтры должны быть дешёвыми: они выполняются для каждого события у каждого клиента.

graphql
const resolvers = {
  Subscription: {
    messageReceived: {
      subscribe: withFilter(
        () => pubsub.asyncIterator(["MESSAGE_RECEIVED"]),
        (payload, variables) =>
          payload.messageReceived.recipientId === variables.userId
      ),
      resolve: (payload) => payload.messageReceived,
    },
  },
};

# Only events where the filter returns true reach this client

Транспорт WebSocket

Подписки используют протокол graphql-ws (или устаревший subscriptions-transport-ws) поверх WebSocket. Рекомендуется более новый graphql-ws. connectionParams передают токены аутентификации. Сервер должен установить WS-обработчик рядом с HTTP-endpoint.

graphql
# Client uses graphql-ws over WebSocket
import { createClient } from "graphql-ws";

const wsClient = createClient({
  url: "ws://localhost:4000/graphql",
  connectionParams: { authToken: "..." },
});

wsClient.subscribe(
  { query: "subscription { postAdded { id title } }" },
  {
    next: (data) => console.log(data),
    error: (err) => console.error(err),
    complete: () => console.log("done"),
  }
);
08

Аргументы

Аргументы полей

Аргументы всегда именованные, никогда позиционные. Они могут быть у любого поля, не только корневого. Именованные аргументы делают запросы самодокументируемыми и независимыми от порядка. Для динамических значений используйте переменные, а не литералы.

graphql
type Query {
  user(id: ID!): User
  posts(limit: Int, offset: Int): [Post!]!
}

# Arguments can be inline literals
query {
  user(id: "1") { name }
  posts(limit: 10, offset: 0) { title }
}

Значения по умолчанию

Аргументы со значениями по умолчанию становятся необязательными — клиент может их опустить. Значения по умолчанию вычисляются на каждый запрос. У non-null аргументов значения по умолчанию нет: клиент обязан передать значение.

graphql
type Query {
  # default values make arguments optional
  posts(limit: Int = 10, sort: String = "newest"): [Post!]!
  user(id: ID!, includeDeleted: Boolean = false): User
}

# These are equivalent:
query { posts { title } }
query { posts(limit: 10, sort: "newest") { title } }

Типы аргументов

Аргументы могут быть скалярами, enum, списками или input-объектами, но никогда обычными объектными типами (они только выходные). Input-объекты — идиоматичный способ передать сложные структурированные аргументы, особенно для фильтров и пагинации.

graphql
type Query {
  # scalar arguments
  byId(id: ID!): User
  byAge(min: Int!, max: Int!): [User!]!

  # enum argument
  byStatus(status: UserStatus!): [User!]!

  # input object argument
  search(filter: UserFilter!): [User!]!

  # list argument
  byIds(ids: [ID!]!): [User!]!
}

Обязательные и необязательные

Суффикс ! делает аргумент обязательным. Пропуск обязательного аргумента ломает валидацию до вызова резолвера, возвращая понятную ошибку. Обязательными делайте действительно необходимые входные данные, а настраиваемое поведение — необязательным со значением по умолчанию.

graphql
type Query {
  # required (non-null) - client MUST provide
  user(id: ID!): User

  # optional (nullable) - client may omit
  posts(limit: Int): [Post!]!

  # optional with default
  recentPosts(limit: Int = 5): [Post!]!
}

# Omitting a required argument is a validation error
# before any resolver runs.

Аргументы-списки

Списковые аргументы записываются в квадратных скобках. [ID!]! означает non-null список non-null ID: клиент обязан передать список, и каждый элемент не может быть null. Передавайте списки через переменные, а не литералами, — так чище и нет проблем с экранированием.

graphql
type Query {
  usersByIds(ids: [ID!]!): [User!]!
  tags(allOf: [String!]): [Post!]!
}

# Inline list literal
query {
  usersByIds(ids: ["1", "2", "3"]) { name }
}

# Via variable
query($ids: [ID!]!) {
  usersByIds(ids: $ids) { name }
}
# { "ids": ["1", "2", "3"] }
09

Переменные

Объявление переменной

Переменные параметризуют операции. Объявите их как $name: Type в заголовке операции, используйте $name в теле и передавайте значения отдельным полем JSON variables. Так статический запрос отделяется от динамических данных.

graphql
# Declare variables in the operation, then use them
query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
  }
}

# Variables are sent in a separate JSON object
{
  "id": "1"
}

Типы переменных

Типы переменных должны соответствовать типам аргументов в схеме. Переменные могут быть nullable, non-null, списками или input-объектами. Тип переменной обязан быть входным типом (скаляр, enum или input-объект), но никогда выходным объектным типом.

graphql
query Search(
  $term: String!
  $limit: Int = 10
  $filters: PostFilter
  $tags: [String!]
) {
  search(term: $term, limit: $limit, filters: $filters, tags: $tags) {
    title
  }
}

Значения по умолчанию

Значения по умолчанию переменных применяются, когда клиент их опускает. Они допустимы только для nullable-переменных: non-null переменная означает, что клиент ОБЯЗАН передать значение. Значения по умолчанию позволяют клиентам отправлять минимум переменных, сохраняя гибкость сервера.

graphql
query Posts($limit: Int = 10, $sort: String = "newest") {
  posts(limit: $limit, sort: $sort) { title }
}

# If the client omits "limit", it defaults to 10.
# Only nullable variables can have defaults - a non-null
# variable with a default is a contradiction.

Обязательные переменные

Non-null переменная (!) обязательна: её пропуск ломает валидацию до вызова резолвера. Это самый надёжный способ гарантировать наличие входного значения. Non-null переменные не могут иметь значений по умолчанию; если нужно значение по умолчанию, сделайте переменную nullable.

graphql
query User($id: ID!) {     # ! means required
  user(id: $id) { name }
}

# Missing required variable -> validation error
{ "id": "1" }      # OK
{ }                # ERROR: variable $id of type ID! is required

# A non-null variable cannot have a default value.

Переменные в директивах

Переменные могут управлять директивами вроде @include и @skip, позволяя клиентам динамически включать и выключать поля. Отлично для feature flags, A/B-тестов и условных секций — всё с одним кешируемым документом запроса.

graphql
query User($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

# { "id": "1", "withPosts": false }  -> posts omitted
# { "id": "1", "withPosts": true }   -> posts included
10

Фрагменты

Именованные фрагменты

Фрагменты — переиспользуемые наборы полей, привязанные к конкретному типу (fragment Name on Type). Вставляйте их через ...Name везде, где встречается этот тип. Они избавляют запросы от дублирования и позволяют клиентам делить выборки между операциями.

graphql
# Define a reusable fragment
fragment UserFields on User {
  id
  name
  email
}

# Spread it into queries
query {
  user(id: "1") {
    ...UserFields
  }
  users {
    ...UserFields
  }
}

Композиция фрагментов

Фрагменты могут включать другие фрагменты, образуя составные выборки. Так наборы полей становятся модульными (базовый и полный профиль), а UI-компоненты объявляют свои потребности в данных и собираются в один запрос.

graphql
fragment UserBasic on User {
  id
  name
}

fragment UserWithEmail on User {
  ...UserBasic
  email
}

fragment UserFull on User {
  ...UserWithEmail
  posts { title }
}

# Fragments can spread other fragments of the same type.

Переменные фрагментов

Переменные фрагментов в стиле Relay позволяют фрагменту принимать параметры (например, limit), которые вызывающий передаёт через @arguments. Это делает фрагменты по-настоящему переиспользуемыми с разными настройками. Apollo поддерживает это директивой @arguments из клиентских директив.

graphql
fragment UserPosts on User
  @argumentDefinitions(limit: { type: "Int", defaultValue: 5 }) {
  posts(limit: $limit) {
    title
  }
}

query {
  user(id: "1") {
    ...UserPosts @arguments(limit: 10)
  }
}

# @argumentDefinitions and @arguments come from
# Relay; Apollo uses a similar pattern via client directives.

Переиспользуемые фрагменты

Размещение фрагментов рядом с компонентами, которые их рендерят, — мощный паттерн: каждый компонент объявляет свои данные, а родитель собирает их в один запрос. Это масштабирует загрузку данных в больших приложениях (поддерживают и Relay, и Apollo).

graphql
// Colocate fragments with the UI component that uses them
const USER_CARD = graphql`
  fragment UserCard_user on User {
    id
    name
    avatarUrl
  }
`;

function UserCard({ user }) {
  return <div>{user.name}</div>;
}

// The parent query spreads all needed fragments
query {
  users {
    ...UserCard_user
  }
}

Ограничения фрагментов

Фрагмент, объявленный на Post, можно вставить только там, где ожидается Post; вставка на User — ошибка валидации. Используйте inline-фрагменты с условиями типа для условной вставки на union/interface. Также избегайте циклических включений фрагментов.

graphql
# A fragment must match the type where it's spread
fragment PostFields on Post { title body }

query {
  user(id: "1") {
    ...PostFields   # ERROR: user is not a Post
  }
}

# Fragments can only spread on the declared type
# (or via type conditions with inline fragments).
11

Inline-фрагменты

Основы inline-фрагментов

Inline-фрагмент — безымянный набор полей с префиксом ... on Type. Он применяет поля только когда runtime-объект соответствует условию типа. Так получают поля конкретного типа на interface и union.

graphql
# An inline fragment is a selection set with a type condition
query {
  user(id: "1") {
    id
    name
    # fields common to User
    ... on AdminUser {
      permissions
    }
  }
}

# No name - declared inline in the query.

Условия типа

Синтаксис ... on Type — условие типа. Несколько inline-фрагментов в одной выборке позволяют обработать каждый возможный тип union/interface отдельно. Общие для всех типов поля можно выбирать прямо вне фрагментов.

graphql
query Search($term: String!) {
  search(term: $term) {
    ... on User { name email }
    ... on Post { title author { name } }
    ... on Comment { body }
  }
}

Доступ к union

У union нет общих полей, кроме __typename, поэтому для чтения данных конкретного типа нужны inline-фрагменты. __typename доступен всегда и говорит клиенту, какой конкретный тип у каждого элемента, — это необходимо для рендеринга результатов union.

graphql
union SearchResult = User | Post | Comment

query {
  search(term: "graphql") {
    # shared __typename is always available
    __typename
    ... on User { name }
    ... on Post { title }
    ... on Comment { body }
  }
}

Доступ к interface

Interface объявляет общие поля. Эти общие поля можно выбирать прямо на интерфейсе; поля конкретных типов требуют inline-фрагментов. В отличие от union, interface гарантирует общий набор полей, который обязан предоставить каждый реализующий тип.

graphql
interface Node { id: ID! }
type User implements Node { id: ID! name: String! }
type Post implements Node { id: ID! title: String! }

query {
  node(id: "1") {
    id              # shared interface field - selectable directly
    ... on User { name }
    ... on Post { title }
  }
}

Именованный фрагмент с условием типа

Именованные фрагменты несут своё условие типа, поэтому их можно вставлять в результат union/interface, и каждый применится только к подходящему типу. Так переиспользование сочетается с условной выборкой: вставьте несколько именованных фрагментов, чтобы покрыть всех членов union.

graphql
# Named fragments can also carry a type condition
fragment UserFields on User { name email }
fragment PostFields on Post { title }

query {
  search(term: "a") {
    ...UserFields
    ...PostFields
  }
}

# Equivalent to inlining those fragments inline.
12

Директивы

Встроенные директивы

GraphQL включает две встроенные клиентские директивы: @skip(if: Boolean!) опускает поле при true, @include(if: Boolean!) включает его только при true. Они взаимоисключающие и применимы к полям, включениям фрагментов и inline-фрагментам.

graphql
# @skip - omit field if true
query($skip: Boolean!) {
  user(id: "1") {
    name
    email @skip(if: $skip)
  }
}

# @include - include field only if true
query($withPosts: Boolean!) {
  user(id: "1") {
    posts @include(if: $withPosts) { title }
  }
}

@skip и @include

@skip и @include позволяют одному запросу обслуживать несколько форм. Они принимают Boolean-переменную, поэтому один и тот же persisted query может выводить краткое или подробное представление в зависимости от переменных — не нужно держать две строки запроса.

graphql
query User($id: ID!, $detailed: Boolean!) {
  user(id: $id) {
    name
    email @skip(if: $detailed)      # hide when detailed
    profile @include(if: $detailed) {  # show when detailed
      bio
    }
  }
}

# { "id": "1", "detailed": false } -> name, email
# { "id": "1", "detailed": true }  -> name, profile { bio }

Свои директивы

Свои директивы начинаются с объявления directive, задающего аргументы и допустимые места. Семантика выполнения не встроена: её реализуют через transforms схемы (Apollo) или visitors директив (graphql-tools). Частые применения: @auth, @cached, @deprecated.

graphql
# Declare a directive in SDL
directive @auth(requires: Role = ADMIN) on FIELD_DEFINITION

type Query {
  adminData: String @auth(requires: ADMIN)
  userData: String @auth(requires: USER)
}

# A directive needs a location: FIELD_DEFINITION, FIELD,
# OBJECT, ENUM, etc. Logic is implemented in the server
# (e.g. via schema transforms or a directive visitor).

Места директив

Каждая директива объявляет, где допустима: на операциях, полях, фрагментах или определениях схемы (FIELD_DEFINITION, OBJECT и т. д.). Клиентские директивы (в запросах) и директивы схемы (в SDL) используют разные наборы мест. Проверяйте при сборке схемы.

graphql
# Where a directive can appear
directive @example on
  | QUERY          # operation
  | FIELD          # a field in a selection
  | FRAGMENT_DEFINITION
  | FRAGMENT_SPREAD
  | INLINE_FRAGMENT
  | FIELD_DEFINITION  # in SDL (server-side)
  | OBJECT | INTERFACE | UNION | ENUM
  | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION;

# Multiple locations use | between them.

Аргументы директив

Директивы могут принимать типизированные аргументы со значениями по умолчанию. Встроенная @deprecated(reason:) помечает поля и значения enum устаревшими; инструменты предупреждают клиентов, которые их используют. Свои директивы с аргументами управляют поведением: TTL кеша, требуемые роли и т. п.

graphql
directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE

type Query {
  oldField: String @deprecated(reason: "Use newField")
  newField: String
}

enum Status {
  ACTIVE
  INACTIVE @deprecated(reason: "Use ARCHIVED")
  ARCHIVED
}
13

Enum

Определение enum

Enum — конечный набор именованных значений. Enum — скалярные типы: это листовые значения без подвыборок. Используйте их для полей с фиксированным набором вариантов (status, role, kind) вместо магических строк, получая валидацию и самодокументирование.

graphql
enum Role {
  ADMIN
  USER
  GUEST
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type User {
  role: Role!
}

type Post {
  status: PostStatus!
}

Значения enum

В запросах значения enum пишутся без кавычек как идентификаторы (color: RED), но сериализуются как строки в JSON переменных и ответах. По соглашению имена в UPPER_SNAKE_CASE. Сервер проверяет любое значение на соответствие объявленному набору.

graphql
enum Color {
  RED
  GREEN
  BLUE
}

# In a query, enum values are unquoted identifiers
query {
  products(color: RED) { name }
}

# In variables JSON, they're sent as strings
{ "color": "RED" }

Enum в запросах

Enum работают и как типы полей, и как типы аргументов. В роли аргумента клиент передаёт одно из объявленных значений. Некорректные значения enum ломают валидацию до вызова резолвера, давая понятные ошибки.

graphql
type Query {
  posts(status: PostStatus!): [Post!]!
}

query {
  posts(status: PUBLISHED) { title }
}

query($status: PostStatus!) {
  posts(status: $status) { title }
}
# { "status": "DRAFT" }

Резолверы enum

По умолчанию значение enum отображается само в себя. Резолвер enum позволяет сопоставить публичное имя API (ADMIN) и внутреннее представление (строка "admin" или числовой код роли). Так схема отделяется от деталей хранения.

graphql
# Map internal values <-> API values
enum Role {
  ADMIN
  USER
}

const resolvers = {
  Role: {
    ADMIN: "admin",   // internal DB value
    USER: "user",
  },
};

# Internally the resolver sees "admin"; the client sees ADMIN.
# Useful when DB values differ from the public API.

Лучшие практики enum

Всегда предпочитайте enum свободным строкам для фиксированных наборов вариантов: они проверяют ввод, документируют API и улучшают инструменты. Чтобы убрать значение enum, не ломая клиентов, сначала пометьте его deprecated. Удаление значения, которое клиенты ещё отправляют, — ломающее изменение.

graphql
# Prefer enums over strings for fixed option sets
type User {
  role: Role!          # GOOD - validated, self-documenting
  roleStr: String      # AVOID - no validation, magic strings
}

# Deprecate values instead of removing them
enum Status {
  ACTIVE
  INACTIVE @deprecated(reason: "Use ARCHIVED")
  ARCHIVED
}
14

Интерфейсы

Определение интерфейсов

Interface — абстрактный тип, объявляющий набор полей, которые обязаны предоставить реализующие типы. Он задаёт контракт. Интерфейсы полезны для общих абстракций вроде Node (глобальные ID в стиле Relay) или Character для связанных типов.

graphql
interface Node {
  id: ID!
}

interface Character {
  name: String!
}

type User implements Node & Character {
  id: ID!
  name: String!
  email: String!
}

Реализация интерфейсов

Тип объявляет реализацию интерфейса ключевым словом implements. Он должен определить каждое поле интерфейса с совместимыми типами. Тип может реализовать несколько интерфейсов (через &). Схема проверяет это при сборке.

graphql
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!        # required by Node
  name: String!
}

type Post implements Node {
  id: ID!        # required by Node
  title: String!
}

# A type must implement every field of the interface.

Запросы к интерфейсам

Когда поле возвращает интерфейс, можно выбирать его общие поля напрямую. Для полей конкретного типа используйте inline-фрагменты (... on User). Runtime-тип каждого результата определяет, какие inline-фрагменты применятся.

graphql
interface Node { id: ID! }

type Query {
  node(id: ID!): Node
}

query {
  node(id: "1") {
    id              # interface field - always selectable
    ... on User { name }
    ... on Post { title }
  }
}

Резолверы интерфейсов

Интерфейсу нужна функция __resolveType, возвращающая имя конкретного типа (или объект типа) для runtime-значения. Так GraphQL понимает, какие inline-фрагменты применить. Без неё определить конкретный тип во время выполнения невозможно.

graphql
interface Character { name: String! }

type Human implements Character {
  name: String!
  starships: [String!]!
}

type Droid implements Character {
  name: String!
  primaryFunction: String
}

const resolvers = {
  Character: {
    // tell GraphQL which concrete type a value is
    __resolveType(obj) {
      return obj.primaryFunction ? "Droid" : "Human";
    },
  },
};

Несколько интерфейсов

Тип может реализовать несколько интерфейсов через разделитель &. Это композиция возможностей: например, Article одновременно Node, Timestamped и SoftDeletable. Запрос возвращает тип интерфейса, а клиенты используют inline-фрагменты для конкретных полей.

graphql
interface Node { id: ID! }
interface Timestamped { createdAt: String! }
interface SoftDeletable { deletedAt: String }

type Article implements Node & Timestamped & SoftDeletable {
  id: ID!
  createdAt: String!
  deletedAt: String
  title: String!
}

# Use & to list multiple implemented interfaces.
15

Union

Определение union

Union — абстрактный тип, который может быть одним из нескольких конкретных типов без требования общих полей (в отличие от interface). Объявляется как union Name = TypeA | TypeB. Union хорош, когда результаты разнородны, но концептуально связаны.

graphql
union SearchResult = User | Post | Comment

type User { id: ID! name: String! }
type Post { id: ID! title: String! }
type Comment { id: ID! body: String! }

type Query {
  search(term: String!): [SearchResult!]!
}

Union против interface

Interface используйте, когда у членов есть общий контракт (поля, которые есть у всех). Union — когда члены не связаны ничем, кроме идеи, и общих полей нет. Тип может входить во множество union; union не может напрямую реализовать другой union.

graphql
# INTERFACE - shared contract
interface Node { id: ID! }
type User implements Node { id: ID! name: String! }
type Post implements Node { id: ID! title: String! }
# All members share the "id" field.

# UNION - no shared contract
union SearchResult = User | Post
# Members share NO required fields.

Запросы к union

Union не предоставляет собственных полей, поэтому для чтения нужны inline-фрагменты. __typename доступен всегда и говорит клиенту, какой конкретный тип у элемента. Выбор поля прямо на union (без условия типа) — ошибка валидации.

graphql
query {
  search(term: "graphql") {
    __typename          # always available
    ... on User { name email }
    ... on Post { title }
    ... on Comment { body }
  }
}

# You CANNOT select fields directly on a union
# (no shared fields) - only via inline fragments.

Резолверы union

Как и интерфейсам, union нужен резолвер __resolveType, возвращающий имя конкретного типа для runtime-значения. Без него GraphQL не выберет inline-фрагменты. Возвращайте имя типа строкой или объект типа из схемы.

graphql
union SearchResult = User | Post | Comment

const resolvers = {
  SearchResult: {
    __resolveType(obj) {
      if (obj.email) return "User";
      if (obj.title) return "Post";
      if (obj.body) return "Comment";
      return null;
    },
  },
};

Частые паттерны

Union моделируют исход «успех или ошибка»: мутация возвращает union типа успеха и типа ошибки, заставляя клиента обработать оба. Это типобезопаснее одного payload с необязательными полями ошибки. (В SDL нужен union, а не псевдонимы типов.)

graphql
# Mutation result that may be success or error
type CreateUserSuccess { user: User! }
type CreateUserError { messages: [String!]! }
type CreateUserPayload = CreateUserSuccess | CreateUserError
# (note: a type alias like this isn't valid SDL; use union)
union CreateUserPayload = CreateUserSuccess | CreateUserError

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}
16

Input-типы

Input-объекты

Input-типы — объектные типы для аргументов, объявляемые через input. Они группируют связанные поля (пользователя, фильтр) в один аргумент. В отличие от выходных объектных типов, input-типы могут содержать только входные типы (скаляры, enum, другие input-типы).

graphql
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

mutation($input: CreateUserInput!) {
  createUser(input: $input) { id }
}
# { "input": { "name": "Alice", "email": "[email protected]" } }

Input против output

Выходные типы (type) могут иметь аргументы полей и резолверы; входные (input) — простые носители данных без резолверов. Это разные пространства имён: можно иметь тип User и input UserInput. Не используйте один для обоих — это ломает развитие схемы.

graphql
# OUTPUT type - returned from resolvers, has resolvers
type User {
  id: ID!
  name: String!
  posts: [Post!]!   # can have field arguments and resolvers
}

# INPUT type - passed into operations, no resolvers
input UserInput {
  name: String!
  email: String!
  # NO field arguments, NO resolvers, NO output object types
}

# A type cannot be used as both input and output.

Вложенные input

Input-типы могут ссылаться на другие input-типы и списки, моделируя сложные вложенные структуры. Это идеально для иерархических форм и вложенных фильтров. Каждый уровень проверяется по схеме, давая понятные ошибки при некорректном вводе.

graphql
input AddressInput {
  street: String!
  city: String!
  zip: String!
}

input CreateUserInput {
  name: String!
  email: String!
  address: AddressInput      # nested input type
  tags: [String!]            # list input
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

Значения по умолчанию в input

Поля input и аргументы могут иметь значения по умолчанию. Когда клиент опускает поле, применяется значение по умолчанию. Они делают input необязательным, не заставляя клиента отправлять весь объект. Учтите: значения по умолчанию — статические литералы, а не вычисляемые на запрос.

graphql
input PaginationInput {
  limit: Int = 20
  offset: Int = 0
  sort: SortOrder = DESC
}

enum SortOrder { ASC DESC }

type Query {
  posts(page: PaginationInput = { limit: 20, offset: 0 }): [Post!]!
}

# Defaults apply per-field when omitted by the client.

Валидация input

GraphQL проверяет типы и non-null, но не смысловые правила (формат email, диапазон возраста, длина строки). Реализуйте их в резолвере, бросая UserInputError при плохих данных. Некоторые серверы добавляют директивы валидации (@constraint) для декларативных правил.

graphql
input CreateUserInput {
  name: String!              # required, non-null
  email: String!             # format check needs custom code
  age: Int                   # range check needs custom code
}

# GraphQL validates structure; you validate semantics
function createUser(_, { input }) {
  if (!input.email.includes("@")) {
    throw new UserInputError("Invalid email");
  }
  if (input.age < 0 || input.age > 150) {
    throw new UserInputError("Invalid age");
  }
  // ...
}
17

Резолверы

Функции-резолверы

Резолвер — функция, возвращающая значение одного поля. Карта резолверов повторяет схему: resolvers.Query.user обслуживает поле user. Если резолвера нет, GraphQL использует стандартный, читающий одноимённое свойство у родителя.

graphql
const resolvers = {
  Query: {
    user: (parent, args, context, info) => {
      return context.db.user.findById(args.id);
    },
    users: () => db.users.findAll(),
  },
  Mutation: {
    createUser: (_, { input }, { db }) =>
      db.user.create(input),
  },
};

Аргументы резолвера

Каждый резолвер получает четыре аргумента: parent (вычисленное значение родительского поля), args (аргументы этого поля), context (общий объект на время запроса) и info (AST и метаданные выполнения). Чаще всего нужны первые два; info — для продвинутых случаев вроде анализа подвыборки.

graphql
// (parent, args, context, info)
const resolvers = {
  Query: {
    user: (parent, args, context, info) => {
      // parent   - value returned by the parent field (root for Query)
      // args     - arguments passed to this field
      // context  - shared per-request object (db, user, loaders)
      // info     - AST + execution info (rarely needed)
      return context.db.user.findById(args.id);
    },
  },
};

Цепочка резолверов

Резолверы выполняются цепочкой в глубину: резолвер родительского поля создаёт объект, затем резолвер каждого дочернего поля запускается с этим объектом как parent. Поток сверху вниз позволяет каждому полю вычисляться независимо — граф собирается поле за полем.

graphql
# query { user(id: "1") { name posts { title } } }
const resolvers = {
  Query: {
    user: () => ({ id: "1", name: "Alice" }),   // runs first
  },
  User: {
    posts: (user, args, ctx) => {                // runs after user
      return ctx.db.posts.findByAuthor(user.id);
    },
  },
  Post: {
    title: (post) => post.title,                 // runs after posts
  },
};

Асинхронные резолверы

Резолверы могут возвращать Promise; GraphQL ожидает их перед переходом к дочерним полям. Так вызываются БД и API. Для читаемости используйте async/await. Резолверы одного уровня выполняются параллельно (для запросов), поэтому независимая асинхронная работа естественно группируется.

graphql
const resolvers = {
  Query: {
    // return a Promise - GraphQL awaits it
    user: async (_, { id }, { db }) => {
      const user = await db.user.findById(id);
      if (!user) throw new Error("User not found");
      return user;
    },
  },
  User: {
    posts: async (user, _, { db }) =>
      db.posts.findByAuthor(user.id),
  },
};

Резолверы по умолчанию

Если у поля нет резолвера, GraphQL читает одноимённое свойство родительского объекта (возвращая null, если его нет). Пишите резолверы только для полей, которым нужна логика или загрузка. Стандартное поведение работает, когда родительские объекты уже имеют нужную форму.

graphql
# If you don't define a resolver, GraphQL reads from the parent
const resolvers = {
  User: {
    // name resolver missing - default behavior:
    // (parent) => parent.name
    posts: (user) => fetchPosts(user.id),  // only this is custom
  },
};

// Equivalent explicit default:
User: {
  name: (user) => (user.name === undefined ? null : user.name),
}

Лучшие практики резолверов

Держите резолверы тонкими: делегируйте загрузку классам источников данных в context. Это централизует доступ к данным (тестируемо, мокируемо) и позволяет источникам кешировать и объединять запросы. Резолвер должен оркестрировать, а не содержать SQL или логику загрузки напрямую.

graphql
# Keep resolvers thin - delegate to data sources
const resolvers = {
  Query: {
    user: (_, { id }, { dataSources }) =>
      dataSources.userAPI.getUser(id),
  },
  User: {
    posts: (user, _, { dataSources }) =>
      dataSources.postAPI.byAuthor(user.id),
  },
};

// dataSources live on context, are injected per request,
// and can batch/cache calls internally.
18

Context и DataLoader

Объект context

Context — объект на время запроса, общий для всех резолверов операции. Складывайте туда общие зависимости: клиенты БД, аутентифицированного пользователя, загрузчики данных и логгеры. Функция контекста выполняется один раз на запрос, а её результат передаётся каждому резолверу.

graphql
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => ({
    db: new PrismaClient(),
    user: getUserFromToken(req.headers.authorization),
    loaders: buildLoaders(),
  }),
});

// Inside any resolver, the third argument is context:
(parent, args, context) => context.db.user.findById(args.id);

Контекст на каждый запрос

Создавайте свежие экземпляры DataLoader внутри функции контекста, чтобы их кеши ограничивались одним запросом. Переиспользование загрузчика между запросами привело бы к утечке кешированных данных между пользователями. Контекст строится один раз на запрос — здесь и место для настройки на запрос.

graphql
const context = async ({ req }) => {
  const token = req.headers.authorization || "";
  const user = await verifyToken(token);  // may be null

  return {
    user,
    db,
    // a FRESH DataLoader instance per request
    // so caches don't leak across requests
    userLoader: new DataLoader((ids) => batchGetUsers(ids)),
  };
};

Проблема N+1

Проблема N+1: выбираем список из N элементов, затем делаем отдельный запрос на элемент, чтобы загрузить связь. Параллельное вычисление полей в GraphQL делает это очень вероятным: резолвер User.posts выполняется для каждого пользователя. Результат — лавина избыточных запросов.

graphql
# query { users { id name posts { title } } }
// BAD: 1 query for users, then N queries for each user's posts
const resolvers = {
  User: {
    posts: (user, _, { db }) =>
      db.posts.findByAuthor(user.id),  // runs once per user!
  },
};

// If there are 100 users, that's 101 DB queries.
// This is the classic N+1 problem.

Основы DataLoader

DataLoader объединяет множество отдельных загрузок в один пакетный запрос. Вы даёте ему batch-функцию, принимающую массив ключей и возвращающую массив результатов в том же порядке. Затем DataLoader собирает все загрузки в пределах тика и вызывает batch-функцию один раз.

graphql
import DataLoader from "dataloader";

// A batch function receives an array of keys, returns
// an array of values IN THE SAME ORDER as the keys.
const userLoader = new DataLoader(async (userIds) => {
  const users = await db.users.findMany({ where: { id: { in: userIds } } });
  // reorder to match the input keys
  return userIds.map((id) =>
    users.find((u) => u.id === id) ?? null
  );
});

DataLoader в резолверах

В резолверах используйте loader.load(key) вместо прямых запросов к БД. В пределах одного тика все загрузки одного загрузчика объединяются в один запрос, а результаты кешируются на время запроса. Это убивает N+1, сохраняя резолверы простыми.

graphql
const resolvers = {
  User: {
    posts: (user, _, { loaders }) =>
      loaders.postLoader.load(user.id),
  },
  Post: {
    author: (post, _, { loaders }) =>
      loaders.userLoader.load(post.authorId),
  },
};

// 100 users -> ONE batched query for all their posts,
// instead of 100 separate queries.

Пакетирование и кеширование

DataLoader делает две вещи: пакетирование (много загрузок за один тик цикла событий превращаются в один пакетный вызов) и кеширование по ключу (повторные загрузки того же ключа возвращают тот же Promise). Кеш принадлежит экземпляру загрузчика, поэтому создавайте свежий загрузчик на каждый запрос.

graphql
// Batching: many .load() calls in one tick -> one batch fn call
await Promise.all([loader.load(1), loader.load(2), loader.load(3)]);
// -> batchGetUsers([1, 2, 3]) called ONCE

// Caching: repeated .load(sameKey) returns the cached Promise
loader.load(1); loader.load(1); loader.load(1);
// -> batchGetUsers([1]) called ONCE; later calls hit cache

// .clear(key) invalidates; .clearAll() resets everything.
19

Обработка ошибок

Формат ответа с ошибкой

Ошибки возвращаются в массиве верхнего уровня errors рядом с data. У каждой ошибки есть message, location в запросе, path к упавшему полю и extensions для машиночитаемых кодов. Ошибка поля обнуляет это поле (или поднимается выше, если оно non-null), а data всё равно возвращает успешные части.

graphql
# Errors appear in a top-level "errors" array
{
  "errors": [
    {
      "message": "User not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "exception": { "stacktrace": ["..."] }
      }
    }
  ],
  "data": { "user": null }
}

Бросок ошибок

Простейшая обработка ошибок — бросить Error. GraphQL ловит его, обнуляет поле и добавляет запись в errors. Для большей структуры используйте специальные классы ошибок (ApolloError, UserInputError), несущие код в extensions.

graphql
const resolvers = {
  Query: {
    user: async (_, { id }, { db }) => {
      const user = await db.user.findById(id);
      if (!user) {
        throw new Error("User not found");
      }
      return user;
    },
  },
};

# Thrown errors become entries in the "errors" array.

Свои ошибки

Типизированные классы ошибок передают смысл: UserInputError для плохого ввода клиента (4xx), AuthenticationError при отсутствии аутентификации, ForbiddenError при отсутствии прав, ApolloError с кодом для своих случаев. Код в extensions позволяет клиентам надёжно ветвиться по ошибкам.

graphql
import { ApolloError, UserInputError } from "apollo-server-errors";

const resolvers = {
  Mutation: {
    createUser: (_, { input }) => {
      if (!isValidEmail(input.email)) {
        throw new UserInputError("Invalid email", {
          field: "email",
        });
      }
      if (emailTaken(input.email)) {
        throw new ApolloError("Email taken", "EMAIL_TAKEN", {
          email: input.email,
        });
      }
      // ...
    },
  },
};

Расширения ошибок

extensions несёт машиночитаемые данные: стабильный код, подсказки о повторе, пути к полям валидации и т. п. Клиенты должны ветвиться по extensions.code, а не разбирать человекочитаемое сообщение, которое может меняться. Не допускайте трассировок стека в ответах production.

graphql
# Structured, machine-readable error data
throw new ApolloError("Rate limited", "RATE_LIMITED", {
  code: "RATE_LIMITED",
  retryAfter: 60,
  limit: 100,
});

# Clients check extensions.code to handle errors
if (err.extensions.code === "RATE_LIMITED") {
  wait(err.extensions.retryAfter);
}

Частичные результаты

GraphQL возвращает частичные результаты: успешные поля приходят в data, упавшие — null (или поднимаются выше, если non-null) и перечислены в errors. Предпочитайте nullable-поля, чтобы одна ошибка не обнуляла весь ответ. Non-null — сильный контракт, применяйте его осознанно.

graphql
# A non-null field error nulls the parent; nullable just nulls the field
type Query {
  user(id: ID!): User       # nullable - error nulls only "user"
  me: User!                 # non-null - error bubbles up to null "me"
}

# Query selecting multiple fields:
query { me { name } user(id: "bad") { name } }
# If "user" errors but "me" succeeds:
{
  "data": { "me": { "name": "Alice" }, "user": null },
  "errors": [{ "path": ["user"], "message": "..." }]
}
20

Apollo Server и интеграция

Настройка Apollo Server

Apollo Server — самый популярный GraphQL-сервер для Node.js. Передайте typeDefs (SDL) и резолверы в конструктор, затем для быстрой разработки запустите standalone-сервер. В production интегрируйте его с существующим HTTP-фреймворком (Express, Fastify, Next.js), а не используйте standalone.

graphql
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";

const typeDefs = `#graphql
  type Query { hello: String }
`;

const resolvers = {
  Query: { hello: () => "Hello, world!" },
};

const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});
console.log(`Server ready at ${url}`);

Интеграция с Express

Для Express используйте expressMiddleware из @apollo/server/express4. Запустите сервер до монтирования middleware. Функция context получает req/res Express, позволяя читать заголовки, сессии и прикреплять аутентификацию. Так GraphQL встраивается в существующее приложение Express.

graphql
import { ApolloServer } from "@apollo/server";
import { expressMiddleware } from "@apollo/server/express4";
import express from "express";
import cors from "cors";
import bodyParser from "body-parser";

const app = express();
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();

app.use("/graphql", cors(), bodyParser.json(),
  expressMiddleware(server, {
    context: async ({ req }) => ({ user: getUser(req) }),
  })
);
app.listen(4000);

Сборка схемы

makeExecutableSchema (из @graphql-tools/schema) собирает схему из typeDefs и резолверов, возвращая объект GraphQLSchema для ApolloServer. Это промежуточное звено открывает transforms схемы, объединение модулей и свои директивы — полезно в крупных кодовых базах.

graphql
import { makeExecutableSchema } from "@graphql-tools/schema";

const schema = makeExecutableSchema({
  typeDefs,
  resolvers,
});

const server = new ApolloServer({ schema });

// makeExecutableSchema lets you apply schema transforms,
// directive visitors, and merge modules before serving.

Функция контекста

Функция context выполняется один раз на запрос, и её результат общий для всех резолверов. Читайте здесь заголовки аутентификации и прикрепляйте пользователя, клиентов БД и свежие DataLoader. Бросок внутри context отклоняет запрос до запуска резолверов (например, при плохой аутентификации).

graphql
const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => {
    const token = req.headers.authorization || "";
    const user = await verifyToken(token);
    return { user, db, loaders: makeLoaders() };
  },
  listen: { port: 4000 },
});

Apollo Studio / Sandbox

Apollo Sandbox (в браузере по URL сервера) позволяет изучать схему и выполнять операции при разработке. Apollo Studio — облачный аналог для истории схемы, метрик и трассировки. В production отключите интроспекцию, если хотите скрыть схему от посторонних.

graphql
# Apollo Sandbox is a dev IDE in the browser
# Visit the server URL in a browser to open it.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  // Apollo Studio reports go through this key (optional)
  // apollo: { graphRef: "my-graph@current" },
});

# For introspection in production, enable it explicitly:
# new ApolloServer({ introspection: true });

Жизненный цикл запроса

Apollo Server проходит жизненный цикл на каждый запрос: строит контекст, разбирает запрос, валидирует по схеме, выполняет резолверы, форматирует ответ. formatError настраивает форму ошибок; плагины цепляются к фазам вроде didResolveOperation, willSendResponse — удобно для логирования, кеширования и метрик.

graphql
# Order: HTTP request -> context -> parse -> validate ->
#        execute (resolvers) -> format response -> HTTP response

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formatted, error) => ({
    message: error.message,
    code: formatted.extensions?.code,
  }),
  plugins: [loggingPlugin, cachePlugin],
});

# plugins hook into every lifecycle phase.

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.