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