Стандартная библиотека и расширения

В этом разделе описаны основные способы организации обработки входящих запросов: при помощи функций из набора Открытого пакета интеграций и при помощи функций из пользовательских расширений

Методы ОПИ (стандартный набор)

Как уже рассматривалось в предыдущих разделах документации, каждый обработчик характеризуется функцией, отвечающей за формирование ответа на входящие запросы. По умолчанию, в Melezh встроен полный набор методов из библиотек Открытого пакета интеграций - эти методы могут быть выбраны в качестве функций обработки при настройке каждого конкретного обработчика

При настройке обработчиков в консольном режиме, для получения правильных имен библиотек (команд), функций и их аргументов можно воспользоваться документацией самого Открытого пакета интеграций. Также там приведены примеры возвращаемых значений, которые будут помещены в тела ответов на запросы

Документация ОПИ

warning

Имена библиотек указываются в форме CLI приложения. Например, telegram или gdrive (Google Drive)

При работе с использованием веб-интерфейса, нужную библиотеку и функцию можно выбрать в выпадающем списке при настройке обработчика

Web консоль

Расширения

Помимо стандартного набора функций из набора ОПИ, в качестве функций-обработчиков Melezh можно использовать методы из произвольных .os скриптов. Для их корректной интерпретации должно быть соблюдено три условия:

Метод должен быть функцией, возвращающей двоичные данные, строку или сериализуемую в JSON коллекцию (массив, структуру или соответствие без несериализуемых полей)
Файл скрипта должен иметь корректное имя (без пробелов, желательно латинскими буквами), расширение .os и быть помещен в подкаталог extensions/Modules основного каталога Melezh:

Windows (стандартная установка из exe установщика):
```
C:\Program Files (x86)\OInt\share\oint\lib\melezh\extensions\Modules
```
Linux:
```
share/oint/lib/melezh/extensions/Modules
```
OneScript, в качестве OPM пакета:
```
<каталог OneScript>/lib/melezh/extensions/Modules
```
Метод должны иметь документирующий комментарий следующего вида:
```
// Отображаемое имя метода
// Описание метода
//
// Параметры:
//  Поле1 - Строка  - Значение поля 1 - field1
//  Поле2 - Строка  - Значение поля 2 - field2
//  Поле3 - Строка  - Значение поля 3 - field3
//
// Возвращаемое значение:
//  Структура Из КлючИЗначение - возвращаемое значение
```
Это - стандартный формат комментария EDT, но с тремя отличительными особенностями: второй строкой является краткое описание функции (не обязательно), у параметров есть четвертый блок описания - имя аргумента в CLI стиле, в описании параметра нельзя использовать знак - кроме как для разделения его блоков

warning
Использование - в тексте описания параметра приведет к ошибке

В стандартной поставке, в каталоге extensions/Modules есть модуль RequestsEcho.os, который может быть использован в качестве примера для создания нового расширения:

RequestsEcho.os

// Эхо полей
// Возвращает в ответе поля, отправленные в запросе
//
// Параметры:
//  Поле1 - Строка  - Значение поля 1 - field1
//  Поле2 - Строка  - Значение поля 2 - field2
//  Поле3 - Строка  - Значение поля 3 - field3
//
// Возвращаемое значение:
//  Структура Из КлючИЗначение - Эхо
Функция ЭхоПолей(Знач Поле1, Знач Поле2, Знач Поле3 = "") Экспорт
	Возврат Новый Структура("field1,field2,field3", Поле1, Поле2, Поле3);
КонецФункции

В списке выбора Web-консоли данный модуль будет отображен следующим образом

RequestsEcho

Для использования его в качестве библиотеки при работе через терминал (командную строку), в качестве опции library необходимо указать имя файла модуля без расширения

Также важно отметить, что при использовании функций-расширений, в частности для обработчиков с типом GET или POST + form-data, значения могут приходить в неподходящих типах данных. Melezh не преобразует данные в нужные типы автоматически, за исключением тех, которые могут быть явно выявлены при чтении JSON или разборе multipart/form-data (двоичные или строка)

Для приведения значений к нужным типам можно использовать самописные преобразователи или же те, которые используются в основных функциях Открытого пакета интеграций. Их можно найти в модуле OPI_ПреобразованиеТипов

important

