---
id: Extensions
keywords: [1C, 1С, 1С:Предприятие, 1С:Предприятие 8.3, API, Интеграция, Сервисы, Обмен, OneScript, CLI]
title: Стандартная библиотека и расширения
sidebar_position: 4
---

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

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

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

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

![Документация ОПИ](../../../../static/img/Docs/Melezh/ru/3.png)

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

<br/>

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

![Web консоль](../../../../static/img/Docs/Melezh/ru/4.png)

<hr/>

## Расширения

Помимо стандартного набора функций из набора ОПИ, в качестве функций-обработчиков 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
	```

+ Метод должны иметь документирующий комментарий следующего вида:

	```bsl
	// Отображаемое имя метода
	// Описание метода
	//
	// Параметры:
	//  Поле1 - Строка  - Значение поля 1 - field1
	//  Поле2 - Строка  - Значение поля 2 - field2
	//  Поле3 - Строка  - Значение поля 3 - field3
	//
	// Возвращаемое значение:
	//  Структура Из КлючИЗначение - возвращаемое значение
	```

	Это - стандартный формат комментария EDT, но с тремя отличительными особенностями: второй строкой является краткое описание функции (не обязательно), у параметров есть четвертый блок описания - имя аргумента в CLI стиле, в описании параметра нельзя использовать знак `-` кроме как для разделения его блоков

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

<br/>

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

```bsl title="RequestsEcho.os"

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

```

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

![RequestsEcho](../../../../static/img/Docs/Melezh/ru/5.png)

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

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

Для приведения значений к нужным типам можно использовать самописные преобразователи или же те, которые используются в основных функциях Открытого пакета интеграций. Их можно найти в модуле [OPI_ПреобразованиеТипов](https://github.com/Bayselonarrend/OpenIntegrations/blob/main/src/ru/OInt/tools/Modules/OPI_%D0%9F%D1%80%D0%B5%D0%BE%D0%B1%D1%80%D0%B0%D0%B7%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%D0%A2%D0%B8%D0%BF%D0%BE%D0%B2.os)

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

## `--melezhcontext`

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

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

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

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

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

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

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

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

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

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

```

Данная опция не отображается в списке аргументов в веб-интерфейсе и всегда содержит значение типа `HTTPКонтекст` (один из нативных типов веб-сервера OneScript, отвечающий за обработку запросов). Подробнее о работе с контекстом можно узнать в [репозитории OneScript](https://github.com/EvilBeaver/OneScript/tree/develop/src/OneScript.Web.Server)

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

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

Как и любой проект на OneScript, Melezh может быть запущен в режиме отладки при помощи плагина [OneScript Debug (BSL)](https://marketplace.visualstudio.com/items?itemName=EvilBeaver.oscript-debug) для Visual Studio Code. Для этого необходимо установить сам плагин, открыть каталог Melezh в VSC и создать `launch.json` файл конфигурации отладки (вкладка `Run anb Debug (Ctrl + Shift + D)` -> `Create a launch.json file` или значок шестеренки, если конфигурация отладки уже была создана ранее)

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

```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 с официального сайта](https://oscript.io/downloads/preview) отдельно
:::

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