Проект представляет собой RESTful API на Laravel, ориентированное на работу с геопространственными данными. "Система" позволяет искать, фильтровать и получать информацию об организациях на основе координат, близости и иерархических связей (например, деятельности с вложенными поддеятельностями или организаций, находящихся в одном здании).
Основной упор проекта идет на демонстрацию подходов использумых разработчиком.
Архитектура проекта делает упор на чистое разделение ответственности с использованием паттернов Service Layer, DTO, что должно обеспечивать поддерживаемость, масштабируемость и тестируемость проекта. Геопространственные запросы обрабатываются с помощью встроенной в MySQL поддержки гео-меток и, эффективно использующих их, пакет tarfin-labs laravel-spatial. Также, для удобного развертывания на любом железе, на проекте используется docker.
Все эндпоинты документированы с использованием OpenAPI/Swagger.
-
Поиск и фильтрация организаций
- Получение организаций через поиск ее деятельности или зданию, в котором она находиться.
- Получение организаций в заданном радиусе от точки.
-
Слой доступа к данным
- Проект спроектирован так чтобы активно использовать паттерны DTO (через пакет wendelladriel/laravel-validated-dto), Service Layer и DI.
- Также в проекте активно используются laravel-фишки, вроде кастомных helpers или scope'ов в моделях.
-
Документация API
- Полная документация OpenAPI для каждого маршрута.
- Автоматически сгенерированная Swagger UI и оптимизированные для быстрого ее написания аттрибуты с модифицированным DarkaOnLine/L5-Swagger.
-
Обработка ошибок
- Человеко-понятные (фронту-понятные) ответы ошибок.
-
Тестирование
- Основная логика и маршруты покрыты Feature Pest-тестами.
-
Производительность
- Кэширование с помощью Redis для оптимизации производительности при частых запросах.
Приложение построено по паттерну Service Layer + DTO, что отделяет бизнес-логику от контроллеров и обеспечивает целостность данных через неизменяемые объекты передачи данных.
- Контроллеры валидируют запросы и форматируют ответы.
- Сервисы содержат бизнес-логику и взаимодействуют с моделями или DTO.
- DTO инкапсулируют передачу данных между слоями, обеспечивая целостность данных и повышенную безопасность.
- OpenAPI атрибуты удобно и оптимизированно документируют эндпоинты не перегружая код контроллеров.
Такой подход обеспечивает чистую, тестируемую и поддерживаемую архитектуру.
- Фреймворк: Laravel
- Документация: OpenAPI / Swagger
- База данных: MySQL
- Тестирование: Pest
- Кэширование: Redis
- Контейнеризация: Docker (LEMP)
Следуйте инструкциям ниже для локального развертывания проекта или на сервере.
Убедитесь, что на вашем компьютере установлены:
- Docker Desktop
- WSL
Больше ничего не потребуется.
-
Клонирование репозитория
git clone https://gitlab.com/pavel.ivanov.pv/cv-project.git
-
Переход в рабочую директорию
cd cv-project -
Подготовка окружения
cp .env.example .env cp .env.example .env.testing
-
Запуск локального окружения
docker compose up -d
-
Запуск контейнера fpm (все последующие команды выполняем из него)
docker exec -it cv-fpm bash -
Установка зависимостей
composer install
-
Генерация ключа приложения
php artisan key:generate
-
Применение миграций и заполнение базы данных начальными данными
php artisan migrate --seed
-
В конце можно протестировать проект
php artisan test --parallel --env=testing
С этого момента проект будет доступен по адресу http://localhost:7890
| Метод | Эндпоинт | Описание |
|---|---|---|
| GET | /api/v1/organizations/near | Получение организаций поблизости |
| GET | /api/v1/organizations/{organization} | Детальная информация об организации |
| GET | /api/v1/organizations/activities/{activity} | Список организаций по деятельности |
| GET | /api/v1/organizations/buildings/{building} | Список организаций в конкретном здании |
| GET | /api/v1/organizations/search?q={name} | Поиск организаций по названию |
| GET | /api/v1/organizations/activities/{activity}/tree | Список организаций по деятельности с вложенными поддеятельностями |