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

Директивы и документирование

Директивы

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

Директивы системы типов размечают типы, поля и аргументы схемы, чтобы те проверялись или выполнялись иначе.

Директивы бывают и исполняемыми — их используют в операциях GraphQL. О них — на странице «Запросы».

Спецификация GraphQL определяет несколько встроенных директив. Например, в реализациях с поддержкой SDL доступна директива @deprecated — ею помечают устаревшие части схемы:

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

Объявлять @deprecated в схеме самому не нужно, если реализация GraphQL поддерживает SDL; её определение выглядит так:

directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE

Как и поля, директивы принимают аргументы, а у аргументов бывают значения по умолчанию. У @deprecated есть необязательный аргумент reason типа String со значением по умолчанию "No longer supported". Кроме того, для директивы указывают, где её можно применять: у @deprecated — FIELD_DEFINITION и ENUM_VALUE.

В актуальной спецификации @deprecated можно ставить также на аргументы и поля входных типов (ARGUMENT_DEFINITION, INPUT_FIELD_DEFINITION).

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

Встроенные директивы

ДирективаГде применяетсяНазначение
@deprecated(reason: "…")Поле, значение перечисления, аргумент, поле входного типаЭлемент устарел: инструменты клиентов предупреждают о нём
@specifiedBy(url: "…")СкалярСсылка на спецификацию формата своего скаляра
@oneOfВходной типДолжно быть задано ровно одно поле (новая версия спецификации)
@include(if:), @skip(if:)Поле или фрагмент в операцииУсловное включение — в запросах, не в схеме

Устаревшие поля на карте схемы зачёркнуты; галочка «Скрыть устаревшие поля» в панели «Описание» убирает их совсем.

Свои директивы

Директива объявляется с аргументами и списком мест, где её можно применять:

"Поле доступно только пользователям с ролью"
directive @auth(role: Role!) on FIELD_DEFINITION | OBJECT

enum Role {
  CUSTOMER
  MANAGER
}

type Report @auth(role: MANAGER) {
  revenue: Float!
}

type Query {
  report: Report @auth(role: MANAGER)
}

Смысл своих директив задаёт сервер: проверка прав, кеширование, федерация. Неизвестная директива или директива не на своём месте — ошибка схемы.

Документирование

Описания

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

На SDL это выглядит так:

"""
Персонаж вселенной «Звёздных войн»
"""
type Character {
  "Имя персонажа."
  name: String!
}

"""
Эпизоды трилогии «Звёздные войны»
"""
enum Episode {
  "Эпизод IV: Новая надежда, 1977 год."
  NEWHOPE
  "Эпизод V: Империя наносит ответный удар, 1980 год."
  EMPIRE
  "Эпизод VI: Возвращение джедая, 1983 год."
  JEDI
}

"""
Тип запросов — все точки входа в граф объектов
"""
type Query {
  """
  Герой выбранного фильма «Звёздных войн».
  """
  hero(
    "Фильм, в котором появляется герой."
    episode: Episode
  ): Character
}

Описания делают схему выразительнее и помогают разработчикам клиентов: они доступны в запросах introspection и видны в инструментах разработчика вроде GraphiQL.

В редакторе описание типа показывается в панели «Описание», а описание поля — во всплывающей подсказке над строкой поля на карте.

Комментарии

Иногда в схему нужно добавить комментарии, которые не описывают типы, поля и аргументы и не предназначены для клиентов. Однострочный комментарий в SDL начинается с символа #:

# Эта строка считается пробелом и игнорируется GraphQL
type Character {
  name: String!
}

Комментарии можно добавлять и в запросы клиентов:

{
  hero {
    name
    # В запросах можно писать комментарии!
    friends {
      name
    }
  }
}

Ответ:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

Расширения типов

Ключевое слово extend добавляет поля, интерфейсы или директивы к уже объявленному типу. Так большую схему делят на части по модулям — каждый модуль дополняет Query своими полями:

type Review {
  stars: Int!
  commentary: String
}

type Query {
  review(id: ID!): Review
}

# Отзывы — отдельный модуль схемы
extend type Query {
  reviews(minStars: Int = 1): [Review!]!
}

Итоги

Подведём итоги о схемах и типах:

  • в зависимости от библиотеки сервиса GraphQL схему описывают на независимом от языка SDL или собирают из кода, который возвращает данные полей;
  • в GraphQL шесть видов именованных типов: объектные типы, скаляры, перечисления, интерфейсы, объединения и входные типы;
  • у объектных типов есть поля с выходными типами, а у полей — аргументы с входными типами;
  • скаляры Int, Float, String, Boolean и ID встроены в GraphQL, можно определить и свои;
  • перечисления, как и скаляры, — листья схемы, но их значения ограничены конечным набором;
  • модификаторы списка ([]) и обязательности (!) меняют поведение выходного типа поля или входного типа аргумента;
  • интерфейсы и объединения — абстрактные типы: одно поле может вернуть объекты разных конкретных типов;
  • входные типы позволяют передать в аргумент поля или директивы значения сложнее скаляров и перечислений;
  • директивы системы типов размечают типы, поля и аргументы схемы и меняют их проверку и выполнение;
  • GraphQL поддерживает документирование схемы описаниями типов, полей и аргументов, а также комментарии, которые парсер игнорирует.

Теперь, зная основы системы типов, переходите к тому, как запрашивать данные у API GraphQL.

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