GraphQL для платформ компании InterSystems


    GraphQL — это стандарт декларирования структур данных и способов получения данных, который выступает дополнительным слоем между клиентом и сервером. Если вы впервые слышите о GraphQL, то вот пара хороших ресурсов: раз и два.


    В этой статье я расскажу как вы можете использовать GraphQL в своих проектах на технологиях InterSystems.


    На данный момент на платформах компании InterSystems есть несколько способов создания клиент-серверных приложений:


    • REST
    • WebSocket
    • SOAP

    Но чем же так хорош GraphQL? Какие новые возможности он даст по сравнению, например, с REST?


    В GraphQL есть несколько типов запросов:


    • query — это запросы на сервер для получения данных, подобно тому как в REST для получения данных рекомендуется использовать GET запросы.
    • mutation — этот тип отвечает за изменение данных на сервере. В REST для изменения данных POST (PUT, DELETE) запросы.
      Mutations, как и query могут возвращать данные — это удобно если вы хотите запросить обновленную информацию с сервера сразу же после выполнения мутации.
    • subscriptions — это тот же тип query, который будет выводить данные. Единственное различие в том, что query запускается от рендеринга страницы на клиенте, а subscriptions от активации mutations.

    Главные особенности GraphQL и то, ради чего его стоит использовать


    Клиент сам решает, что он хочет получить


    Одной из основных особенностей GraphQL является то, что структура и объем данных определяется клиентским приложением. Клиент точно указывает, какие данные он хочет получить, используя декларативную, графо-подобную структуру, которая очень напоминает формат JSON. Структура ответа соответствует структуре запроса.


    Так выглядит простой GraphQL запрос:


    {
      Sample_Company {
        Name
      }
    }

    Ответ в формате JSON:


    {
      "data": {
        "Sample_Company": [
          {
            "Name": "CompuSoft Associates"
          },
          {
            "Name": "SynerTel Associates"
          },
          {
            "Name": "RoboGlomerate Media Inc."
          },
          {
            "Name": "QuantaTron Partners"
          }
        ]
      }
    }

    Единая точка входа


    В GraphQL для работы с данными мы всегда обращаемся к единой точке входа (endpoint) — GQL серверу. Изменяя структуру, поля, параметры запроса мы работаем с разными данными. У того же REST множество endpoint.


    Сравним REST c GraphQL на простом примере:



    Допустим нужно загрузить контент пользователя, для REST нужно сделать три запроса на сервер:


    1. Мы подгружаем данные пользователя по его id
    2. По id мы получаем его посты
    3. По id мы получаем его подписчиков

    REST карта, соответствующая этим запросам:


       <Route Url="/user/:id" Method="GET" Call="GetUserByID"/>
       <Route Url="/user/:id/posts" Method="GET" Call="GetUserPostsByID"/>
       <Route Url="/user/:id/follovers" Method="GET" Call="GetUserFolloversByID"/>

    Чтобы получить новый набор данных REST карту придется дополнить новыми endpoint.


    GraphQL же справляется с этой задачей за один запрос. Для этого необходимо в теле запроса указать следующее:


    {
    operationName: null,    //у query может быть имя ( query TestName(...){...} )
    query: "query {
           User(id: "ertg439frjw") {
            name
            posts {
               title
            }
            followers(last: 3) {
               name
            }
        }
    }",
    variables: null      // инициализация переменных, которые используются в query*
    }

    REST карта, соответствующая этому запросу:


       <Route Url="/graphql" Method="POST" Call="GraphQL"/>

    При том, это единственный endpoint на сервере.


    Установка GraphQL и GraphiQL


    Для того, чтобы начать пользоваться GraphQL необходимо проделать несколько шагов:


    1. Скачать последний релиз из GitHub и импортировать в нужную область
    2. Перейти в портал управления системой и создать новое веб приложение вашем из InterSystems Data Platform продукте (Caché, Ensemble или IRIS):
      • Имя — /
      • Область — например SAMPLES
      • Класс обработчик — GraphQL.REST.Main
    3. GraphiQL — это оболочка для тестирования GraphQL запросов. Скачать последний собранный релиз GraphiQL или же собрать самим
    4. Создать новое веб приложение:
      • Имя — /graphiql
      • Область — например SAMPLES
      • Физический путь к CSP файлам — C:\InterSystems\GraphiQL\

    Посмотрим на результат


    Перейдите в браузере по данной ссылке http://localhost:57772/graphiql/index.html (localhost — сервер, 57772 — порт)


    GraphiQL


    Думаю, с областью Запрос и Ответ все понятно, а Схема — это документация, которая генерируется по всем хранимым классам в области.


    Схема содержит:


    • Классы
    • Свойства, аргументы и их типы
    • Описание всего вышеперечисленного, которое генерируется из комментариев

    Рассмотрим схему на примере класса Sample_Company:



    Так же, GraphiQL поддерживает автодополнение, которое можно вызвать комбинацией клавиш Ctrl + Space:



    Запросы


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



    Фильтрация


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


    filter


    Пагинация


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


    • after: n – все записи у которых id больше n
    • before: n – все записи у которых id меньше n
    • first: n – первые n записей
    • last: n – последние n записей

    filters


    Область видимости


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


    • Все классы в области (GraphQL.Scope.All)
    • Классы, унаследованные от суперкласса (GraphQL.Scope.Superclass)
    • Классы, принадлежащие к определенному пакету (GraphQL.Scope.Package)

    Для изменения способа ограничения видимости необходимо открыть студию, перейти в нужную область и открыть класс GraphQL.Settings. В нем есть параметр SCOPECLASS, его значение по умолчанию установлено GraphQL.Scope.All — это класс, в котором описан интерфейс ограничения видимости классов в области:
    scope
    Для изменения ограничения видимости классов нужно просто установить одно из значений указанных выше, GraphQL.Scope.Package или GraphQL.Scope.Superclass.


    В случае с GraphQL.Scope.Package еще необходимо перейти в этот класс и установить значение параметра Package именем нужного пакета, например, Sample, тогда будут доступны все хранимые классы из этого пакета:



    А с GraphQL.Scope.Superclass просто дополнительно наследоваться от этого класса в нужных вам классах:



    На данный момент поддерживается


    Запросы:


    • Базовые
    • Вложенные объекты
      • Только отношение many to one
    • Лист из простых типов
    • Лист из объектов

    Находится в реализации


    Запросы:


    • Вложенные объекты
      • Поддержка отношений всех типов
    • фильтрация
      • Поддержка неравенств

    В планах



    Ссылка на репозиторий проекта
    Ссылка на демо-сервер


    Issues Pull Requests очень приветствуются.
    Следите за развитием нашего проекта!

    • +13
    • 2,9k
    • 6

    InterSystems

    95,90

    Вендор: СУБД Caché, OLAP DeepSee, шина Ensemble

    Поделиться публикацией

    Похожие публикации

    Комментарии 6
      0

      С постраничным выводом беда. Ни один из 4-х вариантов не покрывает самый распространенный кейс: вывести 10 эдементов на 10-й странице.


      Как быть с deprecated? Если пользователь сам решает, что выбирать, то как дать понять, что какое-то поле более не поддерживается?


      Существует ли аналог swagger для GraphQL?

        +3
        Грубо говоря GraphiQL и есть аналог Swagger-а. На скриншотах на самом деле немного устаревшая IDE, но тем не менее функционал остался прежним: GraphiQL на основе схемы, комментариев к полям и директив генерирует документацию, вот пример (см. кнопку «schema» справа).

        К слову, для обозначения depricated полей существует директива
        @depricated(reason: "Please use `somethingElse` field"))
          0
          Согласен с yuzi, всю необходимую информацию можно получить из схемы.
        0

        А как вы с GraphQL решаете проблему дублирования глубоко вложенных данных? Например есть соцсеть и нужно вывести список всех друзей друзей для юзера, например


        {
          user(1234) {
            friends {
              id, 
              firstName,
              lastName,
              friends {
                id, 
                firstName,
                lastName
             }
           }
        }

        то согласно graphql этот запрос будет формировать вложенный json в котором возможны очень много дублей юзеров (потому что много людей могут быть знакомы между собой), что выливается мегабайты json-а, траффик и медленную передачу и долгий парсинг на клиенте а также в лишние запросы в базу данных (за дублирующими данными). В то время как через rest можно гибко настроить правильный формат передачи данных чтобы избежания дублирования и лишних запросов в базу

            0

            В любом случае, при большом количестве данных, пока graphql проверит схему объекта, вы потеряете минимум секунду на ответе. У меня на сервере ответ генерировался в районе 200-300ms, а вот как он попадал в руки graphql (перед выдачей он проверяет типы и убирает лишние поля) — ответ задерживался на секунду. Использовал на nodejs, как и Apollo, так и поверх реализации graphql-yoga.


            А по поводу кэша. Я сначала Apollo Engine подключил (работает в режиме проксирования запросов), но в режиме cluster (несколько процессов ноды) он коряво как-то работал. На сервере данные стал кэшировать в Redis (тупо данные из mysql/postgresql), стало шустрее, чем с использованием Apollo Engine. Ну и временем жизни кэша и его обновлением управляют несколькими процессами.

          Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

          Самое читаемое