java-explore-with-me

Описание

---

Свободное время — ценный ресурс. Ежедневно мы планируем, как его потратить — куда и с кем сходить. Сложнее всего в таком планировании поиск информации и переговоры. Необходимо учесть множество деталей: какие намечаются мероприятия, свободны ли в этот момент друзья, как всех пригласить и где собраться?

Приложение - афиша событий - позволяет предложить какое-либо событие от выставки до похода в кино и собрать компанию для участия в нём.

Структура модулей приложения

---

Приложение состоит из двух отдельно запускаемых сервисов:

• основной сервис (ewm-main) - содержит основную функциональность приложения;
• сервис статистики (ewm-statistic) - хранит информацию о количестве просмотров событий и позволяет выполнять различные выборки для анализа работы приложения.

Структура модулей и зависимостей представлена ниже в виде схемы.

Спецификация API

• спецификация основного сервиса;
• спецификация сервиса статистики.

Как открыть спецификацию с помощью редактора Swagger?

1. Скопируйте выбранную ссылку на файл спецификации:

   https://github.com/kirshumir01/java-explore-with-me/blob/main/ewm-main-service-spec.json

   https://github.com/kirshumir01/java-explore-with-me/blob/main/ewm-stats-service-spec.json

2. Откройте онлайн-версию редактора Swagger.

3. На верхней панели выберите меню File -> Import URL.

4. Вставьте скопированную ссылку в текстовое поле появившегося диалогового окна и нажмите OK.

Основной сервис (main-service)

API основного сервиса разделен на три части:

• публичная - доступна без регистрации любому пользователю сети;
• закрытая - доступна только авторизованным пользователям;
• административная — доступна для администраторов сервиса.

Каким образом реализована аутентификация и авторизация?

Оба сервиса ExploreWithMe работают внутри VPN. VPN (Virtual Private Network — англ. «виртуальная частная сеть») — совокупность технологий, позволяющих обеспечить одно или несколько сетевых соединений (логическую сеть) поверх другой сети (например, Интернет).

С внешним миром сервисы связывает сетевой шлюз. Он контактирует с системой аутентификации и авторизации, а затем перенаправляет запрос в сервисы. То есть, если шлюз пропустил запрос к закрытой или административной части API, значит, этот запрос успешно прошел аутентификацию и авторизацию.

Структура основного сервиса и функциональность

Модели данных:

• пользователи (users):
  • модель данных: имя, email;
  • валидация данных: email не может быть пустым и должна быть уникальным, логин не может быть пустым и содержать пробелы.
• события (events):
  • модель данных: заголовок, аннотация, описание, дата публикации, дата и время начала, инициатор, необходимость оплаты для участия, лимит запросов на участие, статус пре-модерации, статус публикации, количество просмотров;
  • валидация данных: аннотация от 20 до 2000 символов, описание от 20 до 7000 символов, заголовок от 3 до 120 символов, аннотация, описание, наименование и необходимость оплаты не могут быть пустыми.
• подборки событий (compilation):
  • модель данных: список событий, статус закрепления подборки на главной странице, заголовок подборки;
  • валидация данных: заголовок не может быть пустым и содержит от 1 до 50 символов.
• категории событий (category):
  • модель данных: заголовок категории;
  • валидация данных: заголовок не может быть пустым, должен быть уникальным и содержать от 1 до 50 символов.
• место проведения (location):
  • модель данных: координаты - широта и долгота;
  • валидация данных: координаты не могут быть пустыми.
• запрос на обновление события (request):
  • модель данных: дата и время проведения события, событие, пользователь, статус запроса;
  • валидация данных: не предусмотрена.
• исключение (apiError):
  • модель данных: стектрейс ошибок, сообщение об ошибке, причина ошибки, код ошибки, время и дата ошибки;
  • валидация данных: не предусмотрена.
• комментарий (comment):
  • модель данных: содержание, автор, событие, дата создания, количество изменений, возможность редактирования, дата и время редактирования, статус, родительский комментарий или нет, id родительского комментария;
  • валидация данных: содержание от 1 до 1000 символов.

Примечание: все модели данных содержат поле для присвоения уникального идентификатора создаваемой сущности.

Сервисная часть:

1. Публичная часть:

• пользователи (users):
  • действия: добавление, обновление, хранение, получение и удаление;
  • функционал: добавление вещи (владелец), добавление отзыва (комментария) к вещи (арендатор).
