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

Введение

GraphQL — язык запросов к API и среда выполнения этих запросов на сервере по системе типов, которую вы задаёте для своих данных. Спецификация GraphQL открыта в 2015 году, и с тех пор GraphQL реализован на множестве языков программирования. GraphQL не привязан к конкретной базе данных или системе хранения — за ним стоят ваш существующий код и данные.

Этот раздел — перевод официального руководства «Learn» с сайта graphql.org с примерами на демонстрационной схеме Star Wars, как в оригинале. Ответы к запросам получены выполнением этих запросов. Полную схему примеров можно открыть в редакторе — на странице «Схема примеров».

Описание API системой типов

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

type Query {
  me: User
}

type User {
  name: String
}

Вместе с функциями для каждого поля каждого типа:

// Резолвер поля `me` типа `Query`
function resolveQueryMe(_parent, _args, context, _info) {
  return context.request.auth.user;
}

// Резолвер поля `name` типа `User`
function resolveUserName(user, _args, context, _info) {
  return context.db.getUserFullName(user.id);
}

В этом примере функция, которая возвращает данные поля me типа Query, берёт сведения о пользователе, выполнившем запрос, а поле name типа User заполняется полным именем, которое загружается из базы данных по идентификатору этого пользователя.

Запрашивайте ровно то, что нужно

Когда сервис GraphQL запущен (обычно по адресу веб-сервиса), он принимает от клиентов запросы GraphQL, проверяет и выполняет их. Сначала сервис убеждается, что запрос обращается только к типам и полям, определённым в API, а затем вызывает функции полей и формирует результат.

Например, запрос:

{
  me {
    name
  }
}

может вернуть такой результат в JSON:

{
  "data": {
    "me": {
      "name": "Luke Skywalker"
    }
  }
}

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

Развитие API без версий

Требования клиентов со временем меняются, и GraphQL позволяет развивать API вслед за ними — без затрат на поддержку нескольких версий API. Например, если для новой функции нужно имя в более подробном виде, тип User можно дополнить так:

type User {
  fullName: String
  nickname: String
  name: String @deprecated(reason: "Используйте `fullName`.")
}

Инструменты клиентов подскажут разработчикам перейти на новые поля и отказаться от устаревшего поля name. Поле можно удалить, когда станет ясно, что его больше не используют, а до тех пор GraphQL продолжает отдавать его данные как обычно.

Попробуйте

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

{
  hero {
    name
  }
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2"
    }
  }
}

Добавьте к объекту hero поля id и appearsIn — и в ответе появятся идентификатор героя и эпизоды, в которых он снимался:

{
  hero {
    id
    name
    appearsIn
  }
}

Ответ:

{
  "data": {
    "hero": {
      "id": "2001",
      "name": "R2-D2",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ]
    }
  }
}

Примеры руководства основаны на изменённой версии схемы SWAPI GraphQL. Запросы составлены для наглядности и из-за различий схем не выполнятся на полной версии SWAPI GraphQL API.

Схема в редакторе «Помощника SA»

Редактор GraphQL работает со схемой: слева — SDL, справа — карта типов, как в GraphQL Voyager: карточки типов с полями, стрелки от полей к типам их значений, интерфейсы и объединения. Карточки можно перетаскивать мышью — расположение сохраняется вместе со схемой. Вместо SDL можно вставить результат запроса introspection — так удобно разбирать схему существующего API.

Полные схемы в этой документации открываются в редакторе кнопкой «Открыть в редакторе»; фрагменты схемы и запросы показаны как примеры кода.

Дальше

Теперь, зная ключевые понятия GraphQL, переходите к его системе типов.

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