Документация / 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 г.