Рекомендуется дополнительно сохранять копии модулей расширений в другом месте, так как в отдельных случаях обновления и удаления Melezh, а также при пересборке образа (если используется Docker), данные файлы могут быть удалены! Также вы можете указать любой сторонний каталог для хранения расширений при помощи настройки ext_path (рекомендуется)

`--melezhcontext`

В отдельных случаях простого получения обработанных данных с возвратом ответа в теле недостаточно. Для более низкоуровневого взаимодействия, с возможностью изменения кода состояния и заголовков ответа, а также получения данных запроса напрямую, в расширениях можно использовать зарезервированную опцию melezhcontext

Для использования данной опции, необходимо указать melezhcontext в качестве CLI-названия для любого из параметров функции в документирующем комментарии:

Пример из Static.os - одного из предустановленных расширений Melezh

// Получить файл из каталога
//
// Параметры:
//  Каталог  - Строка       - Путь к каталогу файла   - catalog
//  ИмяФайла - Строка       - Имя файла с расширением - file
//  MIME     - Строка       - MIME тип файлов         - mime
//  Контекст - HTTPКонтекст - Контекст вызова         - melezhcontext
//
// Возвращаемое значение:
//  Структура Из КлючИЗначение, ДвоичныеДанные - данные файла или информация об ошибке
Функция ПолучитьФайлИзКаталога(Знач Каталог, Знач ИмяФайла, Знач MIME, Знач Контекст) Экспорт

	Каталог = СтрЗаменить(Каталог, "\", "/");
	Каталог = ?(СтрЗаканчиваетсяНа(Каталог, "/"), Каталог, Каталог + "/");

	ПолныйПуть = Каталог + ИмяФайла;
	ФайлПути   = Новый Файл(ПолныйПуть);

	Если Не ФайлПути.Существует() Тогда

		Контекст.Ответ.КодСостояния = 404;
		Контекст.Ответ.ТипКонтента = "application/json";
		Возврат Новый Структура("result,error", Ложь, "Not Found");

	Иначе
		Контекст.Ответ.ТипКонтента = MIME;
		Возврат Новый ДвоичныеДанные(ПолныйПуть);
	КонецЕсли;

КонецФункции

Данная опция не отображается в списке аргументов в веб-интерфейсе и всегда содержит значение типа HTTPКонтекст (один из нативных типов веб-сервера OneScript, отвечающий за обработку запросов). Подробнее о работе с контекстом можно узнать в репозитории OneScript

important

При необходимости добавлять собственные расширения (с melezhcontext в частности), для разработки рекомендуется использовать OneScript версию Melezh. Это позволит запустить проект в режиме отладки (VSCode) и ставить точки останова для просмотра содержимого значений

Отладка расширений

Как и любой проект на OneScript, Melezh может быть запущен в режиме отладки при помощи плагина OneScript Debug (BSL) для Visual Studio Code. Для этого необходимо установить сам плагин, открыть каталог Melezh в VSC и создать launch.json файл конфигурации отладки (вкладка Run anb Debug (Ctrl + Shift + D) -> Create a launch.json file или значок шестеренки, если конфигурация отладки уже была создана ранее)

Пример содержания конфигурации отладки launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Melezh Debug",
            "type": "oscript",
            "request": "launch",
            "program": "${workspaceRoot}/src/core/Classes/app.os",
            "args": ["ЗапуститьПроект", "--port", "1921", "--proj", "R:/new_project.melezh"],
            "cwd": "${workspaceRoot}",
            "env": {},
            "runtimeExecutable": null,
            "runtimeArgs": [],
            "debugPort": 2801
        },
    ]
}

В поле program необходимо указать путь к файлу core/Classes/app.os в каталоге Melezh
В поле args необходимо заменить port и proj на свои порт запуска и путь к файлу отлаживаемого проекта соответственно

important

Если Melezh был установлен не как OPM пакет, то необходимо дополнительно прописать в PATH путь к oscript/oscript.exe (находится в {каталог Melezh}/OInt/share/oint/bin) или скачать OneScript v. >2.0 с официального сайта отдельно

После запуска отладки, можно устанавливать точки останова как в основных скриптах Melezh, так и в файлах пользовательских расширений

Методы ОПИ (стандартный набор)​

Расширения​

--melezhcontext​

Отладка расширений​

Методы ОПИ (стандартный набор)

Расширения

`--melezhcontext`

Отладка расширений