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

Схема и типы

Система типов GraphQL описывает, какие данные можно запросить у API. Совокупность этих возможностей называют схемой сервиса; по схеме клиенты составляют запросы и получают предсказуемые результаты.

В GraphQL шесть видов именованных типов: объектные типы, скаляры, перечисления, интерфейсы, объединения и входные типы. На этой странице разобраны объектные типы, скаляры, перечисления и модификаторы типов; интерфейсы, объединения и входные типы — на странице «Интерфейсы, объединения и входные типы». GraphQL можно использовать с любым backend-фреймворком и языком программирования, поэтому подробности реализации опущены — речь только о понятиях.

Система типов

Если вы уже видели запрос GraphQL, то знаете, что язык запросов — это, по сути, выбор полей у объектов. Например, в запросе:

{
  hero {
    name
    appearsIn
  }
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ]
    }
  }
}
  1. Мы начинаем со специального «корневого» объекта.
  2. Выбираем у него поле hero.
  3. У объекта, который вернуло 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
Booleantrue или false
IDУникальный идентификатор — часто для повторной загрузки объекта или как ключ кеша. Передаётся так же, как String, но тип ID показывает, что значение не предназначено для чтения человеком

В большинстве реализаций GraphQL можно объявить и свои скалярные типы. Например, тип Date:

scalar Date

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

Формат своего скаляра принято указывать встроенной директивой @specifiedBy: scalar DateTime @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time").

Перечисления

Перечисления (enum) — особый вид скаляра, значения которого ограничены заданным набором. Перечисление позволяет:

  1. проверять, что аргумент этого типа принимает одно из допустимых значений;
  2. сообщать через систему типов, что поле всегда возвращает одно значение из конечного набора.

Определение перечисления на 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 г.