Шаблон настраиваемого API для WebSoft HCM, которое позволяет существенно сократить время на разработку и отладку программного кода: вам больше не нужно создавать отдельные документы в системе и копировать в них исходные коды, всё будет лежать в едином структурированном репозитории, поддержка hotreload позволит сразу же видеть внесенные изменения, а типизация избавит от опечаток и необходимости просмотра наличия тех или иных полей объектов или аргументов функций в исходных файлах системы.
Note
Советуем использовать в связке с docker, монтируя данное решение в файловую систему
- Гибкий обработчик запросов для реализации REST API
- Набор часто используемых утилит для работы с объектами и выборками
- Механизм hotreload
- Поддержка типизации
- Автоматизированная сборка проекта с возможностью настройки поставки
Для начала работы необходимо иметь интернет соединение, установленный Git и Node.js, если эти условия удовлетворены - выполняем клонирование данного репозитория к себе и устанавливаем npm зависимости, делается это с помощью нескольких простых команд в командной строке.
# Клонируем репозиторий
git clone https://github.com/@wshcmx/api.git
# Переходим в директорию, куда был склонирован репозиторий
cd api
# Устанавливаем заивимости с помощью npm
npm iОткрываем директорию проекта в редакторе форматированного текста, например, Visual Studio Code или любом другом, с поддержкой TypeScript.
Ниже представлена структура проекта с кратким описанием его директорий.
api/
├─ build/ # Собранный проект
├─ src/ # В данной директории расположен основной код проекта
│ ├─ controllers/ # Доступные для вызова через API функции
│ ├─ services/ # Функции для выполнения запросов и действий, вызываются из контроллеров
│ ├─ utils/ # Общие функции для упрощения разработки, например - приведение даты в определенный формат
Важно помнить, что в программном коде библиотек можно объявлять только функции, в противном случае - будет выведена ошибка из-за ограничений платформы.
Доступ к объявленным функциям можно получить с помощью глобальной переменной wshcmx, в ней хранятся ссылки на все функции из services и utils.
// Обращение к функции `isDate`, расположенной в каталоге `utils`
wshcmx.utils.date.isDate(someDate);
// Обращение к функции `getEvents`, расположенной в каталоге `services`
wshcmx.services.events.getEvents();Вы можете обращаться к переменной wshcmx из любого объекта системы на сервере, если же вам нужно реализовать поддержку в толстом клиенте администратора, необходимо будет точечно устанавливать данную библиотеку для каждого пользователя, что очень сильно не рекомендуется из-за сопутствующей сложности данного процесса.
Директория предназначена для размещения программного кода верхнеуровневых обработчиков пользовательских запросов - предлагается не размещать здесь бизнес-логику, а использовать как промежуточный слой для выполнения каких-то долнительных проверок, склеивания ответов разных функций и прочего.
Важно помнить, что функция будет доступна для вызова только если вы опишите её в специальной функции functions(), как показано на примере ниже.
// Объявляем функцию `functions` и описываем какие endpoint будут доступны пользователю при обращении к ней
export function functions(): Route[] {
return [{
// HTTP метод
method: "GET",
// Адрес
pattern: "/collaborator",
// Название вызываемой функции, расположенной в этом же файле
callback: "getCollaborator"
// Доступ к функции для пользователя или внешего приложения
access: "user"
}];
}
// Объявляем функцию для вывода идентификатора текущего пользователя
export function getCollaborator(params: HandlerParams, Request: Request) {
return wshcmx.utils.response.ok(`curUserID is ${Request.Session.Env.curUserID}`); // Возвращаем ответ, обернув в специальную функцию `ok`
}В результате вышеописанных действий, пользователь сможет получить свой идентификатор, обратившись по адресу https://<server_address>/_api/v1/collaborators/collaborator, при этом - вам не нужно думать об аутентификации, так как этот процесс зашит в ядро оркестратора.
Результаты выполнения функций в контроллерах необходимо оборачивать в специальные функции из библиотеки data.utils.repsponse, тогда ваши ответы будут иметь общий вид.
// Пример формирования ответа с удачным исходом
export function getOk() {
return wshcmx.utils.response.ok(`I'm okay!`, 200);
}
// Пример формирования ответа с неудачным исходом
export function getFail() {
return wshcmx.utils.reponse.abort(`I'm not okay!`, 418);
}Для контроллеров также предусмотрен механизм валидации, который, к тому же, служит
источником данных для сборки OpenApi документации.
export function functions(): Route[] {
return [{
method: "GET",
pattern: "/samples",
callback: "getSamples"
access: "user",
// Описание метода
summary: "Запрашивает какой-то объект",
// Набор параметров, принимаемых методом
params: {
id: {
// Тип значения параметра `id`
type: "string",
// Является ли параметр обязательным
optional: false,
// Откуда будет запрашиваться параметр - `query` | `body`
store: "query",
// Описание параметра
description: "Идентификатор запрашиваемого объекта"
}
}
}];
}Директория для размещения программного кода для работы с конкретными объектами и выборками.
Фактически, является набором библиотек программного кода, функции которых размещаются в глобальной переменной wshcmx.services.
// Пример реализации простого сервиса по выборке мероприятий
export function getEvents() {
return wshcmx.utils.query.extract<EventCatalogDocument>(`for $e in events return $e`);
}
// Данная функция будет доступна к вызову следующим образом
wshcmx.services.events.getEvents();Директория для размещения программного кода общего назначения, например - конвертация дат, приведением объектов к определённому формату и прочее.
Фактически, является набором библиотек программного кода, функции которых размещаются в глобальной переменной wshcmx.utils.
// Пример реализации аналога `Array.pop()`
export function pop(array: unknown[]): unknown[] {
return ArrayRange(array, 0, ArrayCount(array) - 1);
}
// Данная функция будет доступна к вызову следующим образом
wshcmx.utils.array.pop(["foo", "bar"]);В репозитории, в файле .env.example, хранится пример с доступными в проекте переменными окружения, вы можете скопировать данный файл и назвать .env, после чего заполнить его в соответствии с вашими настройками системы.
DEPLOYER_LOGIN=deployer # Логин внешнего приложения
DEPLOYER_PASSWORD=deployer # Пароль внешнего приложения
DEPLOYER_HOST=http://localhost:8080 # Хост для подключения
DEPLOYER_APP_ID=deployer # Идентификатор для подстановки в `x-app-id`
API_WEBTUTOR_BASE_PATH=/wshcmx # Базовый путь `wshcmx`
Под внешним приложением понимается объект remote_application системы WebSoft HCM, расположенный в разделе Безопасность >> API >> Внешние приложения API.
Сборка проекта выполняется с помощью вызова команды npm run build в командной строке.
После этого у вас должна появиться новая директория build, в которой будет содержаться собранный для поставки проект.
Контент директории build необходимо перенести на сервер в x-local://wt/web/wshcmx.
Также необходимо добавить библиотеку wshcmx в коробочный файл api_ext.xml, используемый для регистрации сторонних библиотек.
Для того чтобы изменения вступили в силу, вам необходимо произвести перезагрузку сервера.
После перезагрузки, вы увидите в журнале xhttp информацию о регистрации и загрузке, объявленных в wshcmx, библиотек следующего вида:
Регистрация wshcmx
array был успешно загружен utils - хэш "F29DE32E5B053DD42E71C52E80595F32"
object был успешно загружен utils - хэш "A7DB89C01498303C8254B8A1593A653E"
validator был успешно загружен utils - хэш "7F670B7683DC0E1BFBC30B001CA1361C"
passport был успешно загружен utils - хэш "A43BC502E35D1C0BFEE49DF8212CA97C"
router был успешно загружен utils - хэш "2FC7B615F195CB129CB8A0124C1D7676"
fs был успешно загружен utils - хэш "9D69670F309EF9CC22E142064A9A3233"
paginator был успешно загружен utils - хэш "1A71AF815E2EAFF76A22CB72C231D2FD"
response был успешно загружен utils - хэш "C895BF217B8E225E7C32FB000E58173A"
config был успешно загружен utils - хэш "C38B8CF9B098377BE3B9DA4BFF06C3C3"
query был успешно загружен utils - хэш "97B9E15ACA5D7A9911E4F0CEEADB6E2E"
log был успешно загружен utils - хэш "C0A85788A3832253EEEBE74D6A8950CE"
request был успешно загружен utils - хэш "CF0AD736861E2CB51F8CAD2330E18607"
type был успешно загружен utils - хэш "45508C2BFC6C5B14B7D409B089356D0E"
events был успешно загружен services - хэш "BC355042ED2BBDAA234AFEABED752DA1"
Config loaded: {"env":"development","version":"9.9.9","api":{"pattern":"/_api/v1","basepath":"x-local://wt/web/wshcmx"},"stderr":true}
Web правило успешно обновлено 7257866394331456688
API готово: /_api/v1
wshcmx успешно зарегистрировано
External API Lib: x-local://wt/web/wshcmx/index.xml. Loaded.Если все библиотеки зарегистрировались успешно, вы можете проверить доступ к API по адресу https://<server_address>/_api/v1/ping.
Так как в проекте используется TypeScript, который будет транспилирован в JavaScript - необходимо использовать в разработке только приближенные к SP-XML Script конструкции, иначе вы получите невалидный для WebSoft HCM программный код.