Планирование проекта: семь раз отмерь — один раз отрежь - "Java-проект от А до Я"

Приветствую вас, коллеги. Сегодня мы поговорим о том, какую подготовительную работу нужно провести, прежде чем начать безудержно кодить. А конкретнее — о планировании, создании архитектуры приложения. Но с чего начать? Как построить эту архитектуру? Как и водится во всем, нужно начать с начала. А именно — с ИДЕИ. Идеей нашего проекта было создание полезного телеграм-бота с базовым функционалом. Повторим, каким именно: “Я, как пользователь, хочу иметь возможность получать уведомления, когда будут выходить новые статьи в тех группах на JavaRush, которые меня интересуют.” Следуя YAGNI принципу, будем строить наше приложение. Это значит, что мы будем брать только то, что нам нужно. Мы не будем создавать функционал наперед и про запас только потому, что нам так хочется и когда-то это может реально пригодиться. Да, мы будем создавать удобочитаемое и расширяемое приложение, но это не значит, что мы сделаем схему базы данных “на вырост”. Чтобы этот “вырост” не поддерживать, я решил, что лучше будет вовсе отказаться от него. Это нам поможет избежать излишней поддержки во время разработки и излишнего тестирования. Позже, когда наш проект выйдет в прод (опять англицизм, от сокращения prod — production), мы уже сможем что-то сделать большее. Как только определились с идеей, нужно немного пошалить порисовать. А что рисовать? Нам понадобится возможность сохранять данные по подпискам на группы разных пользователей. Я знаю, что можно использовать идентификатор пользователей в виде IDшника чата в телеграме. И есть идея, как собственно будет проходить поиск новых статей: будем искать во всех группах, на которые есть подписки, новые статьи и отправлять их в чаты. Исходя из этого, получим в первом приближении такое (вот вам разработка без прикрас):Я не надеюсь, что вы разберетесь в моем почерке: я хочу показать, как именно и с чего начинается разработка. Первый этап пройден: определились кое-как с тем, что будет. Сверху описаны модели/таблицы в базе данных. Но это черновой вариант: его можно и нужно отшлифовать и привести в более читаемый вид. Пока шлифовал, вспомнил, что хочется еще получать статистику по работе бота. Добавил это. В этом рисунке более чем видно, что и как будет устроено. То есть, какие будут таблицы и поля в них, какие будут имена сущностей для таблиц. Решено, что их будет несколько:

• User — информация о пользователе телеграма, который будет использовать нашего бота. Как вы видите, мы сохраняем только айдишник чата и флаг, активный пользователь или нет. Почему? Потому что наша цель — не собрать информацию о пользователях, а принести им пользу;
• GroupSub — здесь будет информация о группе, на которую есть подписка и последняя статья, которая была отправлена подписчикам;
• Statistics — для нее не создал схему — сделаем это позже. Это не главная цель в MVP проекта.

После этого захотелось уже более детально показать путь поиска новых статей. Для этого я воспользовался BPMN схемой, которую перевел в картинку и получил вот такое:Здесь уже все более читабельное и понятное. По этой схеме будем работать в поиске. Такую схему очень любят менеджеры, потому что она понятна не только программистам :D В общем и целом, начало положено.

Создаем репозиторий для работы

Наконец-то можно создать репозиторий уже для работы с телеграм-ботом.

1. Заполняем уже привычные для нас пункты — имя репозитория, его краткое описание.
2. Добавляем лицензию — Apache 2.0 (вы можете выбирать лицензию по своему усмотрению).
3. Наш проект теперь доступен — вот ссылка на него: JavaRush Telegrambot.

Создаем проект в репозитории

Для работы с проектом хорошо бы использовать инструменты GitHub’a, такие как проект. Что это такое? Это место, в рамках которого можно будет создавать задачи, отслеживать их выполнение, сохранять статус задачи. Определять, кто будет выполнять их и другое. Для этого в созданном проекте найдем кнопку Projects, и там уже создадим новый:Как видим, здесь я указал имя проекта, описал его и выбрал шаблон, по которому будем работать — Automated Kanban. Для нас сейчас не так уж важно, что это значит. Главное, что у нас будет доска с задачами, поделенная на колонки, где каждая из колонок будет статусом задачи:

