Планировщик задач

Проект “Планировщик задач” #

Многопользовательский планировщик задач. Пользователи могут использовать его в качестве TODO листа. Источником вдохновения для проекта является Trello.

Что нужно знать #

Мотивация проекта #

  • Знакомство с микросервисами на практике - разработка проекта, разделённого на несколько сервисов
  • Использование новых модулей Spring Boot - Spring Kafka, Scheduler, Mail
  • Практика с Docker и Docker Compose, докеризация Spring Boot приложение (упаковка его в Docker образ)
  • Знакомство и практика с брокером сообщений Kafka
  • Самостоятельная разработка части схемы REST API

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

Функционал приложения #

Работа с пользователями:

  • Регистрация
  • Авторизация
  • Logout

Работа с задачами:

  • Создание, редактирование (каждая задача имеет заголовок и описание)
  • Пометка задачи как сделанной
  • Удаление

Оповещение пользователей по email:

  • Приветственное письмо
  • Каждый день в полночь оповещение о том, сколько задач было сделано за прошедшие сутки, и какое количество осталось невыполненными

Интерфейс приложения #

Веб-приложение является одностраничным, всё общение с сервером происходит с помощью JavaScript/Ajax, интерфейс обновляется через jQuery.

  • Заголовок
    • Для неавторизованных пользователей - кнопки регистрации и авторизации
    • По нажатию на кнопки открывается модальный диалог с формой регистрации или авторизации
      • Поля диалога регистрации - email, password, repeat password
      • Поля диалога авторизации - email, password
      • В случае ошибки регистрации или авторизации, приложение должно отобразить ошибку, подобно Thymeleaf
    • Для авторизованных пользователей - логин текущего пользователя и кнопка Logout
  • Контент (только для авторизованных пользователей)
    • Поле ввода заголовка новой задачи с кнопкой “Добавить”
    • Список несделанных задач
    • Список сделанных задач

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

  • Поле ввода заголовка задачи
  • Многострочное поле ввода описания задачи
  • Чекбокс, чтобы пометить задачу сделанной (и обратно - пометить несделанной)
  • Кнопка “удалить”

У формы модального окна нет кнопки “сохранить”. JavaScript должен сохранять состояние задачи с помощью Ajax запросов, каждый раз когда пользователь нажимает на чекбокс, или редактирует поля ввода.

SQL база данных #

В этом проекте студент самостоятельно разрабатывает структуру базы данных для хранения пользователей и задач. Отношение между пользователем и задачами - один ко многим.

Как и в предыдущем проекте, в таблице Users ориентироваться стоит на интеграцию с Spring Security. Эта библиотека экосистемы Spring подразумевает определённые атрибуты, которыми должен обладать пользователь, и список которых и станет основой колонок для таблицы.

Таблица Tasks должна содержать поля для описания заметки - заголовок, текст, владелец, статус, и время (timestamp), когда задача была помечена как сделанная.

Миграции #

Рекомендую воспользоваться инструментом миграций для создания таблиц. Необходимо будет принять решение, какой из сервисов является “главным” по работе со схемой БД, и содержит в себе миграции.

JWT #

Вместо сессий воспользуемся JWT. Можно обойтись без refresh token’ов, выдавать только access token, по которым авторизовывать запросы к REST API.

Стоит реализовать авторизацию JWT на уровне Spring Security, например, в виде фильтра, который будет доставать access token из запроса, декодировать и валидировать его.

Сервисы #

Бэкенд #

Spring Boot приложение, реализующее REST API для работы с пользователями, авторизацией, и задачами.

POST /user - регистрация пользователя #

  • Тело запроса - поля формы в формате application/x-www-form-urlencoded или application/json
  • Зарегистрированный пользователь сразу же автоматически авторизуется, без отдельного заполнения логин формы
  • В случае успешной регистрации, код ответа HTTP 200, HTTP заголовок ответа содержит выданный пользователю JWT access token
  • В случае неуспешной регистрации, код и тело ответа описывают ошибку

Пример ответа с ошибкой - “this email is already taken” - HTTP code 409:

{
    "message" - "This email is already taken"
}

Структура ответа с ошибкой - JSON объект с полем message. Код ответа должен быть наиболее подходящим к ситуации из 4хх 5хх кодов ошибок - https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-p2-semantics-18#section-7.4.

