Планування проекту: сім разів відміряй - один раз відріж - "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 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 user, I want to see list of 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: Як користувач, я маю на меті documentation для цього телеграма 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.

Висновки

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

Список всіх матеріалів серії на початку цієї статті.