Создаем свое modx.pro API на GraphQL

Всем привет!

Поддержу возникший марафон и напишу свою заметку в раздел «Для разработчиков». Думаю, многим понравится, тем более что тестовые примеры будут касаться в том числе и самого сайта modx.pro. И хотя будет много буков написано и самое основное не сразу будет показано, все-таки попрошу набраться терпения и если вы не сильны в GraphQL, то прочитать внимательно все с самого начала и по возможности повторить тоже самое самостоятельно. Просто я буду описывать практически с самых основ, и хотя во многом все покажется и окажется просто, данный материал будет очень полезен для дальнейшего самостоятельного освоения GraphQL.

Итак, быстрый старт. Вот мой демо-интерфейс: s19387.h10.modhost.pro:4123/
Можете сразу вставить вот такой листинг запросов:

query foo_string{
  foo_string
}

query foo_number{
  foo_number
}

query foo_json{
  foo_json
}

mutation calc_sum{
  calc_sum (
    vars: [2,4, 34.5, 5]
  )
}

Это три запроса «на чтение» (Query) и один на «изменение» (Mutation). На самом деле «чтение» и «изменение» в graphql — весьма условно, потому что реально решаться что будет просто прочтено, а что изменено — это уже будет на уровне функций-резолверов, о которых сам graphql мало что знает и его не сильно касается что там будет происходить (просто чтение или запись), но все-таки принято разделять эти типы операций, тем более что можно отдельно указать адрес для выполнения Query-запросов, и отдельно для Mutation. И вроде как там какая-то особенность с очередностью выполнения запросов при передаче сразу нескольких подзапросов внутри одного, например так:

query all_query{
foo_string
foo_number
foo_json
}

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

Ну как? Попробовали выполнить запросы? Если да и готовы продолжать дальше, то давайте разберем уже более внимательно что и как тут работает. Перейдем непосредственно к установке.

Для начала по хостингу: методом проб и ошибок я установил, что modhost.pro/ в общих чертах подходит для экспериментов, хотя на тестовом тарифном плане не получится (хотя в официальной тарифной сетке указано 250 метров диска будет доступно, на практике чуть больше ста, и запись на диск прерывалась (80 метров в кеш npm и финита ля комедия)). Но на минимальном тарифном плане за 75 рэ в месяц все полетело нормально. Хотя предполагаю, что эта лавочка может прикрыться, потому что нода сама по себе требует много ресурсов (та же установка всех зависимостей требует порядка гигабайта оперативки, и это в среднем в течение минуты). На сервере, который мне выделился, сейчас 10 Гб оперативы свободно. Если 10 человек одновременно запустит установку зависимостей, сервер заплачет. То есть хотя на php-процессы и есть лимиты, на нод-процессы я лимитов не увидел. Так что у кого есть возможность тестировать на своем железе, просьба: лучше там (хоть локально). Но если альтернативы нет, то наверно можно и там.

1. Заходим по ssh на сервер. создаем себе где-нибудь папку для проекта и клонируем туда мой репозиторий.

git clone https://github.com/Fi1osof/api.modx.pro

2. Переходим в папку скаченного репозитория и выполняем установку зависимостей.

npm i

3. Выполняем сборку API-схемы.

npm run build-api

4. Запускаем API-сервер.

PORT=4xxx npm run start

Вот тут уточнение: есть предположение, что порты на сервере для всех едины (там же вроде как просто разграничение прав по пользователям идет, а не просто каждому своя виртуальная машина), так что если порт кем-то занят уже, вы не сможете на нем запуститься. Поэтому прописывайте какой-нить рандомный порт в диапазоне 4000-4999, например 4156, 4589 и т.п. То есть если пытаетесь запуститься и получаете ошибку занятости порта, просто попробуйте другой.

Все. Если все ОК, то открываете адрес вашего сайта/сервера с указанием своего порта. У меня порт 4123, соответственно адрес s19387.h10.modhost.pro:4123/

5. Запускаем API-сервер постоянный процесс.
Если вы закроете терминал, в котором запускали сервер, то и сервер завершит свою работу. Поэтому, если мы хотим, чтобы сервер работал постоянно (а в случае, если развалится по какой-то причине, чтобы автоматически перезапустился), воспользуемся дополнительным инструментом — pm2 (есть аналог forever, но он мне не нравится по ряду причин, хотя начал его использовать раньше).
Вообще pm2 надо устанавливать глобально командой

sudo npm i -g pm2

но на модхост у нас на это нет прав, поэтому устанавливаем его прям в текущем проекте.

