Roadmap.track

Лабораторные работы по предмету "Технологии сетевого программирования"

1. Обзор проекта

Roadmap.track — это веб-приложение для отслеживания дорожных карт и прогресса, разработанное с использованием микросервисной архитектуры. Проект объединяет SPA фронтенд на React, бэкенд на Python FastAPI и специализированный сервис на Java Spring Boot для работы с объектным хранилищем MinIO (S3-совместимое решение). Безопасность взаимодействия между компонентами и доступ пользователей обеспечиваются системой аутентификации на основе JWT (JSON Web Tokens). Все приложение контейнеризировано с помощью Docker для обеспечения согласованного развертывания. Для каждого бэкенд сервиса написана документация OpenAPI/Swagger.

2. Стек технологий

Фронтенд

• Фреймворк: React
• Инструмент сборки: Vite
• Язык: JavaScript
• Стилизация: Bootstrap
• Маршрутизация: React Router DOM
• HTTP клиент: Axios
• Состояние/Иконки: React Icons

Бэкенд (Основной сервис на Python)

• Язык: Python 3.13
• Фреймворк: FastAPI
• ORM базы данных: SQLAlchemy
• Миграции: Alembic
• Менеджер пакетов: uv
• Линтинг/Форматирование: Ruff
• Другие ключевые библиотеки:
  • pydantic: Валидация данных
  • python-jose: Работа с JWT токенами
  • passlib: Хеширование паролей
  • redis: Кеширование и брокер сообщений

Сервис изображений (Микросервис на Java)

• Язык: Java 17
• Фреймворк: Spring Boot
• Инструмент сборки: Gradle
• Клиент хранилища: MinIO Java SDK
• Ключевые зависимости:
  • spring-boot-starter-web
  • jjwt (JSON Web Token)
  • springdoc-openapi (Swagger UI)

Инфраструктура и DevOps

Проект полностью контейнеризирован, что гарантирует идентичность окружения разработки и продакшена. Каждый сервис (фронтенд, бэкенд, база данных, хранилище) упакован в отдельный контейнер.

• Контейнеризация: Docker
• Оркестрация: Docker Compose
• База данных: PostgreSQL (через драйвер asyncpg в Python)
• Объектное хранилище: MinIO (S3-совместимое)
• Кеш: Redis

3. Архитектура

Приложение состоит из нескольких взаимодействующих сервисов, определенных в docker-compose.yml:

1. Backend (fastapi_app): Основная логика приложения. Предоставляет REST API, подключается к базе данных PostgreSQL и взаимодействует с Redis. Служит основной точкой входа для операций с данными.
2. Frontend (frontend): Клиентское приложение, обслуживаемое через Vite. Использует API бэкенда для отображения данных и управления взаимодействием с пользователем.
3. Image Service (minio_img_service): Выделенный сервис для загрузки и получения изображений. Взаимодействует с сервером хранения MinIO.
4. PostgreSQL (tcp_labs_db): Система управления реляционными базами данных, хранящая данные приложения.
5. Redis (redis): Хранилище структур данных в памяти, используемое для кеширования и, возможно, очередей задач.
6. MinIO (minio): Высокопроизводительное объектное хранилище, совместимое с API Amazon S3, используемое для хранения изображений и других статических ресурсов.

4. Установка и настройка

Предварительные требования

• Docker
• Docker Compose

Запуск приложения

1. Клонирование репозитория:

   git clone https://github.com/DmitryDol/tcp_labs.git
   cd tcp-labs

2. Настройка окружения: Убедитесь, что в корневом каталоге есть файл .env. Вы можете использовать .env.example в качестве шаблона.

   cp .env.example .env

3. Сборка и запуск: Используйте Docker Compose для сборки и запуска всех сервисов.

   docker-compose up --build

   Эта команда выполнит следующее:

   • Соберет образ Python бэкенда.
   • Соберет образ Java сервиса изображений.
   • Соберет образ Фронтенда.
   • Загрузит необходимые образы для Postgres, Redis и MinIO.
   • Запустит все контейнеры.

4. При первом запуске необходимо залить аватар пользователя по умолчанию в minio, накатить миграции alembic и по желанию заполнить базу данных тестовыми данными:

Накатить миграции (создать БД)

``  docker compose exec -w /app fastapi_app alembic upgrade head  ``

Заполнить бд тестовыми данными

``  docker compose exec fastapi_app uv run fill_database.py  ``

После в postman или в Swagger регистрируем пользователя, заливаем в бакет avatars фото, сервер в ответ вернет JSON с новым именем файла (оно меняется на сгенерированное по UUID). Далее вставляем ответ сервера в .env файл в переменную DEFAULT_AVATAR и пересобираем контейнеры 5. Доступ к приложению:

• Фронтенд
• Документация API Бэкенда:
  • Python сервис
  • Java сервис
• Консоль MinIO

5. Документация Фронтенда (frontend)

Фронтенд представляет собой одностраничное приложение (SPA), созданное с помощью React и Vite.

Структура каталогов

• src/: Исходный код.

  • api/: Содержит файл, в котором прописана логика API запросов в бэкенд сервисы.
  • assets/: Статические ресурсы (изображения, стили).
  • components/: Переиспользуемые компоненты UI.
  • pages/: Компоненты маршрутов, представляющие полные страницы.
  • App.jsx: Главный компонент приложения.
  • main.jsx: Точка входа.

• vite.config.js: Конфигурация Vite.

• DockerFile: Докер файл с инструкциями сборки образа.

Скрипты

• npm run dev: Запускает сервер разработки.
• npm run build: Собирает приложение для продакшена.
• npm run lint: Запускает ESLint для проверки качества кода.

6. Документация Бэкенда (src)

Бэкенд создавался с использованием onion архитектуры.

Структура каталогов

• api/: Содержит определения маршрутов API (роутеры).
• crud/: Реализует операции создания, чтения, обновления, удаления (CRUD) для моделей базы данных.
• models.py: Определения моделей базы данных SQLAlchemy.
• dto.py: Объекты передачи данных (модели Pydantic) для валидации запросов/ответов.
• services/: Слой бизнес-логики.
• repositories/: Реализация паттерна доступа к данным.
• migrations/: Скрипты миграции Alembic для версионирования схемы базы данных.
• config.py: Конфигурация приложения и управление переменными окружения.
• database.py: Настройка подключения к базе данных.
• main.py: Точка входа в приложение.

Ключевые особенности

• Аутентификация: Аутентификация на основе JWT.
• База данных: Поддержка асинхронного PostgreSQL с использованием asyncpg.
• Внедрение зависимостей: Активное использование системы внедрения зависимостей FastAPI.

7. Документация Сервиса Изображений (minio_img_service)

Приложение Spring Boot, предназначенное для управления изображениями.

Особенности

• Интеграция с MinIO: Использует MinIO Java SDK для взаимодействия с объектным хранилищем.
• API: Предоставляет эндпоинты для загрузки и получения изображений.
• Безопасность: Включает поддержку JWT (jjwt) для защиты эндпоинтов.
• Документация: Встроенная документация OpenAPI/Swagger.

Сборка

Проект использует Gradle с Kotlin DSL (build.gradle.kts).

• Обертка: gradlew (Unix) / gradlew.bat (Windows) предоставляется для легкого запуска без глобальной установки Gradle.