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

Я аналитик, который сам недавно оказался в ситуации первого типа (вообще не слышал ничего о GraphQL и Hasura, каюсь), поэтому статья не претендует на глубокое погружение в тему и нацелена скорее на аналитиков и тестировщиков, которые не работали с упомянутыми инструментами.

Теперь всё, переходим к контенту с чистой совестью.


Что такое GraphQL?

По данным https://graphql.org/, GraphQL - это язык запросов к API и open-source среда для их выполнения. Изначально разработан Facebook как внутренний проект, внешний stable-релиз значится июнем 2018 года.

Язык GraphQL позволяет отправлять HTTP-запросы и получать на них ответы в виде объектов JSON. Тут есть важное уточнение, что все типы запросов GraphQL отправляются через POST. При этом есть следующие типы запросов:

  • query (аналог GET в REST);

  • mutation (аналог POST и PUT в REST);

  • subscription.

Подробнее мы рассмотрим сигнатуры запросов query и mutation далее в практическом блоке.

Как заверяет сайт GraphQL, GraphQL может использоваться с любым backend-фреймворком или языком программирования. Логично предположить, что в таком случае для запросов используется какая-то универсальная система типов самого GraphQL. Так и есть: у GraphQL своя система типов, которая позволяет описывать схемы API в синтаксе Schema Definition Language (SDL).

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

Бытует мнение, что GraphQL - это следующий, принципиально новый этап развития API относительно REST.

GraphQL, возможно новый этап развития API
GraphQL, возможно новый этап развития API

Поэтому было бы нечестно даже в общем и кратком обзоре упустить такой момент и не рассмотреть GraphQL в сравнении с более знакомым RESTful API.

Что-то похоже на RESTful API… А в чем отличия?

Кажется, этим вопросом много кто задавался (например, тут: 1, 2 и 3).

Количество запросов "graphql vs rest" на 09.08.2021 г.
Количество запросов "graphql vs rest" на 09.08.2021 г.

Да и вообще на собеседованиях аналитиков вопрос: "Назовите отличия REST от SOAP", на мой взгляд, задается так часто, что должен уже получить какое-нибудь развитие. Например, "Назовите отличия REST, SOAP и GraphQL друг от друга".

В данной статье я не ставлю перед собой задачу показать сравнение GraphQL с SOAP и остановлюсь на более популярном сравнении GraphQL с REST по чисто личным причинам: с RESTful API мне приходилось больше работать, он явно ближе моему сердцу ????.

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

REST

GraphQL

Термин

Архитектурный стиль, сам по себе не стандартизирован, но, как мы знаем, чаще всего использует стандарты JSON, и XML.

Язык программирования (выполнения запросов) и среда его выполнения. Обычно формат запросов при этом тоже использует стандарт JSON, но это не является обязательным.

Протокол передачи данных

HTTP, использует множественные точки входа (/users/add_contact, /users/change_password, etc.) в виде URL.

Тоже HTTP, но при этом обычно используется одна точка входа, то есть, например, одним запросом мы можем получить данные из разных источников. На мой взгляд, это полезно, если у вас несколько БД с разными данными (клиенты, счета, товары) и вам нужен ответ определенного формата - вместо нескольких запросов получения и трансформации данных это можно сделать в один шаг.

Типы запросов

Основные методы: POST, DELETE, PUT, GET.

query (аналог get), mutation (в источниках приводится как явный аналог post и put, но, насколько я понимаю, это также аналог update и delete) и subscription. Третий тип запросов звучит наиболее необычно относительно REST: subscriptions - это длительные операции, которые могут менять свой результат с течением времени. Могут реализовываться через WebSocket для поддержки активного соединения и передачи изменений в режиме реального времени от бэкенда. Механика таких запросов похожа на push-уведомления.

О’кей, мы более-менее разобрались, что такое GraphQL. А как с ним работать?

Основной список сервисов, которые помогают работать с GraphQL, лежит тут. В нем значится и такой инструмент, как Hasura.

Рассмотрим его чуть подробнее.

Что такое Hasura?

Hasura GraphQL Engine - это open-source веб-сервер приложений, который при подключении в БД PostgreSQL дает production-ready GraphQL API.

То есть, например, подключив Hasura к уже существующей БД, к ней сразу же с момента настройки можно будет выполнять запросы GraphQL для получения или изменения данных. Бизнес-логику при этом можно реализовать с помощью триггеров на события, REST APIs, отдельный сервис GraphQL API или же хранимые процедуры.

Для меня как для пользователя, который использует Hasura для тестирования, тут важны две простые вещи:

  • через нее можно делать запросы к БД;

  • через нее можно выполнять GraphQL-запросы.

