Документация / GraphQL

Выполнение

Когда разобранный документ проверен, сервер GraphQL выполняет запрос клиента, и форма возвращённого результата повторяет форму запроса. На этой странице разобран этап выполнения операций GraphQL: данные читаются из существующего источника или записываются в него в зависимости от полей, запрошенных клиентом.

Резолверы полей

Без системы типов GraphQL не может выполнять операции, поэтому возьмём пример системы типов — часть той же схемы, что используется в примерах руководства:

type Query {
  human(id: ID!): Human
}

type Human {
  name: String
  appearsIn: [Episode]
  starships: [Starship]
}

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

type Starship {
  name: String
}

Разберём на примере, что происходит при выполнении запроса:

query {
  human(id: 1002) {
    name
    appearsIn
    starships {
      name
    }
  }
}

Ответ:

{
  "data": {
    "human": {
      "name": "Han Solo",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ],
      "starships": [
        {
          "name": "Millenium Falcon"
        },
        {
          "name": "Imperial shuttle"
        }
      ]
    }
  }
}

Каждое поле запроса GraphQL можно считать функцией или методом предыдущего типа, которая возвращает следующий тип. Так GraphQL и работает: за каждым полем каждого типа стоит функция-резолвер (resolver), которую пишет разработчик сервера GraphQL. Когда поле выполняется, вызывается его резолвер, и тот возвращает следующее значение.

Если поле возвращает скаляр — строку или число, — выполнение поля завершено. Если же поле возвращает объект, в запросе есть ещё один набор полей этого объекта. Так продолжается, пока не будут достигнуты листья. Запросы GraphQL всегда заканчиваются скалярами или перечислениями.

Корневые поля и резолверы

На верхнем уровне каждого сервера GraphQL — объектный тип со всеми возможными точками входа в API; его часто называют «корневым типом операции query» или просто типом Query. Если API позволяет записывать данные и получать их в реальном времени, в нём есть ещё типы Mutation и Subscription с полями для таких операций. Подробнее — на странице «Схема и типы».

В примере тип Query содержит поле human с аргументом id. Резолвер этого поля, скорее всего, обращается к базе данных, а затем создаёт и возвращает объект Human:

function resolveHuman(obj, args, context, info) {
  return context.db.loadHumanByID(args.id).then(userData => new Human(userData));
}

Пример на JavaScript, но серверы GraphQL пишут на многих языках. В эталонной реализации резолвер получает четыре аргумента:

  • obj — предыдущий объект (для полей корневого типа Query обычно не используется);
  • args — аргументы, переданные полю в операции GraphQL;
  • context — значение, которое передаётся всем резолверам; в нём держат важный контекст: текущего пользователя, доступ к базе данных;
  • info — используется в основном в сложных случаях: сведения о поле в текущей операции и о схеме; подробнее — тип GraphQLResolveInfo.

Технически операция запроса тоже может записывать данные во время выполнения, но для запросов с побочными эффектами по соглашению используют изменения. А раз у изменений есть побочные эффекты, реализации GraphQL выполняют их поля последовательно.

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

Посмотрим внимательнее, что происходит в этом резолвере:

function resolveHuman(obj, args, context, info) {
  return context.db.loadHumanByID(args.id).then(userData => new Human(userData));
}

Аргумент id в запросе указывает, чьи данные запрошены, а context даёт доступ к базе данных. Загрузка из базы данных — асинхронная операция, поэтому резолвер возвращает Promise. В JavaScript промисы служат для работы с асинхронными значениями; во многих языках то же называют Future, Task или Deferred. Когда база данных вернёт данные, мы создаём и возвращаем новый объект Human.

Резолвер должен знать о промисах, а запрос GraphQL — нет. Он просто ожидает, что поле human вернёт что-то, из чего можно получить скалярное значение name. При выполнении GraphQL дожидается завершения промисов, Future и Task, прежде чем продолжить, и делает это с оптимальным параллелизмом.

Тривиальные резолверы

