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