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

Ответ сервера

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

Данные

Как видно из примеров руководства, результат выполнения запроса GraphQL возвращается в ключе data верхнего уровня. Например:

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

Ответ:

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

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

Конкретный формат сериализации ответа спецификация не требует, но обычно ответы передают в JSON, как в примере выше.

Не требует спецификация и определённого транспортного протокола, хотя запросы и изменения, не хранящие состояние, обычно передают по HTTP. Долгоживущие подписки с состоянием чаще работают через WebSocket или server-sent events.

Есть черновик спецификации GraphQL over HTTP с подробными рекомендациями по использованию HTTP клиентами и серверами GraphQL.

Ошибки

Кроме ключа data, спецификация GraphQL описывает, как оформлять в ответе ошибки. Вернёт ли реализация вместе с ошибками частичные данные, зависит от вида ошибки. Рассмотрим виды ошибок, которые возникают на разных этапах жизненного цикла запроса GraphQL.

Ошибки запроса

Ошибки запроса обычно возникают по вине клиента. Например, в документе может быть синтаксическая ошибка — пропущенная скобка или неизвестное ключевое слово корневого типа операции:

operation {
  updateHumanName(id: "1000", name: "Luke Starkiller") {
    id
    name
  }
}

Ответ:

{
  "errors": [
    {
      "message": "Syntax Error: Unexpected Name \"operation\".",
      "locations": [
        {
          "line": 1,
          "column": 1
        }
      ]
    }
  ]
}

Ключ message в объекте ошибки помогает разработчику понять, что произошло, а ключ locations, если он есть, показывает, где в документе возникла ошибка.

Бывает, что запрос синтаксически правильный, но при разборе и проверке по схеме сервер находит проблему в части операции и выдаёт ошибку проверки.

Например, клиент запрашивает поле, которого нет у типа Starship:

query {
  starship(id: 3000) {
    width
  }
}

Ответ:

{
  "errors": [
    {
      "message": "Cannot query field \"width\" on type \"Starship\". Did you mean \"id\"?",
      "locations": [
        {
          "line": 3,
          "column": 5
        }
      ]
    }
  ]
}

Ошибки проверки возникают и тогда, когда тип переменной не подходит к аргументу поля:

query HeroForEpisode($ep: String!) {
  hero(episode: $ep) {
    name
  }
}

Переменные:

{
  "ep": "JEDI"
}

Ответ:

{
  "errors": [
    {
      "message": "Variable \"$ep\" of type \"String!\" used in position expecting type \"Episode\".",
      "locations": [
        {
          "line": 1,
          "column": 22
        },
        {
          "line": 2,
          "column": 17
        }
      ]
    }
  ]
}

В этих примерах видно: при ошибке запроса ключа data в ответе нет — сервер возвращает ошибку ещё до вызова резолверов полей.

Ошибки полей

Ошибки полей возникают, если во время выполнения случилось что-то непредвиденное. Например, резолвер сам выдал ошибку или вернул недопустимые данные — скажем, null для поля с обязательным выходным типом.

В таких случаях GraphQL пытается выполнить остальные поля и возвращает частичный ответ: ключ data вместе с ключом errors.

Пример:

mutation {
  firstShip: deleteStarship(id: "3001")
  secondShip: deleteStarship(id: "3010")
}

Ответ:

{
  "errors": [
    {
      "message": "Starship not found",
      "locations": [
        {
          "line": 3,
          "column": 3
        }
      ],
      "path": [
        "secondShip"
      ]
    }
  ],
  "data": {
    "firstShip": "3001",
    "secondShip": null
  }
}

Изменение пытается удалить два корабля за одну операцию, но корабля с идентификатором 3010 нет, и сервер выдаёт ошибку. В ответе — сведения об ошибке поля с псевдонимом secondShip. А в ключе data возвращён идентификатор первого корабля — знак успешного удаления, тогда как второй корабль из-за ошибки в резолвере дал null.

Сетевые ошибки

Как и при обращении к любому API, на любом этапе запроса могут случиться сетевые ошибки, не связанные с GraphQL. Они прерывают связь клиента и сервера до завершения запроса — например, ошибка SSL или таймаут соединения. В зависимости от выбранных библиотек сервера и клиента GraphQL в них может быть встроенная обработка сетевых ошибок — например, повтор неудачных операций.

Расширения

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

Например, некоторые серверы GraphQL кладут сюда телеметрию или сведения о расходе лимита запросов. Какие данные есть в extensions и доступны ли они в боевой среде или только при разработке, полностью зависит от реализации.

Итоги

Подведём итоги о формате ответа GraphQL:

  • спецификация допускает в ответе три ключа верхнего уровня: data, errors и extensions;
  • в ответе есть хотя бы один из ключей data или errors (если есть оба — это «частичный ответ»);
  • ключ data содержит результат выполненной операции;
  • сведения о возникших ошибках — в ключе errors;
  • ошибки запроса (синтаксические и ошибки проверки) возникают до начала выполнения, поэтому data в ответе нет;
  • при ошибке поля во время выполнения в errors будет её описание, а в data могут быть частичные данные;
  • в ключе extensions реализации GraphQL могут передавать любые дополнительные сведения об ответе.

Теперь, зная этапы обработки запроса GraphQL и формат ответа, переходите к странице «Интроспекция»: как сервер GraphQL отвечает на вопросы о собственной схеме.

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