103 lines
8.8 KiB
Markdown
103 lines
8.8 KiB
Markdown
# Архитектура и структура сервиса
|
||
|
||
Документ описывает как организован сервер дипломного проекта: какие слои присутствуют, как они взаимодействуют и где искать ключевые модули.
|
||
|
||
## Общий обзор
|
||
|
||
Сервис написан на Kotlin с использованием Ktor и разворачивается как Netty-приложение (`Application.kt`). Приложение поднимает инфраструктурные плагины (HTTP, сериализация, безопасность) и регистрирует доменные маршруты. Все функции сгруппированы в повторяющийся паттерн `Controller → Service → Repository → Entity`, что делает поддержку CRUD-операций симметричной во всех доменных областях.
|
||
|
||
Высокоуровневый поток запросов:
|
||
|
||
1. HTTP-вызов попадает в `Routing.kt`, где маршруты разделены на публичную и админскую зоны (`/api/v1/...`).
|
||
2. Контроллер модуля занимается десериализацией запроса, базовой валидацией и формированием ответа.
|
||
3. Сервис инкапсулирует бизнес-правила: публикация материалов, фильтрация, проверка прав, подготовка DTO.
|
||
4. Репозиторий обращается к PostgreSQL через Ktorm, используя HikariCP-пул соединений.
|
||
5. Исключения (`ValidationException`, `NotFoundException`) перехватывает `StatusPages`, что обеспечивает единый контракт ошибок.
|
||
|
||
Графическая схема слоев расположена в `docs/crud-model.svg`.
|
||
|
||
## Структура каталогов
|
||
|
||
```
|
||
src/main/kotlin
|
||
├── app # Bootstrap: Application, Routing, Security, HTTP, Database
|
||
├── shared # Переиспользуемые DTO, пагинация, ошибки
|
||
└── modules # Доменные модули (admin, news, service, serviceCategory, lead)
|
||
src/main/resources
|
||
├── application.yaml # Конфигурация Ktor
|
||
└── openapi # Спецификации API
|
||
src/test/kotlin # Зеркало production-пакетов для тестов
|
||
docs/
|
||
├── crud-model.svg # Диаграмма последовательности CRUD
|
||
└── architecture.md # Текущий документ
|
||
```
|
||
|
||
## Инфраструктурный слой (`app/*`)
|
||
|
||
- **Application.module** – точка входа, выстраивает последовательность `configureDatabase → configureHTTP → configureSerialization → configureSecurity → configureRouting`.
|
||
- **Database.kt** – инициализация пула HikariCP (настройки берутся из `.env`), регистрация `Database` в `Application.attributes`.
|
||
- **Http.kt** – подключает плагины Ktor (CORS, Compression, CachingHeaders, StatusPages, Swagger UI). Здесь же централизованно обрабатываются исключения.
|
||
- **Serialization.kt** – `ContentNegotiation` с `kotlinx.serialization`.
|
||
- **Security.kt** – загрузка параметров JWT из окружения, настройка схемы `admin-auth`, валидация `JWTPrincipal`.
|
||
- **Routing.kt** – собирает зависимости модулей, подключает публичные маршруты и оборачивает админские роуты в `authenticate("admin-auth")`.
|
||
|
||
## Доменные модули (`modules/*`)
|
||
|
||
Каждый модуль состоит из четырех файлов:
|
||
|
||
- `Controller.kt` – набор Ktor-маршрутов для публичной и/или админской зоны.
|
||
- `Service.kt` – бизнес-логика. Например, `NewsService` отвечает за публикацию, пагинацию и преобразование сущностей в DTO, а `ServiceService` поддерживает фильтры по статусу, категории и ценовому диапазону.
|
||
- `Repository.kt` – слой доступа к данным на Ktorm: построение SQL, пагинация, CRUD-операции, трансформации в `Entity`.
|
||
- `Entity.kt` / DTO – описания таблиц, модели для сериализации и транспортировки данных.
|
||
|
||
### Admin
|
||
|
||
Отвечает за регистрацию, авторизацию и управление администраторами. Использует `BcryptPasswordHasher` для хранения паролей и `TokenService` для выпуска JWT. Публичная часть (`/admin/login`) возвращает токен; защищенная (`/admin/*`) требует `admin-auth`.
|
||
|
||
### News
|
||
|
||
Два набора маршрутов: публичные (`/news`, `/news/{slug}`) и админские (`/admin/news`). Сервис применяет правила публикации и формирует страницы (`Page<T>`). Репозиторий обрабатывает SQL для списков и выборок по `slug`.
|
||
|
||
### Services и Service Categories
|
||
|
||
`ServiceController` поддерживает сложные фильтры (категория, диапазон цен, статус). `ServiceService` связывает услуги с категориями, обеспечивая получение вложенных DTO. `ServiceCategory*` модули обслуживают справочник категорий и проверяют уникальность `slug`.
|
||
|
||
### Leads
|
||
|
||
`publicLeadRoutes` принимает заявки с сайта (`POST /leads`), `adminLeadRoutes` предоставляет CRUD для операторов. Сервис выполняет базовую валидацию и поиск по строке `q`.
|
||
|
||
## Общие компоненты (`shared/*`)
|
||
|
||
- `shared.pagination.Page` – универсальный ответ для списков.
|
||
- `shared.errors.ValidationException/NotFoundException` – типы, которые перехватываются `StatusPages` и автоматически конвертируются в HTTP-ответ.
|
||
|
||
## Работа с БД
|
||
|
||
- **База** – PostgreSQL, подключение через Ktorm + HikariCP (`jdbc:postgresql://...`).
|
||
- **Пулы** – настраиваются через переменные окружения (`DB_HOST`, `DB_POOL_MAX` и т.д.).
|
||
- **Репозитории** – реализованы вручную на SQL Builder, что дает контроль над запросами и связями между таблицами (`services` ↔ `service_categories`, `news`, `leads`, `admins`).
|
||
|
||
## Безопасность
|
||
|
||
- Единственная схемa аутентификации – JWT `admin-auth`.
|
||
- Конфигурация (`JWT_SECRET`, `JWT_ISSUER`, `JWT_AUDIENCE`, `JWT_EXPIRES_MIN`) читается из `.env` или переменных окружения.
|
||
- Public маршруты доступны без токена, все `admin*Routes` подключены внутри `authenticate`.
|
||
|
||
## Сборка и эксплуатация
|
||
|
||
- Основные команды Gradle:
|
||
- `./gradlew run` – локальный сервер.
|
||
- `./gradlew test` – прогон тестов (обязателен перед пушем).
|
||
- `./gradlew buildFatJar` – сборка standalone JAR.
|
||
- `./gradlew buildImage` / `runDocker` – сборка и запуск docker-образа.
|
||
- Конфигурация HTTP-порта, логирования и OpenAPI лежит в `src/main/resources/application.yaml` и `resources/openapi`.
|
||
- Для обновления документации добавляйте артефакты в `docs/` (например, текущую архитектурную схему и диаграмму CRUD).
|
||
|
||
## Тестирование
|
||
|
||
Тесты зеркалируют production-пакеты (`src/test/kotlin/...`). При добавлении новой функциональности рекомендуется:
|
||
|
||
1. Класть тесты в соответствующий пакет модуля (например, `modules/news/NewsServiceTest.kt`).
|
||
2. Проверять ветки успеха, валидации и авторизации.
|
||
3. Запускать `./gradlew test` перед коммитом, чтобы убедиться в корректной работе всего набора.
|