npm i pm2

Если бы мы установили его глобально, тогда можно было бы выполнять как обычную команду, вызывая pm2 [args]. Но ничего, так мы будем просто полный путь к исполняемому файлу указывать и все.
Выполняем

PORT=4xxx ./node_modules/.bin/pm2 --name modx.pro-api:4123 start npm -- run start

В результате получите типа такого:
[PM2] Starting /usr/bin/npm in fork_mode (1 instance)
[PM2] Done.
┌───────────────────┬────┬─────────┬──────┬───────┬────────┬─────────┬────────┬─────┬───────────┬────────┬──────────┐
│ App name │ id │ version │ mode │ pid │ status │ restart │ uptime │ cpu │ mem │ user │ watching │
├───────────────────┼────┼─────────┼──────┼───────┼────────┼─────────┼────────┼─────┼───────────┼────────┼──────────┤
│ modx.pro-api:4123 │ 0 │ N/A │ fork │ 19495 │ online │ 0 │ 0s │ 0% │ 28.4 MB │ s19387 │ disabled │
└───────────────────┴────┴─────────┴──────┴───────┴────────┴─────────┴────────┴─────┴───────────┴────────┴──────────┘

В дальнейшем можно посмотреть логи процесса

pm2 log [id]

Посмотреть список всех процессов

pm2 ls

Перезагрузить процесс

pm2 reload id

И т.п. Смотрите официальную документацию.

Если служба работает успешно, можно закрывать терминал.

Разберем API-схему.
Вот здесь описана схема для Query: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/schema/api/schema.graphql
Вот здесь для Mutation: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/schema/api/mutation.graphql
Когда мы выполняем npm run build-api, скрипт собирает все схемы в модуле и объединяет их в конечные сземы, используемые API-сервером. Они в итоге попадают вот сюда: github.com/Fi1osof/api.modx.pro/tree/master/src/schema/generated (эти схемы не должны отслеживаться гитом). То есть мы может несколько раз описать одни и те же объекты (как, к примеру, в нашей схеме дважды описан type Query, просто с разными полями), и можем даже их описать в разных файлах, но когда мы билдим api-схему, у нас происходит объединение деклараций, и если конфликтов не будет, то они соберутся в конечную схему с уникальными типами.

Резолверы
Итак, схему мы собрали и уже можно запускать сервер, и если со схемой все ОК, то он запустится. Но для реальной обработки запросов нужны еще функции-резолверы. Поясню: схема определяет только какие запросы можно отправлять, какие параметры в них и какие результаты вы можете получить, но схема не выполняет конечных операций (запросов, арифметических действий и т.п.), для этого нужны непосредственно функции. При этом в обратную сторону это не работает. То есть если вы создали функцию-резолвер, но не описали ее в схеме, то сервер не запустится. Он скажет, к примеру "[Error: Query.test_resolver defined in resolvers, but not in schema]", то есть «резолвер есть, а схемы нет».

Вот наши резолверы: github.com/Fi1osof/api.modx.pro/blob/3b56bff42fd181162561562eea5fd5bb538698e0/src/modules/index.mjs#L89-L114
Кто с JS хоть чуть-чуть дружит, наверняка разберет что происходит. Рассмотрим на примере функции calc_sum.

calc_sum(source, args, ctx, info) {

    const {
      vars,
    } = args;

    if (vars.length < 2) {
      throw new Error("Необходимо минимум два числа");
    }

    return vars.reduce((a, b) => a + b);
  }

}

Все резолверы имеют 4 входящие параметра:

source — родительских объект. Если используется многоуровневый запрос, запрашивающий еще и вложенные данные, на каждом уровне выполнения можно будет получить родительский объект. Но на первом уровне он как правило всегда undefined. Мы этот параметр более внимательно рассмотрим ниже, у нас будет пример многоуровневого запроса.

args — входящие параметры. К примеру, вот наш вызов:

mutation calc_sum{
  calc_sum (
    vars: [2,4, 34.5, 5]
  )
}

Внутри функции мы получим args.vars.
При чем обратите внимание на то, что я даже не делаю проверку наличия этого аргумента:

if (vars.length < 2) {
      throw new Error("Необходимо минимум два числа");
    }

Дело в том, что в схеме я описал, что этот аргумент обязательный.

type Mutation {

  """Return sum of inputs"""
  calc_sum(
    vars: [Float!]!
  ): Float!
}