Так же, в случае успешной регистрации, пользователю отправляется приветственное письмо (непосредственная отправка письма происходит в другом сервисе, детали ниже в разделе Kafka).

GET /user - получение текущего пользователя #

  • Успешный ответ с кодом HTTP 200 содержит модель пользователя в виде JSON объекта
  • В случае, если пользователь неавторизован, его токен истек - тело ответа содержит сообщение об ошибке, код ответа - HTTP 401

Пример ответа с кодом HTTP 200:

{
    "id": 1,
    "email": "my@email.com"
}

POST /auth/login - авторизация пользователя #

  • Тело запроса - поля формы в формате application/x-www-form-urlencoded или application/json
  • В случае успешной авторизации, код ответа HTTP 200, HTTP заголовок ответа содержит выданный пользователю JWT access token
  • В случае неуспешной авторизации, код и тело ответа описывают ошибку

GET /tasks - получение списка заметок текущего пользователя #

  • Успешный ответ с кодом HTTP 200 содержит список моделей задач в виде JSON массива
  • В случае, если пользователь неавторизован, его токен истек - тело ответа содержит сообщение об ошибке, код ответа - HTTP 401

Дизайн методов для создания, редактирования, удаления задач студенту предлагается разработать самостоятельно.

Фронтенд #

Набор статических файлов:

  • HTML разметка структуры главной страницы (динамические данные вставляются через JavaScript/jQuery)
  • CSS
  • JavaScript

При разработке, файлы можно раздавать локальным сервером встроенным в Intellij IDEA. В контексте Docker Compose стека, образ фронтенд сервиса будет содержать веб-сервер Nginx, раздающий статику.

  • При загрузке страницы, JavaScript делает запрос на получение текущего пользователя. Ответ 401 HTTP означает, что пользователь неавторизован, 200 - авторизован. Для авторизованного пользователя мы можем запросить и отобразить список задач Работа с JavaScript/Ajax:
  • Формы авторизации и регистрации должны быть сверстаны с помощью тега form, но вместо обработчика по-умолчанию (POST запрос и перезагрузка страницы), jQuery будет переопределять обработчик, исполнять POST запрос через Ajax и реагировать на результат, в соответствии с кодом ошибки
  • Веб-страница и REST API будут доступны на разных портах - 80 и 8080. Для вызова методов REST API через Ajax может потребоваться выдача разрешения браузеру через CORS - https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

Рассыльщик писем #

Spring Boot приложение с двумя модулями - Spring Mail и Spring AMQP.

С помощью Spring AMQP приложение подключается к Kafka и создает топик EMAIL_SENDING_TASKS, после чего подписывается на сообщения, поступающие от планировщика и бэкенд-сервиса.

Для каждого полученного сообщения, содержимое которого десериализуется в экземпляр модели, пользуемся модулем Spring Mail, чтобы отправить письмо. Подробнее о том, откуда брать SMTP конфигурацию, написано ниже в разделе Mailjet.

Планировщик #

Spring Boot приложение с двумя модулями - Spring Scheduler и Spring AMQP.

Задача сервиса - раз в сутки итерировать всех пользователей, и формировать для них отчёты о задачах и изменениях в них за сутки.

  • Пользователям, у которых на конец дня есть невыполненные задача, отправляется емейл вида “У вас осталось N несделанных задач”. Тело письма содержит заголовки этих задач (не более какого-то разумного количества, например 5)
  • Пользователям, у которых за последние сутки 1 или более задач были отмечены как сделанные, отправляется емейл вида “За сегодня вы выполнили N задач”. Тело письма содержит заголовки выполненных задач
  • Пользователям, для которых верны оба условия выше, отправляется емейл и со списком несделанных, и сделанных за последние сутки задач

Spring Scheduler по Cron выражению каждую полночь вызывает метод, читающий список пользователей, анализирующий их заметки, и формирующий емейлы для отправки. Сформированные емейлы упаковываются в классы-модели и отправляются в Kafka топик.

Работа с Kafka #

Kafka в контексте Docker Compose стека запускается образов, подобно базе данных.

  • Задачи для отправки емейлов будут попадать в топик EMAIL_SENDING_TASKS
  • Бэкенд сервис и планировщик записывают сообщения в топик, рассыльщик писем - читает
  • Формат сообщений - JSON, сереализуемый и десериализуемый по модели, описанной с помощью класса Java, подобно моделям для контроллеров REST API. Сообщения в топике EMAIL_SENDING_TASKS должны содержать следующие поля - адрес получателя, заголовок и текст письма
  • Для интеграции Spring c Kafka можно использовать модуль Spring Kafka