• события (events):
  • действия: получение всех событий (краткое содержание) или конкретного события по id;
  • функционал: получение событий из заданного пользователем диапазона дат или всех событий после текущей даты, получение только опубликованных событий, получение информации и просмотрах и количестве одобренных заявок на участие, сохранение информации и просмотре в сервисе статистики.
• подборки событий (compilation):
  • действия: получение всех подборок или конкретной подборки по id;
  • функционал: поиск подборок по заданным фильтрам.
• категории событий (category):
  • действия: получение всех категорий или конкретной категории по id;
  • функционал: поиск категорий по заданным фильтрам.
• комментарии событий (comments):
  • действия: получение всех опубликованных комментариев по id события;
  • функционал: получение комментариев по заданным фильтрам.

2. Закрытая часть:

• события (events):
  • действия: создание и обновление событий, получение всех созданных автором событий (полное содержание) или отдельного события по id;
  • функционал: дополнительный функционал отсутствует.
• комментарии событий (comments):
  • действия: создание и обновление комментария, получение всех комментариев автора по id события;
  • функционал: дополнительный функционал отсутствует.

3. Административная часть:

• пользователи (users):
  • действия: добавление, получение и удаление;
  • функционал: регистрация пользователя, удаление пользователя, получение всех зарегистрированных пользователей.
• события (events):
  • действия: получение всех событий (полное содержание) или конкретного события по id;
  • функционал: получение событий из заданного пользователем диапазона дат или всех событий после текущей даты, получение событий по статусу состояния, id автора события, категории.
• подборки событий (compilation):
  • действия: создание, обновление, удаление подборки событий;
  • функционал: дополнительный функционал отсутствует.
• категории событий (category):
  • действия: создание, обновление, удаление категорий;
  • функционал: дополнительный функционал отсутствует.
• комментарии событий (comments):
  • действия: получение всех комментариев, получение комментария по id, редактирование комментария;
  • функционал: получение комментариев по заданным фильтрам.

Сервис статистики

Сервис аккумулирует информацию о количестве обращений пользователей к спискам событий и о количестве запросов к подробной информации о событии через публичные эндпоинты. На основе этой информации формируется статистика о количестве просмотров событий.

Инструменты и технологии

---

• фреймворк: Spring Boot 3.2.4
• ORM Hibernate
• аннотирование классов приложения: Lombok
• логирование HTTP-запросов и ответов: Logbook 3.7.2
• хранение данных (рабочий режим): PostgreSQL
• сборка и управление зависимостями: Apache Maven 3.9.9
• версия Java: 21

Схема базы данных приложения (ER-диаграмма)

---

Инструменты для запуска приложения

---

• Java Development Kit (JDK) - версия 21 или более поздняя;
• Apache Maven - версия 3.9.9 или более поздняя.

Инструкции по установке JDK

Ниже приведены инструкции по установке JDK 21 на различных операционных системах.

Установка на macOS

Установите Homebrew запуском следующей команды в терминале (командной строке) операционной системы:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Установите JDK 21 с помощью Homebrew:

brew install openjdk@21

Создайте символическую ссылку, чтобы система могла найти JDK:

sudo ln -sfn /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk

Добавьте JDK 21 в PATH. Откройте файл .zshrc (или .bash_profile, в зависимости от используемой оболочки) и добавьте следующую строку:

echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zshrc

Перезагрузите терминал или примените изменения с помощью команды:

source ~/.zshrc

Проверьте установленную версию Java:

java -version

Установка на Linux

Откройте терминал и выполните команду для обновления списка пакетов:

sudo apt update

Установите JDK 21:

sudo apt install openjdk-21-jdk

Убедитесь, что JDK установлен и настроен корректно:

java -version

Установка на Windows

1. Скачайте установочный файл JDK 21 с официального сайта Oracle или OpenJDK.

2. Запустите установочный файл и следуйте инструкциям установщика.

3. После установки настройте переменную среды JAVA_HOME:

• откройте Системные настройки > Переменные среды;
• в разделе Системные переменные нажмите Создать и введите:
  • имя переменной: JAVA_HOME
  • значение переменной: путь к установленной JDK (например, C:\Program Files\Java\jdk-21).
• добавьте JAVA_HOME\bin в переменную Path.