Знак! — это признак «Обязательно». То есть в данном случае [Float!] — это массив дробных чисел, а [Float!]! — это обязательный массив. Но Float! не требует наличия хотя бы одного элемента (такая вот особенность), так что может прийти пустой массив. Но если в этом массиве какие-то значения будут перечислены, это обязательно будут числа (схема к этому обяжет). По этой причине я и не делаю проверку типов данных при суммировании их.

return vars.reduce((a, b) => a + b);

Наверняка многие знают, что «12» + 13 это будет строковое «1213», а не число 25. Здесь схема не допустит передачи строки вместо числа.

К слову, еще немного о преобразовании. В схеме у нас описано, что foo_number возвращает число.

foo_number: Int!

При этом прописано Int, а не Float, то есть целочисленное, а не дробное. По этой причине:
1. Если наш метод попытается вернуть дробное число, мы получим ошибку, а не число.
2. Даже если мы возвращаем строку, которая может корректно быть преобразована в число, то мы получим в ответе именно число без всяких ошибок. Пример результата выполнения:

{
  "data": {
    "foo_number": 263
  }
}

При этом я сознательно оставил в резолвере return (Math.random() * 1000).toFixed(); Если кто в курсе, Number.toFixed() возвращает строчное значение, а не число. В подтверждение этого посмотрим метод foo_json, в котором я прописал одно из значений — результат выполнения метода this.foo_number(). Вот пример ответа:

{
  "data": {
    "foo_json": {
      "date": {
        "date": "2019-08-08T01:04:41.095Z",
        "year": 2019,
        "month": 7,
        "day": 4
      },
      "foo_number": "47"
    }
  }
}

Результат foo_number в данном случае у нас строчное «47». Дело в том, что foo_json у нас возвращает json. GraphQL не делает проверки типов внутренних значений для него, он просто проверяет, что возвращаемый результат действительно JSON-объект. При этом если мы попытаемся вернуть число или строку, получим ошибку.

Ну а теперь переходим к самому интересному — созданию своего API для modx.pro

Конечно же у нас нет прямого доступа к базе данных modx.pro и мы не сможем получить больше, чем даст нам сам сайт, но тем не менее для эксперимента у нас есть парочка подопытных источников данных:
1. Список пользователей на самом modx.pro
2. Список авторов на modstore.pro
Для этих страниц данные подгружаются по API и их-то мы и возьмем.

Вот я прописал схемы для пользователей самого modx.pro (ModxProUser) и авторов компонентов (ModxProAuthor): github.com/Fi1osof/api.modx.pro/tree/master/src/modules/schema/api/modx.pro

Вот пример запроса пользователей с modx.pro:

query modx_pro_users{
  modx_pro_users_connection(
    limit: 10
    where:{
    	query: ""
      work_only: true
      positive_rating_only: false
    }
    orderBy:{
      sort: topics
      dir: desc
    }
  ){
    success
    message
    data
    limit
    start
    total
    results{
      ...user
    }
    pages{
      ...page
    }
  }
}

fragment page on ModxProUsersConnectionPage{
  isActive
  isCurrent
  num
  url
}

fragment user on ModxProUser {
  id
  avatar
  avatar_retina
  comments
  idx
  link
  name
  place
  rating
  topics
  username
  visitedon
  work
}

А вот авторов с modstore.pro:

query modx_pro_authors{
  modx_pro_authors_connection(
    limit: 2
    where:{
    	query: ""
      work_only: true
      positive_rating_only: false
    }
    orderBy:{
      sort: place
      dir: asc
    }
  ){
    success
    message
    data
    total
    results{
      ...user
      User{
        id
        username
        avatar
      }
    }
  }
}

fragment user on ModxProAuthor {
  id
  community
  downloads
  extras
  fullname
  github
  place
  rating
  support
  work
  tags{
    color
    tag
  }
}

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

User{
        id
        username
        avatar
      }

Это, вероятно, самая интересная часть нашего сегодняшнего материала. Давайте внимательней разберем сами резолверы.

Вот модуль пользователя: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/ModxProUser/index.mjs
Вот здесь мы выполняем запрос на modx.pro и получаем данные: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/ModxProUser/index.mjs#L36-L43

А вот это модуль автора: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/ModxProAuthor/index.mjs
В целом здесь все то же самое, вот здесь мы запрашиваем данные: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/ModxProAuthor/index.mjs#L36-L43
Но самое интересное находится вот здесь: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/ModxProAuthor/index.mjs#L119-L182

Если смотреть схему, то мы видим, что запрос modx_pro_authors_connection возвращает объект ModxProAuthorsConnection.

