Описание

OneCore - это фреймворк на движке onescript, созданный для разработки web-приложений любой сложности, используя компонентный подход.

Проект находится в активной разработке. Фреймворк перешёл на onescript 2.0!!!

Установка

Перед установкой у вас уже должна быть установлена платформа onescript версией не менее 2.0RC4 ветка develop. Рекомендовано использовать OVM для установки платформы onescript.

Скачать архив и распаковать в корень проекта, в корне проекта должен быть каталог "onecore". (временно)
Создать файл main.os и заполнить по примеру:

#Использовать "onecore"

Приложение.Запустить();

Создать файл oscript.cfg со следующим содержимым:

lib.additional=./oscript_modules

Создать файл packagedef со следующим содержимым (временно):

Описание.Имя("onecore")
	.Версия("0.1.2")
	.ЗависитОт("json")
	.ЗависитОт("strings")
	.ЗависитОт("entity")
	.ЗависитОт("cli")
	.ЗависитОт("fs")
	.ЗависитОт("logos");
;

Выполнить консольную команду: opm install -l

Структура проекта

└── Компонент                  # Каталог компонента, имя каталога соответствует имени компонента
    ├── Модели                 # Модели ORM (не реализовано)
    ├── Представления          # Представления данных, они же контроллеры
    ├── Ресурсы                # Статические данные (скрипты, картинки и т. д)
    ├── Сервисы                # Произвольные сервисы, реализующие бизнес логику
    ├── Шаблоны                # HTML шаблоны для шаблонизатора
    └── МодульКомпонента.os    # Скрипт модуля компонента
├── main.os                    # Стартовый скрипт
├── oscript.cfg                # Конфигурационный файл onescript
└── settings.json              # Системный файл с информацией о текущей версии

В корне каталога проекта создаются каталоги компонентов, внутри которых реализуется логика отдельно взятого компонента. При разработке компонентов желательно соблюдать изолированность. В служебных каталогах компонента (Модели, Представления, Ресурсы, Сервисы, Шаблоны) разрешено использовать вложенные каталоги для удобной структуризации логики.

Начало работы

Создание любого приложения на onecore начинается с создания компонента, так как компонент приложения является обособленной функциональной областью, при желании он может быть один, но не советую так поступать.

Создание и регистрация компонента

Для создания компонента необходимо создать каталог в корне проекта и указать имя каталога в соответствии с именем планируемого компонента, например "Ядро", и создать служебные каталоги компонента (см. Структура проекта), также скрипт МодульКомпонента.os с следующим содержимым:

Процедура ПриИнициализацииКомпонента() Экспорт
    // Код, выполняемый при инициализации приложения до его запуска
КонецПроцедуры

Процедура ПриФормированииМаршрутов(Маршруты) Экспорт
    // Код, заполняющий коллекцию маршрутов
КонецПроцедуры

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

#Использовать "onecore"

МенеджерКомпонентов = Приложение.МенеджерКомпонентов();
МенеджерКомпонентов.Инициализировать("Ядро", "core");

Приложение.Запустить();

При выполнении процедуры "Инициализировать" класса "МенеджерКомпонентов", будет вызвана процедура "ПриИнициализацииКомпонента" модуля компонента, в данной процедуре можно выполнять любые действия, например объявить настройки приложения для файла settings.json.

Маршрутизация и создание представления (контроллера)

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

Для того, чтобы создать контроллер, необходимо в каталоге "Представления" вашего компонента создать скрипт и назвать его так, как далее вы хотите его использовать, например "Приветствие.os" и обязательно заполнить его по шаблону:

Перем Контекст;

Процедура GET() Экспорт
    // Код обработчика запроса
КонецПроцедуры

Процедуры обработчиков запросов должны обязательно называться в соответствии с методами HTTP, которые необходимо обработать (GET, POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, PATCH, TRACE), маршрутизатор самостоятельно запустит выполнение нужной процедуры в зависимости от метода поступившего запроса.

Для тестирования сразу напишем код обработчика:

Процедура GET() Экспорт
    Контекст.Ответ.ТипКонтента = "html";
    Контекст.Ответ.Записать("<h1>Привет мир!!! Как банально...</h1>");
КонецПроцедуры

На данный момент мы имеем объект контроллера, но не понятно, как приложение будет понимать, что запрос адресован именно ему, для этого существует маршрутизация, и указать соответствие адреса с обработчиком мы должны в том же модуле компонента в процедуре "ПриФормированииМаршрутов":

Процедура ПриФормированииМаршрутов(Маршруты) Экспорт
    Маршруты.Добавить("/", "Приветствие");
КонецПроцедуры

Согласно тому, что мы указали, сервер, при обращении клиента к корневому адресу, будет переадресовывать выполнение в наш контроллер. Процедура "Добавить" принимает в себя 2 параметра, первый - это шаблон адреса, второй - это строковый путь к объекту обработчика запроса через точку, при этом, если бы у нас объект обработчика находился не в корневом каталоге "Представления", а например в каталоге "Тестирование", тогда указание маршрута выглядило бы так Маршруты.Добавить("/", "Тестирование.Приветствие");.

Шаблоны адресов могут содержать параметы, например: /users/<Число:Идентификатор>, что позволяет нам создавать динамические маршруты, сами же параметры части маршрута передаются в качестве параметров в обработчик запроса:

Процедура GET(Идентификатор) Экспорт
    Контекст.Ответ.ТипКонтента = "html";
    Контекст.Ответ.Записать("Идентификатор пользователя" + Строка(Идентификатор));
КонецПроцедуры

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

Запуск и отладка

