Зачем нужны запросы самоанализа в GraphQL?

Development | Amber | Комментировать запись

Как известно, система типизации GraphQL отличается своей строгостью, благодаря чему GraphQL может поддерживать систему самоанализа (или интроспекции). Интроспекция GraphQL – это встроенная возможность обнаруживать ресурсы, доступные в схеме GraphQL. Проще говоря, с помощью запросов самоанализа вы можете узнать о доступных полях и типах схемы GraphQL. Эта возможность также помогает GraphiQL собирать документацию о схеме и поддерживает автозаполнение. Система интроспекции имеет множество применений, некоторые из них мы рассмотрим ниже.

Итак, в данном мануале мы поговорим о запросах самоанализа GraphiQL. Для выполнения примеров мы воспользуемся конечной точкой публичного SWAPI API от Star Wars.

Запросы __type

Сначала давайте запустим встроенный запрос __type, с помощью которого мы узнаем тип Film:

query FilmType {
  __type(name: "Film") {
    kind
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}

Рассмотрим этот пример подробнее:

• kind предоставляет нам значение enum для типа (например, OBJECT, SCALAR или INTERFACE).
• name определяет имя типа.
• description предоставляет описание.

Ответ на данный запрос будет выглядеть так:

{
  "data": {
    "__type": {
      "kind": "OBJECT",
      "name": "Film",
      "fields": [
        {
          "name": "title",
          "description": "The title of this film.",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "episodeID",
          "description": "The episode number of this film.",
          "type": {
            "name": "Int"
          }
        },
        ...

Обратите внимание на использование встроенного __type: здесь с его помощью мы получаем информацию о типе конкретного объекта или интерфейса.

Давайте взглянем на еще один пример, в котором мы попробуем получить больше информации об определенном типе:

query LearnAboutFilm {
  __type(name: "Film") {
    ...AboutType
  }
}

fragment AboutType on __Type {
  fields {
    name
    description
    args {
      name
      description
    }
  }
  interfaces {
    name
    description
  }
  inputFields {
    name
    description
  }
  possibleTypes {
    kind
    name
    fields {
      name
      description
      type {
        kind
        name
        description
      }
    }
  }
}

Запрос __schema

С помощью запроса __schema мы можем извлечь информацию о самой схеме. Давайте посмотрим на такой пример запроса:

query LearnAboutSchema {
  __schema {
    types {
      name
      kind
    }
    queryType {
      fields {
        name
        description
      }
    }
  }
}

Этот запрос выведет на экран следующий ответ:

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "Root",
          "kind": "OBJECT"
        },
        {
          "name": "String",
          "kind": "SCALAR"
        },
        {
          "name": "Int",
          "kind": "SCALAR"
        },
        ...
        "queryType": {
        "fields": [
          {
            "name": "allFilms",
            "description": null
          },
          {
            "name": "film",
            "description": null
          },
          ...

Запрос __typename

Запросы __typename можно использовать как часть обычных запросов, чтобы узнать тип конкретного поля. Например:

query LearnAboutFilm {
  allFilms {
    films {
      __typename
      title
    }
  }
  film (id: "ZmlsbXM6Mw==") {
    __typename
    title
  }
  starship(id: "c3RhcnNoaXBzOjc1") {
    __typename
    name
    model
  }
}

Ответ на данный запрос выглядит следующим образом:

{
  "data": {
    "allFilms": {
      "films": [
        {
          "__typename": "Film",
          "title": "A New Hope"
        },
        {
          "__typename": "Film",
          "title": "The Empire Strikes Back"
        },
        ...
      ]
    },
    "film": {
      "__typename": "Film",
      "title": "Return of the Jedi"
    },
    "starship": {
      "__typename": "Starship",
      "name": "V-wing",
      "model": "Alpha-3 Nimbus-class V-wing starfighter"
    }
  }
}

Заключение

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

Читайте также: Введение в GraphQL: преимущества и недостатки