1. To do — все задачи, которые планируется сделать;
2. In progress — задачи, над которыми идет работа в данный момент;
3. Done — задачи, которые уже сделаны в рамках этого проекта.

Таким образом мы будем знать о статусе наших задач. Какие в работе, какие сделаны. Причем это важно и удобно не только в случаях, когда есть команда, но и когда работаешь сам. Чтобы на доске что-то появилось, нужно создать задачи (Issue).

Пишем задачи (issue) для проекта

Чтобы понять, какие задачи писать, определимся с тем, что у нас будет в проекте. Нам нужно приложение, которое можно было бы запустить легко и быстро, чтобы был доступ к базе данных, чтобы мы могли управлять схемой базы данных и изменять ее, чтобы можно было делать REST запросы в JavaRush для получения данных по статьям. Исходя из этого, можно выбрать следующие технологии:

• SpringBoot — как каркас для нашего приложения,
• Spring Data — для работы с базой данных,
• Flyway — для работы с миграциями базы данных,
• MySQL — как БД для проекта,
• Telegrambot StringBoot starter — библиотека для работы с телеграм-ботом,
• Unirest — библиотека для работы с REST запросами.

Из всего вышеперечисленного начнем создавать задачи.

Шаблон создания задач

Будем создавать задачи по следующему шаблону:

1. Имя задачи будет иметь такой вид: JRTB-{IssueNumber}:{IssueDescription}, где:
   • {IssueNumber} — это порядковый номер задачи. Берем его на один больше от последней задачи;
   • {IssueDescription} — краткое описание задачи.
2. В теле задачи будем делать ее более детальное описание (иногда может совпадать с описанием в имени задачи).
3. Acceptance Criteria — это перечень требований, после выполнения которых можно считать, что задача выполнена. Так сказать, критерии приемки задачи. По ним ревьювер (от англ. reviewer — рецензент — человек, который смотрит как выполнена задача) может понять, полностью ли сделана задача или нет.

По этому шаблону создадим наше первое задание:Также стоит обратить внимание, что при создании я сразу определил, к какому проекту подходит эта задача, кто ее будет выполнять (assignee) и к какой метке (label) эта задача относится. Далее я просто покажу имена задач с небольшим описанием и ссылки на них. Все они находятся здесь. Выполнять задачи мы будем примерно в том же порядке, что здесь указан:

1. [FEATURE] JRTB-0: create Skeleton Spring boot project — здесь все понятно: нужно сделать первую часть того, что мы делали в предыдущей статье.
2. [FEATURE] JRTB-2: add telegram bot to the project — добавляем пустого бота, который будет просто отвечать и говорить, что он жив-здоров.
3. [FEATURE] JRTB-3: Implement Command pattern for telegrambot — настроим правильный подход к работе с командами в телеграм-боте. Пока что для нескольких команд.
4. [FEATURE] JRTB-1: Add repository layer — это одна из самых больших задач — здесь объединено все то, что нужно сделать для работы с базой данных.
5. [FEATURE] JRTB-5: As a user, I want to add the group to the subscription — это уже первая User Story в понимании Agile. Здесь уже будет реальный выхлоп для наших пользователей: можно будет добавлять подписки на группы в бота.
6. [FEATURE] JRTB-12: Implement scheduling for sending notification about new articles — вот здесь будет реализация поиска новых статей, если они вышли для каждой из групп и отправлены всем пользователям, которые подписаны на группы.
7. [FEATURE] JRTB-6: As a user, I want to see list of my group subscriptions — здесь все просто: добавляем команду с выводом списка всех групп, на которые подписан пользователь.
8. [FEATURE] JRTB-7: As a User, I want to remove group subscription from my subscriptions — здесь нужно реализовать удаление подписки пользователя на обновления в группе.
9. [FEATURE] JRTB-8: As a User, I want to set inactive using bot — реализовать остановку бота. То есть все то, что нужно сделать в нашей системе, чтобы работа остановилась. Добавить в обработку команду /stop.
10. [FEATURE] JRTB-9: As a User, I want to start working with bot OR set active if I used it before — добавить обработку команды /start. Именно так, как мы хотим этого.
11. [FEATURE] JRTB-10: As an administrator, I want to see bot statistics — создание сбора статистики бота. Добавление возможности администраторов.
12. [FEATURE] JRTB-11: As a user, I want to see documentation for this telegram bot — написание документации. Да-да, друзья, без нее никуда, и чем раньше вы научитесь это делать, тем лучше будет для вас))