Для запуска приложения достаточно выполнить команду oscript main.os, и перейти по адресу, указанному в консоли. Второй вариант - это настроить отладку, для этого нужно создать файл отладки по инструкции платформы onescript и указать следующее содержимое:

{
    // Используйте IntelliSense, чтобы узнать о возможных атрибутах.
    // Наведите указатель мыши, чтобы просмотреть описания существующих атрибутов.
    // Для получения дополнительной информации посетите: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Приложение",
            "type": "oscript",
            "request": "launch",
            "program": "${workspaceRoot}\/main.os",
            "args": [],
            "cwd": "${workspaceRoot}",
            "env": {},
            "runtimeExecutable": null,
            "runtimeArgs": [],
            "debugPort": 2801
        }
    ]
}

Далее запускаем отладку привычным нам способом.

Разработка и использование сервисов

Сервисы - это слой, в котором реализуется бизнес-логика компонента, каждый созданный сервис создаётся как обычный скрипт, определяется фреймворком как класс и доступен для использования во всём приложении. Создавать сервисы можно во вложенных каталогах в целях структуризации.

Например, создадим несколько сервисов:

└── Компонент
    └── Сервисы
        └── ОбщегоНазначения
            ├── ДатаВремя.os
            └── СтроковыеФункции.os

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

&Сервис("ОбщегоНазначения.СтроковыеФункции")
Перем СтроковыеФункции;

Следует учесть, что если сервис используется в объекте компонента, который находится в том же компоненте, что и сам сервис, то указание параметра аннотации "Сервис" должен писаться в сокращенном виде:

&Сервис("ОбщегоНазначения.СтроковыеФункции")
Перем СтроковыеФункции;

Если же сервис используется в другом компоненте, тогда необходимо прописать полный путь:

&Сервис("Ядро.Сервисы.ОбщегоНазначения.СтроковыеФункции")
Перем СтроковыеФункции;

Далее сервисы можно использовать в других сервисах и в представлениях любых компонентов приложения.

Статические файлы

Встроенный web-сервер позволяет отдавать статические файлы, для этого необходимо разместить файл в каталоге "Ресурсы" вашего компонента. При этом струкура каталогов в каталоге "Ресурсы" учитывается при генерации маршрутов.

Адрес к каждому статическому файлу будет формироваться по следующему шаблону: <адрес сервера или ip>/<латинское имя компонента>/<путь к статическому файлу>

Например, если в компоненте Ядро (core), в ресурсах размещен файл index.html: http://127.0.0.1:5555/core/index.html

Если необходимо, чтобы статический файл был доступен в корне приложения, то есть возможность при инициализации компонента установить третий параметр в "Истина":

#Использовать "onecore"

МенеджерКомпонентов = Приложение.МенеджерКомпонентов();
МенеджерКомпонентов.Инициализировать("Ядро", "core", Истина);

Приложение.Запустить();

Далее все ресурсы компонента будут доступны по нескольким адресам: http://127.0.0.1:5555/index.html и http://127.0.0.1:5555/core/index.html

Перехватчики (Middleware)

Фреймворк позволяет перехватывать выполнение запроса перед обработкой представлением и перед отправкой ответа, это позволяет гибко управлять данными для отправки. Перехватчики отрабатывают в той очередности, в которой они указаны разработчиком, при этом сначала запускаются процедуры "ПередВыполнениемПредставления" перед отправкой в представление, и уже после обработки представлением в том же порядке выполняются процедуры "ПослеВыполненияПредставления". Для написания обработчиков перехватчиков используются сервисы, а в стартовом файле прописываются пути к сервисам перехватчиков. Для того, чтобы обработать событие необходимо создать экспортные процедуры "ПередВыполнениемПредставления" или/и ПослеВыполненияПредставления, указав в них 2 параметра: Контекст и ПродолжитьОбработку. Для инициализации сервисов перехватчиков нужно воспользоваться объектом "МенеджерОбъектов", получить его можно с помощью модуля глобального контекста "Приложение", "Приложение.МенеджерКомпонентов()".

Пример стартового скрипта:

#Использовать "onecore"

МенеджерКомпонентов = Приложение.МенеджерКомпонентов();
МенеджерКомпонентов.Инициализировать("Ядро", "core", Истина);

МенеджерОбъектов.ИнициализироватьПерехватчики("Ядро.Перехватчики.ПроверкаТокена");
МенеджерОбъектов = Приложение.МенеджерОбъектов();

Приложение.Запустить();

В метод ИнициализироватьПерехватчики менеджера объектов можно передавать сервисы через запятую или массивом строк, как вам будет удобнее.

Пример сервиса перехватчика по пути: Ядро/Сервисы/Перехватчики/ПроверкаТокена.os

Процедура ПередВыполнениемПредставления(Контекст, ПродолжитьОбработку) Экспорт

    Лог.Отладка("Проверяю токен");
    Токен = Контекст.Запрос.Заголовки.Получить("Token");

    Если НЕ ЗначениеЗаполнено(Токен) Тогда
        Ответ.Отправить(401);
        Лог.Отладка("Отсутствует токен в заголовках");
    КонецЕсли;

    Лог.Отладка("Токен типа проверен");

КонецПроцедуры

Процедура ПослеВыполненияПредставления(Контекст, ПродолжитьОбработку) Экспорт

    Лог.Отладка("Что-то делаем после того, как обработалось представление");

КонецПроцедуры

Перед выполнением каждой процедуры сервиса перехватчика проверяется признак отправленности ответа, в случае, если ответ отправлен, процедура не будет выполнена. Если необходимо прервать дальнейшее выполнение обработки запроса необходмо параметр "ПродолжитьОбработку" установить в Ложь.

Macegor / onecore