Теперь объект Human есть, и выполнение продолжается с полей, запрошенных у этого типа:

function resolveHumanName(obj, args, context, info) {
  return obj.name;
}

Сервер GraphQL опирается на систему типов, чтобы понять, что делать дальше. Ещё до того как поле human что-то вернёт, GraphQL знает, что следующим шагом будут поля типа Human: система типов говорит, что поле human возвращает этот выходной тип.

Получить имя здесь просто. Вызывается резолвер name, в аргументе obj — новый объект Human, возвращённый предыдущим полем. Ожидается, что у этого объекта есть свойство name, его можно прочитать и вернуть.

Многие библиотеки GraphQL позволяют такие простые резолверы не писать: если резолвер поля не задан, читается и возвращается одноимённое свойство объекта.

Приведение скаляров

Пока вычисляется поле name, параллельно могут вычисляться appearsIn и starships. У поля appearsIn тоже может быть тривиальный резолвер, но посмотрим на него внимательнее:

const Human = {
  appearsIn(obj) {
    return obj.appearsIn; // например, [4, 5, 6]
  },
};

Система типов утверждает, что appearsIn возвращает значения перечисления, а функция возвращает числа! И всё же в результате — правильные значения перечисления. Что происходит?

Это приведение скаляров (scalar coercion). Система типов знает, чего ожидать, и преобразует значения, возвращённые резолвером, так, чтобы соблюдался контракт API. Здесь на сервере может быть перечисление, которое внутри использует числа 4, 5 и 6, а в системе типов GraphQL представляет их ожидаемыми значениями.

Резолверы списков

Поле appearsIn уже показало, что происходит, когда поле возвращает список: оно вернуло список значений перечисления, и, раз система типов ожидала именно это, каждый элемент был приведён к нужному значению. А что происходит при вычислении поля starships?

function resolveHumanStarships(obj, args, context, info) {
  return Promise.all(
    obj.starshipIDs.map(id =>
      context.db.loadStarshipByID(id).then(shipData => new Starship(shipData))
    )
  );
}

Этот резолвер возвращает не просто промис, а список промисов. У объекта Human был список идентификаторов кораблей, которыми управлял персонаж, и по ним нужно загрузить настоящие объекты Starship.

GraphQL параллельно дождётся всех промисов, а получив список объектов, так же параллельно продолжит — загрузит поле name у каждого элемента.

Формирование результата

Значение каждого вычисленного поля помещается в словарь: ключ — имя поля (или псевдоним), значение — результат. Так результат собирается от полей-листьев запроса до исходного поля корневого типа Query. Вместе они образуют структуру, повторяющую исходный запрос, — её отправляют клиенту (обычно в JSON).

Ещё раз посмотрим на исходный запрос и его результат, собранный всеми этими резолверами:

query {
  human(id: 1002) {
    name
    appearsIn
    starships {
      name
    }
  }
}

Ответ:

{
  "data": {
    "human": {
      "name": "Han Solo",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ],
      "starships": [
        {
          "name": "Millenium Falcon"
        },
        {
          "name": "Imperial shuttle"
        }
      ]
    }
  }
}

Каждое поле вложенных наборов выбора при выполнении запроса доходит до скалярного значения-листа.

Итоги

Подведём итоги о выполнении:

  • у каждого поля системы типов GraphQL есть функция-резолвер, которая берёт данные поля из существующего источника;
  • выполнение начинается с полей верхнего уровня Query, Mutation или Subscription;
  • резолверы могут выполняться асинхронно;
  • приведение скаляров преобразует значения к типам, которые ожидает схема;
  • если поле объектного типа возвращает список других объектов, может понадобиться загрузить дополнительные данные, чтобы превратить ссылки вроде внешних ключей (идентификаторов) в связанные объекты;
  • когда все запрошенные поля вычислены до ожидаемых листьев, результат отправляется клиенту, обычно в JSON.

Дальше — последний этап жизненного цикла запроса GraphQL: ответ клиенту.

Обновлено: 17 октября 2026 г.