Вот это уже похоже на начало проекта. Так сказать, поработали мы архитектором проекта и бизнес-аналитиком.

Заполняем репозиторий

Что нужно еще сделать ДО того, как мы начнем кодить? — Автор, ну сколько можно добавлять этих абзацев, ты что их, из бездны достаешь?? — Нет, качество работы проявляется в деталях. И именно они имеют смысл. Поэтому добавим еще одну деталь. Чтобы проект стал популярным и понятным для других разработчиков, нужно наполнить его. Что нужно добавить? Полный перечень того, что можно сделать, я описал в статье Оптимизируем работу со своими проектами на GitHub: знакомство с Github Template Repository. Очень советую прочитать. Для нас важно иметь четкое версионирование, четкое понимание того, что мы делаем. Поэтому я добавил RELEASE_NOTES файл, в котором будут записываться изменения по нашему проекту. В качестве примера можно посмотреть на RELEASE_NOTES из моего проекта (да, почему бы не показать то, во что я вкладываю свои силы и творчество). Там описаны изменения по каждой новой версии. Также добавил шаблоны для создания новых задач, в которых есть 4 варианта:

• Bug Report задача, которую создают пользователи/тестировщики, нашедшие ошибку в работе. Это очень важная вещь: она помогает управлять исправлением ошибок;
• Feature request — это задача на добавление новой функциональности. Все первые задачи на проекте — задачи на feature request;
• Improvement request — задача на улучшение работы приложения. Например, на изменение тестовых ответов в работе с ботом. Я не technical writer и могу придумать не совсем правильные ответы. Так если будет желание и умение — предлагайте :)
• Question — это вопрос к разработчикам по работе приложения. Очень полезная вещь. Допустим, нет понимания в работе или есть сомнения в каком-то вопросе — можно задать таким образом вопрос и получить ответ из первых рук.

Если посмотреть на гитхаб, то это будет выглядеть именно так:Также на данный момент мы располагаем документом по работе с JavaRush API для работы с группами.

Что дальше?

Ну вот выполним мы все эти шаги и что, проект закроется? Нет, вовсе нет. Этот проект будет жить и дальше. Его буду развивать я и все те ученики/выпускники JavaRush, которые захотят принять участие. Какие планы на будущее? Их много. Самый первый план — это создание Java-клиента для JavaRush API. Разработчики пообещали сделать открытый доступ к их Swagger’у. Что такое сваггер мы тоже разберем. Прикольная и очень полезная вещь. Дальше будем интегрировать JavaRush сайт с телеграм-ботом. Подключим пользователя к боту, чтобы синхронизировать подписки. Создадим статистику по прохождению курса. И все, что вы захотите как JavaRush Community.

Выводы

Сегодня мы поговорили о закулисной работе до создания проекта. А точнее, о том, как создать план работы, без которого можно потратить много энергии впустую. Повторю, начало проекта уже выложено в открытый доступ здесь. Традиционно предлагаю подписаться на мой аккаунт на гитхабе. Таким образом вы сможете получить изменения в проекте ДО того, как публикуется статья. Уже предполагаю, что все заинтересованные лица зарегистрировались на гитхабе. Да, проект не летит так быстро, как нам хотелось бы. Впрочем, как и реальные проекты на работе. В следующей статье я опишу добавление первых задач. Всем спасибо за прочтение и до скорого!

Список всех материалов серии в начале этой статьи.