modx_pro_authors_connection(
limit: Int = 20
page: Int
where: ModxProAuthorWhereInput
orderBy: ModxProAuthorOrderByInput
): ModxProAuthorsConnection!

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

ModxProAuthorsConnection: {
    results: async (source, args, ctx, info) =>  {
        ....
    }
}

и когда GraphQL обрабатывает полученный результат ModxProAuthorsConnection, если в нем запрошего поле results, он прогоняет его через наш резолвер.
Уточню, что если это поле не было запрошего, то оно и не выполняется.

И здесь я пытаюсь понять, был ли у автора запрошен объект User: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/ModxProAuthor/index.mjs#L133-L136

Если да, то я запрашиваю список всех пользователей с modx.pro и пытаюсь для полученных авторов найти их пользователей: github.com/Fi1osof/api.modx.pro/blob/master/src/modules/ModxProAuthor/index.mjs#L139-L175

Уточню два момента:
1. Все пользователи с modx.pro запрашиваются только в том случае, если для автора был прописан подзапрос пользователя.
2. Хотя мы получаем массив авторов, мы не выполняем столько же запросов на modx.pro за всеми пользователями, сколько было получено авторов. Нет, мы обрабатываем только одно поле results, содержащее массив полученных авторов. И запрос на modx.pro мы выполняем соответственно один. Просто перебираем потом массивы и все.
К сожалению, я в этих двух массивах пользователей не сумел обнаружить признаки, которые бы четко идентифицировали авторов и пользователей, поэтому некоторые авторы не содержат данные пользователей.

Еще немного о валидации

Вот чем мне нравится GraphQL, так это тем, что он очень жесткий по части входных и выходных данных. Помню в свое время разрабатывал промежуточный API-сервер на одном важном проекте. ТАм я должен был получать данные от API-сервера заказчика и выводить уже в конечную верстку. Так вот, возвращаемые данные от их API-сервера часто не соответствовали описанию в документации. То есть есть документация, но проект активно развивается, что-то меняется, а документацию не успевают оперативно поправлять. В классическом варианте я шлю API-запрос и получаю ответ, рассчитывая, что ответ придет в соответствии с документацией. Но возникают случаи, когда в большинстве ответов поля эти имеются и данные соответствуют, но для каких-то отдельных возвращаемых сущностей данные не соответствуют. И хорошо если сразу увидел. А если нет? Не можешь же все перепроверить. И вот когда я API-схему прописал и начал использовать промежуточный сервер на графе, вот тогда-то и посыпались ошибки «Здесь значение не было получено, хотя оно обязательно», «Здесь тип данных не тот», «Здесь значение не соответствует заявленному списку возможных значений enum» и т.п.

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

Разные ответы в случае ошибки и успеха.
Посмотрел на сайте ответ сервера и по нему схему описал первоначально:

type ModxProUsersConnection {
  success: Boolean!
  limit: Int!
  start: Int
  total: Int!
  pages: [ModxProUsersConnectionPage!]!
  results: [ModxProUser!]! 
}

В целом логично: success — обязательный, страница, список пользователей и т.п. тоже. Вроде ОК. Но выполнил запрос и получил результат:

{
  "data": null,
  "errors": [
    {
      "message": "Cannot return null for non-nullable field ModxProUsersConnection.limit.",
      "locations": [
        {
          "line": 4,
          "column": 5
        }
      ],
      "path": [
        "modx_pro_users_connection",
        "limit"
      ]
    }
  ]
}

Оказывается, если что-то не так, ответ получаем такой:

{
  "success": false,
  "message": "Access denied",
  "data": []
}

Я уже где-то писал про то, что MODX возвращает разные форматы ответа в разных случаях (в том числе в зависимости от того, как именно ты не авторизован))). Вот это тот случай.

Ладно, дописал схему:

type ModxProUsersConnection {
  success: Boolean!
  limit: Int!
  start: Int
  total: Int!
  pages: [ModxProUsersConnectionPage!]!
  results: [ModxProUser!]!
  
  """Возвращается в случае ошибки"""
  message: String
  data: Json
}

И в резолвере дописал значения по умолчанию. ОК, полетело. Теперь получаем ответ:

{
«data»: {
«modx_pro_users_connection»: {
«success»: false,
«message»: «Access denied»,
«data»: [],
«limit»: 0,
«start»: null,
«total»: 0,
«pages»: [],
«results»: []
}
}
}

Ошибся с форматом поля num.
В схеме для данных постраничности я прописал:

