STRUCTURE.md

Структура проекта, логика и библиотеки

Общая информация:

Примеры кода написаны на Scala.

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

Проект разбит на packages по следующему принципу:

• api - протокол, роутеры/контроллеры, директивы
• common - модели, конифиги, хелперы
• persistence - логика работы с БД (мапинги, репозитории/dao, логика коннекта и т.д.)
• services - основная бизнес-логика
• validation - логика для валидации даных

common

config

Модели и инициализация загрузки конфиг файлов в кейс-классы. Все конфиги в себе хранит хэлпер - ConfigKeeper доступный из любой точки приложения Конфиги задаются в /src/main/resources/application.conf Конфигурация описывается с помощью HOCON. За загрузку конфига отвечает Typesafe Config. Мапинг конфигов на классы делается с помощь PureConfig

domain

Данный пакет содержит в себе основные объекты-компаньоны доменной области проекта. Каждый такой объект-компаньон содержит в себе сущности для маппинга на данные из PostgreSQL, объекты для маппинга на json-данные, хелперы для конвертации, трейт + объект-компаньон с форматерами для сериализации/десериализации json данных. В корневом пакетном объекте package.scala содержатся все типы-перечисления (Enumerations) и базовые трейты.

utils

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

persistence

Основное наполнение пакета - это репозитории (объекты-компаньоны содержащий логику запросов к БД для конкретной сущности) + класс для маппинга на таблицу. Вся работа с БД происходит асинхронно.

DatabaseConnection - трейт и его объект-компаньен для инициализации коннекта и api работы с БД.

Маппинг и работа с БД - Slick и расширение Slick-PG для доп. возможностей PostgreSQL. Конфигурация пула коннектов HikariCP, мапперами и т.д.

base

Базовые репозитории и трейты/классы для добавления базовых или дополнительных полей к классу мапинга на таблицу.

migration

Содержит в себе один единственный объект-компаньон DatabaseSchemeMigration для миграций схемы и данных в PostgreSQL.

За мирацию отвечает FlyWay, скрипты миграций расположены в /src/main/resources/db/migration.

services

В данном пакете расположена основная бизнес-логика приложения - различные проверки перед каким либо действием, права доступа и в конечном итоге поиск/создание/обновление/удаление данных из хранилищ. Корневой package.scala содержит в себе абстракцию над результатом сервиса и методы-хелперы. Каждый метод сервиса возвращает некий тип-контейнер, который при успешном выполнении содержит данные либо ошибку сервиса, в случае если что-то пошло не так. Все операции в сервисах выполняются асинхронно, с использованием Scala Futures

validation

В данном пакете расположены валидаторы для данных приходящих от клиента на сервер (dto). Валидатор представляет из себя объект-компаньон с методами нормализации данных (очистка от html и т.д.) и непосредственно валидации. Метод валидации возвращает либо нормализованный/очищенный объект либо ошибки валидации. Некоторые валидаторы также содержат дополнительные методы для проверки различных констрейнов перед записью в БД (например не существует ли уже страна с таким же кодом и т.д.).

Библиотека для валидации Cats.

api

Логика работы с HTTP.

Построена на базе Akka HTTP.

directives

Базовые директивы для удобного построения роутинга, авторизаций, валидаций приходящих данных и т.д.

protocol

Логика и модели для работы с json. Api всегда отвечает идиоматичным json, содержащим статус операции (совпадает с кодом HTTP), опционально данные и ошибку.

Примеры ответа:

• { "status": 200 }
• { "status": 200, "data": {"role":"Admin","nick_name":"ExampleUser","id":1,"status":"Active","created_at":1510936306853} }
• { "status":409,"error": {"details":{"email":"invalid","nick_name":"empty"}} }

Используется Spray-JSON.

routers

Роутеры для обработки запросов от клиентов. Роутинг строется на akka-http DSL - на композиции директив.