Цель данной статьи - рассказать о 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 в сравнении с более знакомым RESTful API.
Что-то похоже на RESTful API… А в чем отличия?
Кажется, этим вопросом много кто задавался (например, тут: 1, 2 и 3).
Да и вообще на собеседованиях аналитиков вопрос: "Назовите отличия 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).
А еще тут можно выполнять 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, которое дала эта статья, вам еще пригодится и станет только отправной точкой в вашей работе с этими инструментами.