Mailjet #

Для отправки SMTP нужны логин, пароль, хост и порт SMTP сервера. У емейл сервисов, например Gmail, mail.ru, есть SMTP сервера, с которыми работают емейл-клиенты. Теоретически, можно воспользоваться их сервером, и отправлять письма, авторизовываясь логином и паролем своего ящика, но в реальности, для писем и рассылок обычно пользуются специальными для этого созданными сервисами, например Mailjet, Mailchimp, Mailgun (и десятками аналогичных).

Для примера рассмотрим Mailjet. Бесплатный лимит сервиса - 200 писем на отправку в сутки. Необходимо зарегистрироваться там, сконфигурировать sender адрес (адрес отправителя писем), получить credentials (логин и пароль) и остальные SMTP настройки.

Логин и пароль - секретные данные, которые не должны попасть в git репозиторий. При запуске приложения из IDE или Docker Compose стека, секреты можно подключить к приложению через переменные окружения.

Docker #

В данном проекте воспользуемся Docker для запуска необходимых приложений, и упаковки наших четырех сервисов в Docker образы.

Необходимо:

  • Найти образы для каждого нужного приложения
  • Написать Docker Compose файл для запуска стека с приложениями (по сервису для каждого)
  • Упаковать сервисы в Docker образы, написав для них Dockerfile

Сервисы:

  • task-tracker-backend (порт 8080)
  • task-tracker-frontend (порт 80)
  • task-tracker-scheduler
  • task-tracker-email-sender
  • Postgres
  • Kafka

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

Для структурирования мульти-сервисного проекта существует 2 альтернативных подхода:

  • Отдельный репозиторий для каждого сервиса, плюс отдельный репозиторий для Docker Compose. Главный минус - необходимость создавать и управлять несколькими репозиториями
  • Единый репозиторий для всех сервисов и Docker Compose. Главный минус - необходимость дополнительной конфигурации Intellij IDEA для работы с несколькими Gradle/Spring Boot приложениями в одной папке

Выбор того или иного варианта зависит от ситуации. В рамках данного проекта, вариант #2 кажется более предпочтительным.

Деплой #

Приложение целиком будем деплоить через Docker.

Шаги:

  • С помощью GitHub Actions (детали ниже) автоматизировать сборку докер образов для сервисов task-tracker-backend, task-tracker-frontend, task-tracker-scheduler, task-tracker-email-sender
  • В хостинг-провайдере по выбору арендовать облачный сервер на Linux
  • Установить Docker
  • Скопировать на удалённый сервер Docker Compose файл для запуска сервисов приложения, запустить
  • Опционально - купить доменное имя и привязать к нему IP сервера

Ожидаемый результат - приложение доступно по адресу http://$server_ip, или http://$domain_name (если куплено доменное имя).

CI/CD #

С помощью GitHub Actions автоматизируем сборку докер образов для четырёх сервисов приложения (task-tracker-*):

  • У каждого сервиса должен быть отдельный репозиторий
  • При push в основную ветку запускается GitHub Actions пайплайн:
    • Шаг 1 - сборка образов сервисов. Советую разобраться с multi-stage Dockerfile, первая стадия - сборка jar артефакта с помощью JDK, вторая стадия - копируем jar в легковесный образ с jre
    • Шаг 2 - push образов в публичный репозиторий, откуда их можно будет скачать для деплоя. В качестве публичного репозитория проще всего воспользоваться https://hub.docker.com/. Необходимо будет разобраться с безопасным хранением логина/пароля от Docker Hub на GitHub для push’а образов

План работы над приложением #

  • Docker Compose - добавить Postgres, Kafka
  • Backend - работа с пользователями
  • Backend - работа с JWT, авторизация
  • Frontend - структура страницы, интерфейс и Javascript для регистрации и авторизации
  • Backend - работа с задачами
  • Frontend - листинг, добавление, редактирование, удаление задач
  • Email sender - реализация получения сообщений от Kafka и отправки емейлов
  • Backend - отправка приветственного письма при регистрации
  • Scheduler - отправка пользовательских отчетов по сделанным и оставшимся задачам
  • CI/CD, деплой

Ресурсы для работы над ошибками #

January 5, 2025
Edit this page