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