Словарь GraphQL 101

GraphQL только входит в массовую индустрию как новый стандарт выборки данных. Сейчас ведется много замечательных разговоров о разработках в области технологий и новых инструментов, которые создаются каждый день. Одна из лучших частей GraphQL - это то, что он дает вам отличный общий язык с вашей командой для обсуждения данных, доступных в вашем API. Но как говорить о языке запросов и самой базовой технологии?

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

Примечание. Если вы пытаетесь изучить GraphQL, это не лучшее место для начала. Сначала прочтите концепции в документации graphql.org, затем попробуйте использовать GraphQL с превосходным Учебником по изучению Apollo и, наконец, вернитесь сюда, когда захотите углубиться в технический язык.

Базовые запросы GraphQL

Люди обычно называют все, что попадает на ваш сервер GraphQL API, «запросом». Но там много чего смешано. Что мы называем единицей работы, которую мы просим сделать у сервера? Это может быть запрос, изменение или подписка. Слово «запрос» тесно связано с идеей HTTP и транспорта. Итак, давайте начнем с определения некоторых общих понятий:

  • Документ GraphQL. Строка, написанная на языке GraphQL, которая определяет одну или несколько операций и фрагментов.
  • Операция: отдельный запрос, изменение или подписка, которые могут быть интерпретированы механизмом выполнения GraphQL.

Каковы различные части базовой операции? Давайте посмотрим на очень простой пример документа GraphQL.

В этом документе показаны основные строительные блоки GraphQL, которые определяют данные, которые вы пытаетесь получить.

  • Поле: запрашиваемая единица данных, которая заканчивается полем в данных вашего ответа JSON. Обратите внимание, что они всегда называются «полями», независимо от того, насколько глубоко в запросе они появляются. Поле в корне вашей операции работает так же, как поле, вложенное глубже в запрос.
  • Аргументы: набор пар "ключ-значение", привязанных к определенному полю. Они передаются при выполнении этого поля на стороне сервера и влияют на его разрешение. Аргументы могут быть буквальными значениями, как в запросе выше, или переменными, как в примерах ниже. Обратите внимание, что аргументы могут появляться в любом поле, даже в полях, глубоко вложенных в операцию.

Вышеупомянутый запрос является чем-то вроде сокращенной формы GraphQL, которая позволяет очень кратко определять операцию запроса. Но есть три необязательных части операции GraphQL, которые там не используются. Эти новые части понадобятся вам, если вы хотите выполнить что-то, кроме запроса, или передать динамические переменные.

Вот пример, который включает их все:

  • Тип операции: это либо запрос, изменение, или подписка. Он описывает, какой тип операции вы пытаетесь выполнить. Хотя все они выглядят одинаково на языке, они имеют несколько разные режимы выполнения на сервере GraphQL, соответствующем спецификации.
  • Название операции. Для отладки и ведения журнала на стороне сервера полезно давать вашим запросам понятные имена. Таким образом, когда вы видите, что что-то не так, либо в ваших сетевых журналах, либо на вашем сервере GraphQL (например, в таком инструменте, как Apollo Optics), вы можете легко найти этот запрос в своей кодовой базе по имени, вместо того, чтобы пытаться расшифровать содержимое. . Думайте об этом как об имени функции на вашем любимом языке программирования.
  • Определения переменных. Когда вы отправляете запрос на сервер GraphQL, у вас могут быть некоторые динамические части, которые меняются между запросами, в то время как фактический документ запроса остается неизменным. Это переменные вашего запроса. Поскольку GraphQL имеет статическую типизацию, он действительно может подтвердить, что вы передаете правильные переменные. Здесь вы объявляете типы переменных, которые планируете предоставить.

Переменные передаются отдельно от документа запроса специфичным для транспорта способом. В современных реализациях сервера GraphQL это обычно JSON. Вот как объект переменных может выглядеть в соответствии с приведенным выше запросом:

