В предыдущей публикации я описал обработку статики web-плагином из своего набора инструментов для построения web-приложений, который я назвал Tequila Framework. В этой публикации я опишу, каким образом этот же плагин обрабатывает запросы к API-сервисам.

Для тех, кто ещё не в курсе — у меня несколько нестандартный подход к созданию приложений, я программирую на "чистом" JavaScript (ES 2015+) с использованием пространств имён, собственного DI-контейнера (@teqfw/di) и обильным применением аннотаций JSDoc вместо статической типизации TypeScript'а. Некоторые считают это "некошерным", а я считаю, что JS и TS — как два рукава реки. Где-то в будущем они опять сольются и, по большому счёту, всё равно, по какому рукаву плыть. Для меня на данный момент аннотации JSDoc дают основные преимущества статической типизации (контроль типов) и не влекут за собой необходимость транспиляции.

Под катом — пару подробностей, какой интерфейс сторонним плагинам предоставляет web-плагин для добавления API-сервисов в web-приложение, и как можно использовать одни и те же DTO на сервере и в браузере.

Значение основных используемых терминов можно посмотреть в пункте "Определения". Для понимания изложенного нужно предварительно ознакомиться с предыдущими публикациями:

Обработчик API-запросов

Фабрика обработчика находится в модуле TeqFw_Web_Back_Plugin_Web_Handler_Service. В общей очереди обработчик API-запросов находится перед обработчиком запросов к статике и определяет пространство api для своих запросов (пространства описаны в "Структура URL"):

"web": {
  "handlers": [
    {
      "factoryId": "TeqFw_Web_Back_Plugin_Web_Handler_Service",
      "before": "TeqFw_Web_Back_Plugin_Web_Handler_Static",
      "spaces": ["api"],
      "weight": 100
    }
  ]
}

Основы

В контексте данной статьи, web-сервис — это некоторая функция, которая принимает входные данные, выполняет над ними некоторую операцию и возвращает назад некоторый результат. Функция находится на сервере, по некоторому адресу, доступ к ней осуществляется по HTTP. Таким образом, в сервисе можно выделить следующие составляющие:

функцию
данные запроса
данные ответа
адрес

Протокол HTTP — это правила обмена текстовой информацией по сети. От клиента к серверу и обратно пересылаются массивы текста, представляющего информацию двух типов:

заголовки запроса/ответа
тело сообщения

Обработчик API-запросов извлекает данные из тела HTTP-запроса, анализирует HTTP-заголовки запроса и находит соответствующую сервис-функцию для выполнения операции, передаёт ей входные данные, дожидается завершения обработки, формирует заголовки и тело ответа и возвращает их клиенту.

В web-плагине обработчик API-запросов не разделяет HTTP-запросы по их методу (GET, POST, DELETE, ...) и сопоставляет сервис-функции запросам исключительно на основании адреса запрашиваемого ресурса. В качестве входных и выходных данных POST-запроса используется только JSON. Сервисы применяются для выполнения каких-либо операций на сервере и для передачи-получения данных между фронтом и бэком.

Адресация

Внутри пространства ./api/ каждому teq-плагину приложения отводится своё собственное подпространство, которое совпадает с npm-именем этого плагина ("teq-плагин" = "npm-пакет" + "./teqfw.json"). Т.е., любой сервис плагина @teqfw/web будет находиться по адресу, начинающемуся на http://...[/$root][/$door]/api/@teqfw/web/. Внутри своего адресного пространства плагин сам распределяет адреса для своих сервисов:

/sale/order/
/sale/order/:id
/user/current/profile

Процессор запросов обрабатывает только HTTP-запросы с методами HEAD, GET, POST, PUT, DELETE, PATCH. Сервис-функция сама должна определять, каким образом ей реагировать на различные методы. В моих плагинах сервис-функции отрабатывают одинаково на все методы, а разделение "получения" и "сохранения" данных происходит на уровне адресации:

/sale/get/:id
/sale/save

Создание и регистрация сервисов

Для создания сервиса default-экспорт сервисного модуля должен имплементировать интерфейс TeqFw_Web_Back_Api_Service_IFactory и создавать:

маршурт (интерфейс TeqFw_Web_Back_Api_Service_IRoute);
сервис-функцию;

Модули регистрируются в teq-дескрипторе плагинов (./teqfw.json):

{
  "web": {
    "services": [
      "TeqFw_Web_Back_Service_Load_Config",
      "TeqFw_Web_Back_Service_Load_Namespaces"
    ]
  }
}

Маршрут

Маршрут относится к shared-коду, т.к. он используется на стороне сервера (для разбора запросов и формирования ответа) и на стороне клиента (для формирования запроса и разбора ответа), а также для определения адреса соответствующего сервиса. В плагине я располагаю модули маршрутов в каталоге ./src/Shared/Service/Route/. В отличие от большинства других модулей у модуля маршрута нет default-экспорта, т.к. он является контейнером для трёх взаимосвязанных сущностей:

DTO запроса;
DTO ответа;
фабрики по созданию data-transfer-объектов (также содержит адрес сервиса, которому эти запросы/ответы соответствуют);

Сервис-функция

Это чисто серверный код — асинхронная функция, которой на вход передаётся объект (контекст сервиса), из которого она извлекает нужную информацию и куда помещает результат выполнения операции:

