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