Вы можете видеть, что ключ здесь соответствует имени переменной, определенной в определениях переменных, и это имя является одним из членов перечисления Episode.

  • Переменные: словарь значений, передаваемых вместе с операцией GraphQL, который предоставляет динамические параметры этой операции.

Есть еще одна основная концепция, которую не часто называют, но она важна, когда речь идет о GraphQL в техническом смысле: что это за фигня в скобках?

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

  • Набор выбора: набор полей, запрошенных в операции или вложенных в другое поле. Запрос GraphQL должен содержать набор выбора для любого поля, которое возвращает тип объекта, а наборы выбора не допускаются для полей, возвращающих скалярные типы, такие как Int или String.

Фрагменты

GraphQL становится еще более мощным, когда вы вводите фрагменты. Они приносят с собой новый набор концепций.

  • Определение фрагмента. Часть документа GraphQL, определяющая фрагмент GraphQL. Его также иногда называют именованным фрагментом, в отличие от встроенного фрагмента, о котором мы поговорим ниже.

  • Имя фрагмента. Имя каждого фрагмента должно быть уникальным в документе GraphQL. Это имя, которое вы используете для ссылки на фрагмент в операции или в других фрагментах. Имена фрагментов также могут быть полезны для ведения журнала на стороне сервера, как и имена операций, поэтому мы рекомендуем использовать явные и значимые имена. Если вы правильно назовете свои фрагменты, вы сможете отследить, какая часть вашего кода определяет этот фрагмент, если вы хотите оптимизировать получение данных позже.
  • Условие типа: операции GraphQL всегда начинаются с типа запроса, изменения или подписки в вашей схеме, но фрагменты можно использовать в любом наборе выбора. Итак, чтобы проверить фрагмент на соответствие вашей схеме изолированно, вам необходимо указать, для какого типа он может использоваться, и именно здесь возникает условие типа.

И, как и операции, у фрагментов есть набор выбора. Они работают так же, как наборы выбора в операциях.

Использование фрагментов в ваших операциях

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

  • Распространение фрагмента. Когда вы используете фрагмент внутри операции или другого фрагмента, вы делаете это, помещая ..., за которым следует имя фрагмента. Это называется разворотом фрагмента и может появиться в любом наборе выбора, который соответствует условию типа указанного фрагмента.
  • Встроенный фрагмент: если вы просто хотите выполнить некоторые поля в зависимости от типа результата, но не хотите разделять это на отдельное определение, вы можете использовать встроенный фрагмент . Это работает так же, как именованный фрагмент, но записывается как часть вашего запроса. Одно из отличий встроенных фрагментов заключается в том, что они не обязательно должны иметь условие типа и могут использоваться только с директивой, как мы увидим в примере ниже.

Директивы

Директивы - это способ получить дополнительную функциональность от вашего сервера GraphQL. Директивы не должны влиять на ценность результатов, но влияют на то, какие результаты возвращаются и, возможно, на то, как они выполняются. Они могут появляться практически в любом месте запроса, но в этой статье мы сосредоточимся только на директивах skip и include, которые есть в текущей спецификации GraphQL.

Выше показаны примеры использования директив skip и include для кухонной мойки. Эти директивы, в частности, заставляют выполнение GraphQL условно пропускать поля и исключать их из ответа. Поскольку синтаксис директив довольно гибкий, их можно использовать для добавления дополнительных функций в GraphQL, не усложняя синтаксический анализ или инструменты.

  • Директива: аннотация к полю, фрагменту или операции, которая влияет на то, как они выполняются или возвращаются.
  • Аргументы директивы. Они работают так же, как аргументы поля, но обрабатываются механизмом выполнения, а не передаются преобразователю полей.

Участвуйте в разговоре

Большая часть преимущества GraphQL заключается в наличии общего языка для обсуждения выборки данных. Теперь у вас будет все необходимое для участия в глубоких технических обсуждениях GraphQL, например, в продолжающемся обсуждении подписок GraphQL.

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

Хотите работать над технологией GraphQL на постоянной основе? Мы нанимаем на разные должности, в том числе на фронтенд, бэкэнд и с открытым исходным кодом!