/**
 * @param {TeqFw_Web_Back_Api_Service_IContext} context
 */
async function service(context) {}

Контекст сервиса

Контекст (TeqFw_Web_Back_Api_Service_Context) создаётся обработчиком API-запросов после того, как он находит маршрут, соответствующий запрошенному адресу, а также связанные с ним фабрики для создания DTO запроса и ответа. В контексте находятся:

контекст HTTP-запроса (TeqFw_Web_Back_Api_Request_IContext);
DTO с данными запроса;
параметры маршрута (для адресов типа ./sale/get/:id);
пустой DTO для размещения сервисом данных ответа;
объект для размещения сервисом заголовков ответа;

В контексте сервиса находятся структурированные данные (Object), а в запросе/ответе HTTP находится JSON-текст. За преобразование DTO <=> JSON отвечает как раз обработчик API-запросов. Все сервис-функции работают с контекстом сервиса, в котором запрос/ответ находятся в виде объекта.

Фронтенд-шлюз

Модуль TeqFw_Web_Front_Service_Gate представляет собой шлюз для выполнения клиентских запросов к сервисам. Шлюз преобразовывает входные данные в JSON и POST'ом отправляет их на сервер. В преобразовании данных и адресации сервиса используется route-объект.

В общем случае код в браузере выглядит так:

// извлекаем нужные компоненты кода через DI 
// (в конструкторе объекта или в фабричной функции)
/** @type {TeqFw_Web_Front_Service_Gate} */
const gate = spec['TeqFw_Web_Front_Service_Gate$'];
/** @type {Vnd_Prj_Shared_Service_Route_Name.Factory} */
const route = spec['Vnd_Prj_Shared_Service_Route_Name#Factory$'];

// выполняем запрос (в какой-то внутренней функции или методе)
/** @type {Vnd_Prj_Shared_Service_Route_Name.Request} */
const req = route.createReq();
req.param = 'value';
/** @type {Vnd_Prj_Shared_Service_Route_Name.Response} */
const res = await gate.send(req, route);
if (res) {
    ...
}

Шлюз во время выполнения запроса использует объект с интерфейсом TeqFw_Web_Front_Api_Gate_IAjaxLed для оповещения пользователя о том, что выполняется AJAX-запрос, и объект с интерфейсом TeqFw_Web_Front_Api_Gate_IErrorHandler для оповещения пользователя о возникших ошибках. Default имплементации этих интерфейсов из web-плагина просто выводят оповещения на консоль. Разработчик на уровне своего приложения может в ./teqfw.json переопределить имплементации этих интерфейсов и обрабатывать события на своё усмотрение:

{
  "di": {
    "replace": [
      {
        "orig": "TeqFw_Web_Front_Api_Gate_IAjaxLed",
        "alter": "Vnd_Prj_Front_Model_Gate_AjaxLed",
        "area": "front"
      }, {
        "orig": "TeqFw_Web_Front_Api_Gate_IErrorHandler",
        "alter": "Vnd_Prj_Front_Model_Gate_ErrorHandler",
        "area": "front"
      }
    ]
  }
}

Обработка ошибок

Ошибкой считается такое выполнение запрошенной операции при котором соответствующая сервис-функция не смогла завершиться (произошло исключение) или обработчик API-запросов не смог сформировать ответ из результатов сервис-функции. Исключения перехватываются на уровне обработчика API-запросов и передаются клиенту в виде ответа с кодом 500 (Internal Server Error). Фронтенд-шлюз в такой ситуации вызывает объект с интерфейсом TeqFw_Web_Front_Api_Gate_IErrorHandler для оповещения пользователя об ошибке, а вызывающему коду возвращает false вместо данных ответа сервиса.

Демо

В качестве демонстрации работы сервисов привожу приложение @flancer64/habr_teqfw_web, выполняющее запрос к сервису "Fl64_Habr_Web_Back_Service_Load_Plugins" — на получение кратких данных по всем плагинам этого приложения.

Компоненты сервиса:

Fl64_Habr_Web_Back_Service_Load_Plugins: конструктор сервис-функции;
Fl64_Habr_Web_Shared_Service_Route_Load_Plugins: объект, содержащий адрес сервису, структуру запроса/ответа и фабрики для создания запросов/ответов;

На фронте сервис используется моделью Fl64_Habr_Web_Front_Module.

Так как сервис не использует данные запроса, то обычный GET-запрос также отрабатывает.

Резюме

На примере web-сервисов видно, каким образом может использоваться один и тот же код, как в браузере, так и в nodejs-приложениях:

Fl64_Habr_Web_Shared_Service_Dto_Plugin
Fl64_Habr_Web_Shared_Service_Route_Load_Plugins

Т.к. в демо-приложении используется уже достаточное количество es-модулей, то в браузере можно видеть "файловую структуру", загруженную с сервера:

Использование "интерфейсов" (классов, в которых функциональность только обозначена, но не реализована) и "имплементаций" (классов с реализованной функциональностью, которые DI-контейнер загружает вместо "интерфейсов") позволяет одни и те же web-сервисы использовать как в web-сервере на базе библиотеки nodejs/http, так и на базе библиотеки nodejs/http2. И даже совмещать оба сервера в одном проекте (например, для разработки использовать HTTP/1, а для production'а — HTTP/2). Об этом в следующей статье.

@teqfw/web: Сервисы