Документация / GraphQL
Проверка запросов
На этой странице разобран важный этап жизненного цикла запроса GraphQL — проверка (validation). Чтобы запрос выполнился, он должен быть синтаксически правильным, но ещё и корректным по схеме API.
Когда операция GraphQL приходит на сервер, документ сначала разбирается, а затем проверяется по системе типов. Так сервер и клиент сообщают разработчику о некорректном запросе без проверок во время выполнения. После успешной проверки операцию можно выполнить на сервере и вернуть клиенту ответ.
Примеры проверки
Спецификация GraphQL подробно описывает условия, которым должен удовлетворять корректный запрос. Ниже — несколько частых ошибок проверки в операциях GraphQL.
Запрос несуществующих полей
Запрашиваемое поле должно быть определено в соответствующем типе. Поле hero возвращает тип Character,
поэтому в его наборе выбора можно запрашивать только поля типа Character; поля favoriteSpaceship у
Character нет, и запрос некорректен:
# НЕКОРРЕКТНО: у Character нет поля favoriteSpaceship
query {
hero {
favoriteSpaceship
}
}
Ответ:
{
"errors": [
{
"message": "Cannot query field \"favoriteSpaceship\" on type \"Character\".",
"locations": [
{
"line": 4,
"column": 5
}
]
}
]
}
Наборы выбора и поля-листья
Если запрашиваемое поле возвращает не скаляр и не перечисление, нужно указать, какие данные получить от поля, —
набор выбора. Поле hero возвращает Character, и выше в нём уже запрашивались поля name и appearsIn.
Без выбора полей-листьев запрос некорректен:
# НЕКОРРЕКТНО: hero — не скаляр, нужны поля
query {
hero
}
Ответ:
{
"errors": [
{
"message": "Field \"hero\" of type \"Character\" must have a selection of subfields. Did you mean \"hero { ... }\"?",
"locations": [
{
"line": 3,
"column": 3
}
]
}
]
}
И наоборот, запрашивать поля у скаляра или перечисления бессмысленно, поэтому набор выбора у поля-листа тоже делает запрос некорректным:
# НЕКОРРЕКТНО: name — скаляр, поля у него запрашивать нельзя
query {
hero {
name {
firstCharacterOfName
}
}
}
Ответ:
{
"errors": [
{
"message": "Field \"name\" must not have a selection since type \"String!\" has no subfields.",
"locations": [
{
"line": 4,
"column": 10
}
]
}
]
}
Нет фрагментов у полей абстрактных типов
Как уже говорилось, запрос может спрашивать только поля рассматриваемого типа. Поле hero возвращает
Character, поэтому можно запрашивать только поля интерфейса Character. А если нужна основная функция R2-D2?
# НЕКОРРЕКТНО: у Character нет поля primaryFunction
query {
hero {
name
primaryFunction
}
}
Ответ:
{
"errors": [
{
"message": "Cannot query field \"primaryFunction\" on type \"Character\". Did you mean to use an inline fragment on \"Droid\"?",
"locations": [
{
"line": 5,
"column": 5
}
]
}
]
}
Запрос некорректен: primaryFunction не входит в общие поля интерфейса Character. Нужен способ сказать:
«получить primaryFunction, если Character — это Droid, а иначе пропустить поле». Для этого служат
фрагменты. Фрагмент, определённый на Droid и включённый в набор выбора,
запрашивает primaryFunction только там, где поле определено:
query {
hero {
name
...DroidFields
}
}
fragment DroidFields on Droid {
primaryFunction
}
Ответ:
{
"data": {
"hero": {
"name": "R2-D2",
"primaryFunction": "Astromech"
}
}
}
Запрос корректен, но многословен: именованные фрагменты выручали, когда использовались несколько раз, а здесь фрагмент нужен однажды. Вместо именованного фрагмента можно взять встроенный — он тоже указывает тип, но без отдельного объявления:
query {
hero {
name
... on Droid {
primaryFunction
}
}
}
Ответ:
{
"data": {
"hero": {
"name": "R2-D2",
"primaryFunction": "Astromech"
}
}
}
Циклические фрагменты
Начнём со сложного корректного запроса. Он вложенный, а повторяющиеся поля вынесены во фрагмент:
query {
hero {
...NameAndAppearances
friends {
...NameAndAppearances
friends {
...NameAndAppearances
}
}
}
}
fragment NameAndAppearances on Character {
name
appearsIn
}
Ответ:
{
"data": {
"hero": {
"name": "R2-D2",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
],
"friends": [
{
"name": "Luke Skywalker",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
],
"friends": [
{
"name": "Han Solo",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
},
{
"name": "Leia Organa",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
},
{
"name": "C-3PO",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
},
{
"name": "R2-D2",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
}
]
},
{
"name": "Han Solo",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
],
"friends": [
{
"name": "Luke Skywalker",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
},
{
"name": "Leia Organa",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
},
{
"name": "R2-D2",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
}
]
},
{
"name": "Leia Organa",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
],
"friends": [
{
"name": "Luke Skywalker",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
},
{
"name": "Han Solo",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
},
{
"name": "C-3PO",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
},
{
"name": "R2-D2",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
}
]
}
]
}
}
}
А вот попытка заменить три явных уровня вложенности рекурсией. Такой запрос некорректен: фрагмент не может ссылаться сам на себя ни прямо, ни косвенно — цикл мог бы дать бесконечный результат!
query {
hero {
...NameAndAppearancesAndFriends
}
}
fragment NameAndAppearancesAndFriends on Character {
name
appearsIn
friends {
...NameAndAppearancesAndFriends
}
}
Ответ:
{
"errors": [
{
"message": "Cannot spread fragment \"NameAndAppearancesAndFriends\" within itself.",
"locations": [
{
"line": 11,
"column": 5
}
]
}
]
}
Это лишь малая часть системы проверки: множество правил гарантирует, что операция GraphQL имеет смысл. Подробнее — в разделе спецификации о проверке, а в каталоге validation эталонной реализации — код проверки по спецификации.
Ошибки проверки
Как видно из примеров, обнаружив ошибку проверки, сервер GraphQL возвращает сведения о ней в ключе errors
ответа. Точнее, найдя ошибку проверки в документе, GraphQL выдаёт ошибку запроса ещё до начала выполнения —
частичных данных в ответе не будет.
Спецификация обязывает все реализации проверять входящие запросы по схеме, поэтому разработчикам не нужно писать для этого отдельную логику.
Ответы с ошибками на этой странице получены эталонной реализацией graphql-js, поэтому сообщения — на английском, как их возвращают серверы.
Итоги
Подведём итоги о проверке:
- чтобы выполниться, запрос должен содержать синтаксически правильный документ, корректный по схеме;
- спецификация требует проверять, что входящие запросы правильно выбирают поля, используют фрагменты и многое другое;
- при ошибке проверки сервер возвращает ошибку запроса со сведениями о ней; выполнение полей не начинается.
Дальше — страница «Выполнение»: как GraphQL получает данные каждого поля запроса после успешной проверки.
Похожие инструменты
Обновлено: 17 октября 2026 г.
