Документация / GraphQL
Интроспекция
Часто полезно спросить у схемы GraphQL, какие возможности она поддерживает. GraphQL позволяет это сделать с помощью системы интроспекции (introspection).
Запросы интроспекции — особые запросы, которые рассказывают о схеме API GraphQL; на них же работают инструменты разработки GraphQL. На этой странице разобраны запросы, которые выясняют типы схемы, их поля и описания.
Имя типа
Пример интроспекции уже встречался на странице «Интерфейсы, объединения и входные типы»:
при запросе поля, возвращающего объединение, в набор выбора добавлялось мета-поле __typename, чтобы получить
имена разных типов в результатах поиска. Вспомним этот пример:
query {
search(text: "an") {
__typename
... on Character {
name
}
... on Starship {
name
}
}
}
Ответ:
{
"data": {
"search": [
{
"__typename": "Human",
"name": "Han Solo"
},
{
"__typename": "Human",
"name": "Leia Organa"
},
{
"__typename": "Starship",
"name": "TIE Advanced x1"
}
]
}
}
Поле __typename мы не добавляли в API сами — спецификация требует, чтобы реализация GraphQL предоставляла его
клиентам. Его можно запросить у любого поля, выходной тип которого — объектный тип, интерфейс или объединение.
Интроспекция схемы
Интроспекция умеет больше, чем сообщать имена типов. Если вы проектировали систему типов API, то и так знаете,
какие типы есть. А если нет — спросите GraphQL полем __schema, оно всегда доступно в корневом типе query.
Спросим, какие типы есть в схеме Star Wars:
query {
__schema {
types {
name
}
}
}
Ответ:
{
"data": {
"__schema": {
"types": [
{
"name": "Query"
},
{
"name": "String"
},
{
"name": "ID"
},
{
"name": "Mutation"
},
{
"name": "Episode"
},
{
"name": "FilmRating"
},
{
"name": "Film"
},
{
"name": "Character"
},
{
"name": "Int"
},
{
"name": "LengthUnit"
},
{
"name": "Human"
},
{
"name": "Float"
},
{
"name": "Droid"
},
{
"name": "FriendsConnection"
},
{
"name": "FriendsEdge"
},
{
"name": "PageInfo"
},
{
"name": "Boolean"
},
{
"name": "Review"
},
{
"name": "ReviewInput"
},
{
"name": "Starship"
},
{
"name": "SearchResult"
},
{
"name": "__Schema"
},
{
"name": "__Type"
},
{
"name": "__TypeKind"
},
{
"name": "__Field"
},
{
"name": "__InputValue"
},
{
"name": "__EnumValue"
},
{
"name": "__Directive"
},
{
"name": "__DirectiveLocation"
}
]
}
}
}
Сколько типов! Что это за типы? Сгруппируем их:
- типы, которые мы определили в системе типов:
Query,Mutation,Character,Human,Episode,Droid,LengthUnit,FriendsConnection,FriendsEdge,PageInfo,Review,ReviewInput,StarshipиSearchResult(а такжеFilmиFilmRating); - встроенные скаляры системы типов:
Boolean,Float,ID,IntиString; - типы с двойным подчёркиванием в начале — часть системы интроспекции:
__Schema,__Type,__TypeKind,__Field,__InputValue,__EnumValue,__Directiveи__DirectiveLocation.
Теперь найдём, с чего начать изучение доступных запросов. При проектировании системы типов мы указали, с какого типа начинаются все запросы; спросим об этом систему интроспекции:
query {
__schema {
queryType {
name
}
}
}
Ответ:
{
"data": {
"__schema": {
"queryType": {
"name": "Query"
}
}
}
}
Результат совпадает со сказанным на странице «Схема и типы»: запросы
начинаются с типа Query. Имя здесь — лишь соглашение: тип можно было назвать как угодно, и интроспекция всё
равно вернула бы его, если бы он был указан начальным типом запросов. Но называть его Query удобно.
Часто полезно изучить один конкретный тип. Посмотрим на Droid:
query {
__type(name: "Droid") {
name
}
}
Ответ:
{
"data": {
"__type": {
"name": "Droid"
}
}
}
А если нужно больше сведений о Droid? Например, это интерфейс или объектный тип?
query {
__type(name: "Droid") {
name
kind
}
}
Ответ:
{
"data": {
"__type": {
"name": "Droid",
"kind": "OBJECT"
}
}
}
Поле kind возвращает перечисление __TypeKind, одно из значений которого — OBJECT. Если спросить о
Character, окажется, что это интерфейс:
query {
__type(name: "Character") {
name
kind
}
}
Ответ:
{
"data": {
"__type": {
"name": "Character",
"kind": "INTERFACE"
}
}
}
Для объектного типа важно знать, какие у него поля, — спросим систему интроспекции о полях Droid:
query {
__type(name: "Droid") {
name
fields {
name
type {
name
kind
}
}
}
}
Ответ:
{
"data": {
"__type": {
"name": "Droid",
"fields": [
{
"name": "id",
"type": {
"name": null,
"kind": "NON_NULL"
}
},
{
"name": "name",
"type": {
"name": null,
"kind": "NON_NULL"
}
},
{
"name": "friends",
"type": {
"name": null,
"kind": "LIST"
}
},
{
"name": "friendsConnection",
"type": {
"name": null,
"kind": "NON_NULL"
}
},
{
"name": "appearsIn",
"type": {
"name": null,
"kind": "NON_NULL"
}
},
{
"name": "primaryFunction",
"type": {
"name": "String",
"kind": "SCALAR"
}
}
]
}
}
}
Это поля, которые мы определили у Droid!
С id что-то странное: у его типа нет имени. Дело в том, что это тип-обёртка вида NON_NULL. Если запросить
у типа этого поля ofType, там окажется тип ID — то есть это обязательный идентификатор.
Так же нет имени у friends и appearsIn: это обёртки вида LIST. Запросив у них ofType, узнаем, какие типы
внутри списков:
query {
__type(name: "Droid") {
name
fields {
name
type {
name
kind
ofType {
name
kind
}
}
}
}
}
Ответ:
{
"data": {
"__type": {
"name": "Droid",
"fields": [
{
"name": "id",
"type": {
"name": null,
"kind": "NON_NULL",
"ofType": {
"name": "ID",
"kind": "SCALAR"
}
}
},
{
"name": "name",
"type": {
"name": null,
"kind": "NON_NULL",
"ofType": {
"name": "String",
"kind": "SCALAR"
}
}
},
{
"name": "friends",
"type": {
"name": null,
"kind": "LIST",
"ofType": {
"name": "Character",
"kind": "INTERFACE"
}
}
},
{
"name": "friendsConnection",
"type": {
"name": null,
"kind": "NON_NULL",
"ofType": {
"name": "FriendsConnection",
"kind": "OBJECT"
}
}
},
{
"name": "appearsIn",
"type": {
"name": null,
"kind": "NON_NULL",
"ofType": {
"name": null,
"kind": "LIST"
}
}
},
{
"name": "primaryFunction",
"type": {
"name": "String",
"kind": "SCALAR",
"ofType": null
}
}
]
}
}
}
Закончим возможностью системы интроспекции, особенно полезной для инструментов, — спросим документацию:
query {
__type(name: "Droid") {
name
description
}
}
Ответ:
{
"data": {
"__type": {
"name": "Droid",
"description": "An autonomous mechanical character in the Star Wars universe"
}
}
}
Как видно, через интроспекцию доступна документация системы типов — на ней строят обозреватели документации и удобные среды разработки.
Это лишь малая часть системы интроспекции: можно запросить значения перечислений, интерфейсы, которые реализует тип, и многое другое. Можно даже применить интроспекцию к самой системе интроспекции.
Пример системы интроспекции по спецификации в коде — файл src/type/introspection.ts эталонной реализации.
Результат introspection в редакторе
Полный запрос интроспекции (его отправляют GraphiQL, Postman, генераторы кода) возвращает всю схему в JSON —
ответ вида {"data": {"__schema": {…}}}. Вставьте такой ответ в редактор GraphQL «Помощника SA» вместо SDL:
редактор распознает формат, покажет карту типов и позволит скачать схему в SDL (Файл → Скачать → GraphQL SDL).
И наоборот, из SDL можно выгрузить результат introspection в JSON.
Интроспекция в боевой среде
Интроспекция полезна разработчикам клиентов и инструментам. Но API, предназначенному только для ваших приложений, в боевой среде она обычно не нужна: нужные операции встраиваются в приложения при сборке, и интроспекция во время работы не требуется.
Чтобы уменьшить поверхность атаки API, интроспекцию в боевой среде часто отключают. Обычно это часть более широкой стратегии безопасности API: аутентификация и авторизация, белый список операций (или альтернативные меры защиты: ограничение глубины и ширины запросов, числа псевдонимов, запрет циклов, анализ стоимости и т. п.), таймауты выполнения и другое.
Итоги
Подведём итоги об интроспекции:
- имя типа можно запросить в наборе выбора объектного типа, интерфейса или объединения мета-полем
__typename; - сведения об элементах схемы GraphQL запрашиваются полем
__schemaкорневого типаquery; - в боевой среде интроспекцию часто отключают.
Вы изучили систему типов GraphQL, запросы данных у API и жизненный цикл запроса. Дальше — практики: пагинация, глобальная идентификация объектов и рекомендации по проектированию схемы.
Похожие инструменты
Обновлено: 17 октября 2026 г.
