Документация / GraphQL
Схема и типы
Система типов GraphQL описывает, какие данные можно запросить у API. Совокупность этих возможностей называют схемой сервиса; по схеме клиенты составляют запросы и получают предсказуемые результаты.
В GraphQL шесть видов именованных типов: объектные типы, скаляры, перечисления, интерфейсы, объединения и входные типы. На этой странице разобраны объектные типы, скаляры, перечисления и модификаторы типов; интерфейсы, объединения и входные типы — на странице «Интерфейсы, объединения и входные типы». GraphQL можно использовать с любым backend-фреймворком и языком программирования, поэтому подробности реализации опущены — речь только о понятиях.
Система типов
Если вы уже видели запрос GraphQL, то знаете, что язык запросов — это, по сути, выбор полей у объектов. Например, в запросе:
{
hero {
name
appearsIn
}
}
Ответ:
{
"data": {
"hero": {
"name": "R2-D2",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
}
}
}
- Мы начинаем со специального «корневого» объекта.
- Выбираем у него поле
hero. - У объекта, который вернуло
hero, выбираем поляnameиappearsIn.
Форма запроса GraphQL близка к форме результата, поэтому можно предсказать ответ, почти ничего не зная о сервере. Но полезно иметь и точное описание данных, которые можно запросить: какие поля можно выбрать, какие объекты они возвращают, какие поля есть у этих вложенных объектов?
Для этого и нужна схема. Каждый сервис GraphQL определяет набор типов, который полностью описывает данные, доступные для запроса. Пришедший запрос проверяется и выполняется по этой схеме.
Язык описания типов
Сервисы GraphQL пишут на любых языках, и способы определить типы схемы различаются:
- одни библиотеки строят типы, поля и функции-резолверы схемы на том же языке программирования, на котором написана реализация GraphQL;
- другие позволяют удобно описать типы и поля на языке описания схемы (schema definition language, SDL), а функции-резолверы для полей написать отдельно;
- третьи позволяют написать и разметить функции-резолверы, а схему вывести из них;
- некоторые библиотеки даже выводят и типы, и резолверы сами — по источнику данных.
Мы не можем опираться на конкретный язык программирования, поэтому в руководстве используется SDL: он похож на уже знакомый язык запросов и позволяет говорить о схемах GraphQL независимо от языка реализации.
Объектные типы и поля
Основа схемы GraphQL — объектные типы: вид объекта, который можно получить от сервиса, и его поля. На SDL это выглядит так:
type Character {
name: String!
appearsIn: [Episode!]!
}
Язык понятен и так, но разберём его, чтобы говорить на одном языке:
Character— объектный тип GraphQL, то есть тип с полями. Большинство типов схемы — объектные.nameиappearsIn— поля типаCharacter. Только эти поля можно выбрать в любой части запроса, которая работает с типомCharacter.String— один из встроенных скалярных типов. Скаляр — единичное значение, у которого в запросе нельзя выбрать вложенные поля. Подробнее о скалярах — ниже.String!означает, что поле обязательное (Non-Null): сервис обещает всегда вернуть значение этого поля. В SDL обязательность обозначают восклицательным знаком.[Episode!]!— список (List) объектовEpisode. Список обязательный, поэтому при запросе поляappearsInвсегда приходит массив (из нуля или более элементов). ЭлементEpisode!тоже обязательный, поэтому каждый элемент массива — объектEpisode.
Теперь вы знаете, как выглядит объектный тип GraphQL и как читать основы SDL.
Аргументы
У каждого поля объектного типа может быть ноль или больше аргументов,
как у поля length ниже:
type Starship {
id: ID!
name: String!
length(unit: LengthUnit = METER): Float
}
Все аргументы именованные. В отличие от JavaScript или Python, где функция принимает упорядоченный список
аргументов, в GraphQL аргументы всегда передаются по имени. Здесь у поля length один аргумент — unit.
Аргументы бывают обязательными и необязательными. Для необязательного аргумента можно задать значение по
умолчанию: если unit не передан, он будет равен METER.
Типы Query, Mutation и Subscription
Каждая схема GraphQL обязана поддерживать операции query. Точка входа этого
корневого типа операции — обычный объектный тип,
по умолчанию он называется Query. Поэтому если вы видите такой запрос:
{
droid(id: "2000") {
name
}
}
Ответ:
{
"data": {
"droid": {
"name": "C-3PO"
}
}
}
значит, у сервиса GraphQL есть тип Query с полем droid:
type Query {
droid(id: ID!): Droid
}
Схема может поддерживать и операции mutation и subscription — для этого добавляют типы Mutation и
Subscription и определяют поля в этих корневых типах.
Важно помнить: если не считать особой роли точек входа в схему, типы Query, Mutation и Subscription
ничем не отличаются от других объектных типов GraphQL, и их поля работают точно так же.
Корневые типы можно назвать и по-другому — тогда новые имена нужно сообщить GraphQL ключевым словом schema:
schema {
query: MyQueryType
mutation: MyMutationType
subscription: MySubscriptionType
}
На карте схемы в редакторе корень выбирается в панели «Описание»: от
Query,MutationилиSubscriptionпоказываются типы, достижимые от него по полям, а вариант «Все типы» показывает всю схему.
Скалярные типы
У объектного типа есть имя и поля, но в какой-то момент поля должны вернуть конкретные данные. Для этого служат скалярные типы — «листья» запроса.
В следующем запросе поля name и appearsIn возвращают скаляры:
{
hero {
name
appearsIn
}
}
Ответ:
{
"data": {
"hero": {
"name": "R2-D2",
"appearsIn": [
"NEWHOPE",
"EMPIRE",
"JEDI"
]
}
}
}
Это видно по тому, что у них нет вложенных полей — они листья запроса.
В GraphQL есть набор встроенных скалярных типов:
| Тип | Значение |
|---|---|
Int | Целое 32-битное число со знаком |
Float | Число с плавающей точкой двойной точности со знаком |
String | Последовательность символов UTF-8 |
Boolean | true или false |
ID | Уникальный идентификатор — часто для повторной загрузки объекта или как ключ кеша. Передаётся так же, как String, но тип ID показывает, что значение не предназначено для чтения человеком |
В большинстве реализаций GraphQL можно объявить и свои скалярные типы. Например, тип Date:
scalar Date
Как такой тип сериализуется, разбирается и проверяется, решает реализация. Например, можно договориться,
что Date всегда передаётся как целое число — метка времени, и клиент должен ожидать этот формат у всех
полей с датами.
Формат своего скаляра принято указывать встроенной директивой
@specifiedBy:scalar DateTime @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time").
Перечисления
Перечисления (enum) — особый вид скаляра, значения которого ограничены заданным набором. Перечисление позволяет:
- проверять, что аргумент этого типа принимает одно из допустимых значений;
- сообщать через систему типов, что поле всегда возвращает одно значение из конечного набора.
Определение перечисления на SDL:
enum Episode {
NEWHOPE
EMPIRE
JEDI
}
Это значит, что везде, где в схеме используется тип Episode, ожидается ровно одно из значений NEWHOPE,
EMPIRE или JEDI.
Реализации GraphQL на разных языках по-своему работают с перечислениями. В языках, где перечисления есть, реализация может использовать их; в JavaScript, где перечислений нет, значения могут внутри сопоставляться с целыми числами. Клиент этих подробностей не видит — он работает только со строковыми именами значений.
Модификаторы типов
По умолчанию типы в GraphQL допускают null и обозначают одно значение. Но при использовании именованных
типов в схеме (или в объявлениях переменных запроса) можно применить
модификаторы типов, которые меняют смысл значений.
Как в примере объектного типа выше, в GraphQL два модификатора — список и обязательность (Non-Null); их можно использовать по отдельности и вместе.
Обязательное значение
Пример:
type Character {
name: String!
}
Здесь используется тип String, а восклицательный знак ! после имени типа делает его обязательным. Сервер
обещает всегда возвращать для этого поля значение, отличное от null; если резолвер всё же вернёт null,
возникнет ошибка выполнения GraphQL, и клиент узнает, что что-то пошло не так.
Модификатор обязательности можно применять и к аргументам поля — тогда при передаче null в такой аргумент
сервер GraphQL вернёт ошибку проверки:
{
droid(id: null) {
name
}
}
Ответ:
{
"errors": [
{
"message": "Expected value of type \"ID!\", found null.",
"locations": [
{
"line": 2,
"column": 13
}
]
}
]
}
Список
Списки работают похоже. Модификатор помечает тип как список — поле возвращает массив значений этого типа.
В SDL тип заключают в квадратные скобки [ и ]. Для аргументов так же: при проверке ожидается массив.
Пример:
type Character {
name: String!
appearsIn: [Episode]!
}
Модификаторы списка и обязательности можно сочетать. Например, список обязательных строк String:
myField: [String!]
Это значит, что сам список может быть null, но элементов null в нём быть не может. В JSON:
myField: null // допустимо
myField: [] // допустимо
myField: ["a", "b"] // допустимо
myField: ["a", null, "b"] // ошибка
Теперь объявим обязательный список строк:
myField: [String]!
Сам список не может быть null, но может содержать значения null:
myField: null // ошибка
myField: [] // допустимо
myField: ["a", "b"] // допустимо
myField: ["a", null, "b"] // допустимо
Наконец, обязательный список обязательных строк:
myField: [String!]!
Список не может быть null и не может содержать null:
myField: null // ошибка
myField: [] // допустимо
myField: ["a", "b"] // допустимо
myField: ["a", null, "b"] // ошибка
Модификаторы списка и обязательности можно вкладывать друг в друга сколько угодно раз.
В GraphQL нельзя объявить тип так, чтобы корректным считался только непустой список:
[]— допустимое значение и для обязательного списка обязательных элементов.
Сводная таблица:
| Тип | Допустимые значения |
|---|---|
String | "a", null |
String! | "a" |
[String] | null, [], ["a", null] |
[String!] | null, [], ["a"] |
[String]! | [], ["a", null] |
[String!]! | [], ["a"] |
Дальше
Переходите к абстрактным типам — интерфейсам и объединениям, а также к входным типам для сложных аргументов.
Похожие инструменты
Обновлено: 17 октября 2026 г.