4. Проверьте версию Java в командной строке:

java -version

Инструкции по установке Maven

Ниже приведены инструкции по установке Maven на различных операционных системах.

Установка на macOS

Установите Homebrew, если он еще не установлен:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Установите Maven с помощью Homebrew:

brew install maven

Проверьте версию Maven, чтобы убедиться в правильной установке:

mvn -version

Установка на Linux

Откройте терминал и загрузите Apache Maven 3.9.9:

wget https://downloads.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz

Распакуйте архив:

tar xzvf apache-maven-3.9.9-bin.tar.gz

Переместите распакованную папку в директорию /opt/:

sudo mv apache-maven-3.9.9 /opt/maven

Добавьте Maven в PATH. Откройте файл .bashrc или .zshrc и добавьте следующую строку:

export PATH=/opt/maven/bin:$PATH

Примените изменения:

source ~/.bashrc

Проверьте версию Maven:

mvn -version

Установка на Windows

1. Скачайте установочный архив Maven 3.9.9 с официального сайта.

2. Распакуйте архив в удобное место, например C:\Program Files\Maven.

3. Настройте переменные среды:

• откройте Системные настройки > Переменные среды.
• в разделе Системные переменные нажмите Создать и добавьте:
  • имя переменной: MAVEN_HOME
  • значение переменной: путь к папке Maven, например C:\Program Files\Maven.
• найдите переменную Path, выберите ее и нажмите Изменить. Добавьте новый путь: %MAVEN_HOME%\bin.

4. Перезапустите командную строку и проверьте версию Maven:

mvn -version

Подготовка к запуску приложения

---

ВАЖНО! Запуск приложения осуществляется через системные порты 8080 и 9090. Перед запуском убедитесь, что порты 8080 и 9090 свободны!

Как проверить, что системный порт свободен?

Ниже приведены инструкции по проверке порта на различных операционных системах.

Проверка порта на macOS

Откройте терминал.

Выполните следующую команду, заменив PORT на номер порта, который нужно проверить:

lsof -i :PORT

Если порт занят, команда выведет список процессов, использующих порт. Для завершения процесса используйте команду:

kill -9 PID

где PID — идентификатор процесса из вывода предыдущей команды.

Если порт свободен, команда не вернет никаких данных.

Проверка порта на Linux

Откройте терминал.

Выполните следующую команду, заменив PORT на номер порта:

sudo lsof -i :PORT

Если порт занят, команда выведет список процессов, использующих порт. Для завершения процесса используйте команду:

sudo kill -9 PID

где PID — идентификатор процесса из вывода предыдущей команды.

Если порт свободен, команда не вернет никаких данных.

Проверка порта на Windows

Откройте командную строку (cmd) или PowerShell с правами администратора.

Выполните следующую команду, заменив PORT на номер порта:

netstat -aon | findstr :PORT

Если порт занят, команда выведет информацию о процессе, использующем порт. Обратите внимание на PID (идентификатор процесса).

Чтобы завершить процесс, откройте Диспетчер задач, перейдите на вкладку Подробности, найдите процесс с соответствующим PID и завершите его.

Если порт свободен, команда не вернет никаких данных.

Где следует выполнять команды для запуска приложения?

• в терминале (командной строке) операционной системы;
• в программной среде разработки IntelliJ IDEA непосредственно в данном файле нажатием на символ тройной стрелки >>>, расположенной слева от строки описания соответствующей команды.

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

---

1. Склонируйте репозиторий с использованием следующей команды:

git clone https://github.com/kirshumir01/java-explore-with-me

2. Перейдите в директорию 'evm-statistic' склонированного проекта и выполните команды:

cd java-explore-with-me

cd ewm-statistic

3. Запустите сборку проекта командой:

./mvnw clean install

4. Запустите сервис 'statistic', выполнив следующую команду:

./mvnw spring-boot:run

5. Перейдите в директорию 'evm-main' склонированного проекта следующими командами:

cd ..

cd ewm-main

4. Запустите сервис 'main', выполнив следующую команду:

./mvnw spring-boot:run

Доступ к публичному API основного сервиса будет открыт по ссылке через адресную строку интернет-браузера: http://localhost:8080.

Доступ к публичному API сервиса статистики будет открыт по ссылке через адресную строку интернет-браузера: http://localhost:9090.