Архитектура приложения

Архитектурные принципы

В проекте используются следующие принципы:

Все основные компоненты приложения инициализируются в main() функции в файле BuildBotDashboards.kt.
HTTP-обработчики (Handler) не содержат бизнес-логики, отвечают только за обработку HTTP-запроса, извлечение параметров из него, передачу управления операции и формирование HTTP-ответа.
Вся логика получения и обработки данных сосредоточена в операциях.
Domain-модели не зависят от других слоев приложения.
Классы ViewModel используются только для передачи данных в шаблоны Pebble.
Шаблонизатор Pebble отвечает только за формирование HTML-кода на основе данных из ViewModel.

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

`config`

Конфигурация приложения, настройка параметров подключения к БД и настройка JobRunr (менеджера фоновых задач).

`db.operations`

Слой доступа к данным и бизнес-логики приложения.

OperationHolder представляет собой хранилище специализированных классов операций и служит для централизованного доступа к ним. Каждый класс-операция инкапсулирует полный сценарий получения данных. Операция может:

выполнять один или несколько SQL-запросов через jOOQ;
использовать общие подзапросы из subqueries;
объединять результаты нескольких запросов;
выполнять фильтрацию и преобразование данных;
формировать доменные модели, используемые web-слоем.

`domain`

Доменная модель приложения.

Содержит сущности предметной области, используемые различными слоями приложения. Данный слой не зависит от других.

`jobrunr`

Фоновые задачи.

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

`web`

HTTP-интерфейс приложения.

Структура:

Router — регистрация маршрутов.
handlers — обработка HTTP-запросов.
configs — описание варианта отображения для типов сборок (DisplayBuildConfig).
models — ViewModel для Pebble.
view — рендеринг HTML.
filters — http4k-фильтры.
lens — извлечение данных из HTTP-запросов.
extensions — расширение функциональности шаблонизатора Pebble (Extending Pebble документация) .

Сгенерированный код

Каталоги kotlin-jooq-buildbotdb и kotlin-jooq-maxscaledb содержат автоматически сгенерированный jOOQ-код на основе схемы базы данных.

Изменения в этих каталогах вручную не вносятся.

Цикл обработки HTTP-запроса

HTTP Request
      │
      ▼
Router
      │
      ▼
DisplayBuildConfig
      │
      ▼
Handler
      │
      ▼
Operation 
      │
      ▼
Domain Model
      │
      ▼
ViewModel
      │
      ▼
Pebble Template
      │
      ▼
HTTP Response

Общий паттерн обработчиков

Практически все страницы используют один и тот же паттерн.

Для каждого типа сборок существуют три обработчика:

Страница фильтрации (*AllFiltersHandler)
Панель (*AllHandler)
Страница сборки (*Handler) // если нужна детальная информация по отдельной сборке

Пример:

MaxScaleBuild
├── MaxScaleBuildHandler
├── MaxScaleBuildAllHandler
└── MaxScaleBuildAllFiltersHandler

Аналогичная структура используется для остальных типов сборок.

Структура шаблонов Pebble

Все HTML-страницы приложения реализованы с использованием шаблонизатора Pebble.

Шаблоны располагаются в каталоге src/main/resources/net/mariadb/web/models

Каждому ViewModel соответствует одноимённый Pebble-шаблон. Пути и названия файлов должны совпадать, по ним шаблонизатор устанавливает соответствие.

Например:

kotlin/.../models/MaxScaleBuildAllViewModel
        │
        ▼
resources/.../models/MaxScaleBuildAllViewModel.peb

Основные шаблоны

Основные шаблоны (*ViewModel.peb) отвечают за отображение отдельных страниц приложения. Из них DashboardsViewModel.peb — главная страница приложения с карточками панелей.

Как правило, для каждой категории сборок существует три шаблона:

страница фильтрации;
панель;
страница сборки (если нужна).

`models/Layout`

Layout.peb

Базовый шаблон приложения.

Определяет общую HTML-структуру страницы, подключение CSS, навигацию и общий каркас интерфейса.

Все страницы наследуются от него.

`layouts`

Крупные переиспользуемые компоненты интерфейса.

Например:

BuildCardDashboard.peb — основа страницы панели;
DetailedBuildCard.peb — основа страницы сборки;
FiltersForm.peb — основа страницы фильтрации.

`parts`

Небольшие повторно используемые части интерфейса.

Например:

BuildCard.peb — карточка сборки на панелях;
StepAccordion.peb — аккордеоны шагов на странице сборки.

Используются внутри основных шаблонов и layouts.

`macros`

Набор Pebble-макросов для отображения повторяющихся элементов.

Например:

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

Использование макросов позволяет избежать дублирования HTML-кода.

`accessory`

Шаблоны вспомогательных компонентов.

DifferenceBetweenStepConfigsViewModel.peb — особый шаблон для анализа соответствия текущей конфигурации отображения и реального дерева шагов последних N сборок определенного типа.

Keyboard shortcuts

BuildBot Dashboards