type ModxProUsersConnectionPage {
  isActive: Boolean!
  isCurrent: Boolean!
  num: Int!
  url: String!
}

Думал, что num — это всегда число. И получил ошибку:

{
  "data": null,
  "errors": [
    {
      "message": "Int cannot represent non-integer value: \"...\"",
      "locations": [
        {
          "line": 21,
          "column": 3
        }
      ],
      "path": [
        "modx_pro_users_connection",
        "pages",
        9,
        "num"
      ]
    }
  ]
}

В сообщении мы видим помимо сообщения информацию о том, в каком именно месте запроса возникла ошибка (номер строки и позиция, а так же название проблемного поля). В нашем случае это num. Смотрю ответ, а там:

{
      "num": "...",
      "url": "&limit=20",
      "isCurrent": false,
      "isActive": true
    },

То есть в большинстве случаев там действительно число, но все-таки это немного не то, а просто титл для кнопки. Поэтому меняем тип с Int! на String!..

Булевое значение work.
Для поля work от сервера приходит «0» или «1». Но если я просто пропишу Int, то можно рассчитывать на значения 2, 3 и т.п. А у нас только 0 или 1. Соответственно а схеме я прописал Boolean. Но при выполнении я получаю:

"errors": [
    {
      "message": "Boolean cannot represent a non boolean value: \"0\"",
      "locations": [
        {
          "line": 38,
          "column": 3
        }
      ],
      "path": [
        "modx_pro_users_connection",
        "results",
        0,
        "work"
      ]
    }
  ]
}

То есть graphql не хочет просто так преобразовывать «0» в false и «1» в true. Ок, допишу преобразование на уровне резолвера.

Что в процессе удалось выяснить?

1. Можно запросить и получить сразу весь список пользователей, передав limit: 0;
Не вижу проблемы, а наоборот, это хорошо, потому что можно разом получить сразу всех пользователей. Но вот получение полного списка всех статей было бы напряжно)).

2. Нельзя искать пользователей без рейтинга, можно только с рейтингом.
То есть если передать rating: true, то даст список пользователей только с положительным рейтингом. Но если передать rating: false, то он возвращает просто всех пользователей, а не только тех, у кого рейтинг отрицательный, то есть этот параметр игнорируется. В итоге убрал этот параметр пока из условий поиска, добавил параметр positive_rating_only: Boolean. Так логичней. То есть если «только с положительным» === true, тут понятно. Если «только с положительным» === false, тут тоже понятно, потому что «дай нам не только с положительным». Тонкости…

К слову, я вообще по себе заметил, что работая с JS я стал более внимательным к типам данных и условиям. К примеру, раньше я тоже в подобных случаях на php писал

if($positive){
    $where['positive:>'] = 0;
}

но не писал

if($positive === true){
    $where['positive:>'] = 0;
}
else if($positive === false){
    $where['positive:<='] = 0;
}

А ведь разница существенная. Как результат: часть логики утеряна.

Собственно, то же касается и условия work. Нельзя получить только тех, кто не принимает заказы. Поменял на work_only

3. Сортировку нельзя указать по любому полю, только одно из перечисленных. Подсмотрел три варианта, больше не увидел (даже возможности по fullname отсортировать). Поэтому перечислил четко варианты:

"""Сортировка пльзователей"""
enum ModxProUsersSort {
  
  """По ретингу"""
  rating

  """По количеству топиков"""
  topics

  """По количеству комментариев"""
  comments

}

В списке авторов дополнений
4. В списке авторов дополнений id — это не классический цифровой id, а username.

5. Аватары адреса не совпадают.
В обычном списке «avatar»: "/assets/images/avatars/3508/c3ddc31708cbdb38dee68bbd8babb8ca-48.jpg?t=1551334248"
а в списке авторов avatar: «3a1f53ab0678a39c3aad9f8669ad9f3a»

6. В списке авторов fullname, как положено, а в обычном списке это name.

7. modstore.pro и modx.pro судя по всему — это абсолютно разные сайты со своими отдельными базами данных.

8. Не увидел фильтра авторов по тегам.

Заключение.

Если кто-то проявил интерес к вот этой теме, то, думаю, организация API под это будет в кассу, ведь API — необходимая часть JAM-стэка.

P.S. Я надеюсь каждый для себя сделает выводы, интересна такая технология организации API или нет. Но лично я после знакомства с GraphQL на обычный REST не вернусь уже ни за что.

Еще раз ссылка на исходники: github.com/Fi1osof/api.modx.pro