Перейдем к практической части: посмотрим, где и как можно выполнять запросы к БД и собственно GraphQL-запросы.

Примеры запросов GraphQL через Hasura

Запросы GraphQL можно выполнять в разделе API:

Тут всё просто: выполняем запросы в консоли (там, где у нас закомментировано милое приветствие в GraphQL) и справа получаем результат выполнения запроса.

Доступ к данным подключенной БД получаем в разделе Data. Тут можно просмотреть данные таблиц через графический редактор, отредактировать их, удалить и так далее. Для этого достаточно выбрать нужную таблицу и нужный тип операции (как в знакомых мне pgAdmin, DataGrip и DBeaver, через которые я работала с PostgreSQL).

Источник картинки - https://cxlabs.sap.com/2020/07/01/exploring-the-hasura-open-source-graphql-engine/
Источник картинки - https://cxlabs.sap.com/2020/07/01/exploring-the-hasura-open-source-graphql-engine/

А еще тут можно выполнять SQL запросы в raw SQL:

Queries

Если нам нужно получить данные, в консоль Hasura (см. картинку выше) можно написать запрос в формате:

{
  user {
    login
  }
}

Этим запросом мы получим логин пользователя из подключенной БД, например:

{
  "data": {
    "user": {
      "login": "ivanovmp"
    }
  }
}

Чаще всего, конечно, мы либо запрашиваем данные какой-то конкретной записи, объекта или же массив объектов. Для запроса конкретной записи или записей параметры запроса можем указать так:

{
  users(name: "marina", status: "active") {
    email
    login
  }
}

Также для запроса можно указать limit и orderby по аналогии с SQL-запросами. Подробнее можно почитать тут и тут.

Результат запроса выше может быть таким:

{
  "data": {
	    "users": [
	        {
						"email": "marinaivanova@aaa.ru",
						"login": "ivanovama"
					},
	        {
						"email": "mar88af@33.ru",
						"login": "kirinovamp"
					}
	    ]
	}
}

Mutations

Этот тип запросов реализует подходы более знакомых из RESTful APIs методов POST и DELETE.

В mutations также можно передавать параметры. Выше был приведен пример с явной передачей параметров, но их можно указать еще и в виде переменных, например, $name и $status из примера выше.

Запрос на удаление может выглядеть так:

mutation deleteUser($filter: UserFilter!) {
  deleteUser(filter: $filter) {
    user {
      email
      login
    }
  }
}
#### далее привожу значение фильтра, который можно указать
{ 
	"filter":
  { 
		"status": "inactive" 
	}
}

В результате операции мы получим список удаленных клиентов:

{
  "data": 
		{
		    "users": [
		        {
							"email": "sdfa@aaa.ru",
							"login": "sdfa"
						},
		        {
							"email": "pertaf@33.ru",
							"login": "pertaf"
						}
		    ]
		}
}

Запрос на изменение, который в RESTful API мы могли бы передать через POST, в GraphQL тоже выполним через mutation c указанием параметров:

mutation {
         updateUser ( userId:1, email: "merkuloba@pp.com", login: "merkulovba")
         ##устанавливаем для пользователя 1 email и login из параметров
         {
            id
            email
            login
         }
}

В результате запроса получим измененные данные пользователя:

{
  "data": {
    {
      "id": 1,
      "email": "merkuloba@pp.com",
      "login": "merkulovba"
    }
}

Заключение

В статье мы рассмотрели GraphQL API в сравнении с, возможно, более знакомым RESTful API и немного узнали о том, как использовать консоль Hasura при работе с GraphQL API.

По некоторым данным, только за последний год использование проекта GraphQL выросло на 60%:

Проект растет и развивается, что подтверждается и активностью проекта на гите. На примере репозитория с документацией:

Поэтому надеюсь, что начальное представление о GraphQL и Hasura, которое дала эта статья, вам еще пригодится и станет только отправной точкой в вашей работе с этими инструментами.

Комментарии (3)


  1. denisromanenko
    15.09.2021 18:31

    Еще можно рассмотреть Postgraphile


    1. Annnik Автор
      15.09.2021 18:41

      Спасибо, почитаю про него


    1. vaboretti
      21.09.2021 12:41

      Мы пользовались postgraphile, но в итоге переписали все на hasura, и в нескольких других проектах используем тоже hasura. Postgraphile сложно поддерживать и писать, нет миграций и админки – все это достаточно весомые аргументы, чтобы никогда больше не пользоваться postgraphile.

      Наш low-code metrics store на основе Hasura https://github.com/mlcraft-io/mlcraft