Статичні та динамічні діаграми. Навіщо та як використовувати їх під час документування архітектури
Вітаю, колеги. Мене звати Андрій Трубіцин, я співпрацюю з ЕРАМ у ролі Senior Solution Architect. Мої робочі завдання передбачають документування архітектури рішень. Багато документування... Без діаграм у цій справі ніяк. Пропоную в статті розібрати деякі аспекти використання статичних і динамічних діаграм для документування архітектури, процесів тощо.
Чому не варто нехтувати візуалізацією
Часом ми стаємо свідками того, як людина довго та красномовно розповідає про якийсь процес, а слухачі однаково не все розуміють. Але варто додати малюнок чи діаграму — і вуаля, усе стає на свої місця. Візуалізація — чи не найпотужніший засіб передачі інформації. Зокрема, дослідження Массачусетського технологічного інституту (MIT) довели, що 90% інформації, яку опрацьовує мозок — це візуальна інформація. Лише уявіть: ми сприймаємо зображення за десятки мілісекунд.
Отже, діаграми допомагають передати думки та ідеї чітко навіть без особистої присутності. Завдяки цьому члени команди розуміють, що потрібно робити, а клієнт пересвідчується, що інженери рухаються у правильному напрямку, а він зможе потім підтримувати рішення.
Усі стандарти документування архітектури описують різноманітні види діаграм для візуалізації дизайну IT-рішень. З власного досвіду бачу, що UML — уніфікована мова моделювання — є популярною для цих завдань. Тож використовуватиму її у статті та всіх прикладах, але інколи спрощуватиму UML-позначення чи відступатиму від них, беручи за основу неформальні визначення.
Загальна інформація
Статичні (structure) діаграми використовують для опису статичних структур об’єктів, класів, компонентів, інтерфейсів, операцій, рішень тощо та їх залежності чи зв’язку. Динамічні (behavior) діаграми демонструють порядок взаємодії елементів протягом певного часу чи зміни внутрішнього стану системи.
Як приклад розглянемо, які типи статичних і динамічних діаграм пропонує UML.
Отже, ми бачимо, що UML має сім статичних (structure) та сім динамічних (behavior) типів діаграм. Для їх зображення є каталог елементів. Щоб використовувати цю мову моделювання, вашій команді та клієнту треба розуміти значення всіх UML-елементів. Але інколи можна використовувати неформальну нотацію: звичайні паралелепіпеди та стрілочки.
Опис цієї діаграми словами був би важким для розуміння, але завдяки візуалізації ми одразу бачимо розмаїття варіантів і їхні взаємозв’язки.
Розглядаємо деталі. Статичні діаграми
До детального дизайну варто зробити контекстну діаграму рішення, де система — це просто квадрат, а головний фокус — на дійових особах і системах, які використовують, або яких використовує ваша система. Для цього знадобиться спрощена статична Component-діаграма, на якій буде зображено групи користувачів вашої системи й систем, з якими вона інтегрується. Зображення-приклад нижче здається простим, але нагадує про дійових осіб та інтеграції. Ось, приміром, онлайн-магазин, два користувачі (адміністратор і замовник) і дві системи, з якими він взаємодіє.
Статична Context-діаграма
Інші статичні діаграми допомагають будувати зрізи для документування дизайну, безпеки, інтеграції рішення. Далі, щоб розкрити внутрішню структуру та показати, які інфраструктурні ресурси потрібні, можна використати статичні діаграми розгортання (deployment). Зазвичай вони є у кожній документації й дуже поширені, як і статичні Context-діаграми. Наприклад, у неформальній нотації у хмарі Amazon онлайн-магазин може мати такий вигляд:
Статична діаграма розгортання у хмарі Amazon
На зображенні вище ви бачите віртуальну хмару з двома зонами доступності, де розгорнутий кластер Kubernetes і кілька інших інфраструктурних сервісів.
Ще один корисний вид діаграм — модульні. Вони знадобляться, коли є потреба показати внутрішню структуру рішення чи сервісу, сформувати структуру коду, зрозуміти природну структуру сервісу та планувати задачі з імплементації. На наступній діаграмі від інженера Мартіна Фаулера показано модульну структуру майже будь-якого мікросервісу. Подивіться, як кольорами відзначені модулі за своїм призначенням і поряд є легенда, що їх пояснює.
Розглядаємо деталі. Динамічні діаграми
Розберімось, які типи діаграм потрібні в документуванні й для чого. Поглянемо на питання з погляду архітектора з фази відкриття до фази побудови рішення. А почнемо зі збору функціональних і нефункціональних вимог, бізнес-кейсів тощо.
На етапі збору функціональних і нефункціональних вимог треба побудувати динамічні Use Case діаграми. У багатьох випадках за це відповідає бізнес-аналітик. Приклад такої діаграми ви можете побачити на малюнку далі, де є чотири Use Case та дві дійові особи. Цей вид діаграм допомагає зрозуміти, що користувачі можуть чи хочуть робити з системою.
Нерідко майбутнє рішення передбачає впровадження бізнес-процесів, які можуть бути досить складними. В такому випадку є сенс використати динамічні Activity-діаграми. Один з прикладів — на ілюстрації далі, де зображено процес онлайн-пошуку та придбання товару. Словами його описати майже неможливо, але діаграма здатна передати складні залежності та послідовності просто. Крім того, за допомогою такого типу діаграм можна разом з клієнтом переконатись, що процес повністю задокументований, замовник надав усі деталі, а ви правильно зрозуміли механіку.
Я завжди використовую такі діаграми, коли процес створення сервісу чи нового функціоналу дещо складніший за CRUD (тобто create, read, update, delete). Під час розмови з клієнтом намагаюсь робити чернетку діаграми процесу і демонструю її під час бесіди. Часто замовник пам’ятає основні моменти, але забуває про деякі corner cases (наприклад, що робити, коли крок закінчився невдало, як реагувати на помилки). Саме завдяки Activity-діаграмі можна побачити, що не всі шляхи ведуть до завершення процесу або що на якихось кроках бракує інформації для ухвалення рішення тощо.
Звичайно, створення динамічних Activity (або Business Process Model and Notation) діаграм потребує навичок і знання сили-силенної позначок і символів як від вас, так і від клієнта.
Activity-діаграма пошуку та купівлі онлайн
Часто я обираю динамічні Sequence-діаграми для документування складного процесу взаємодії між компонентами. Наприклад, розглянемо автентифікацію користувача. У статичній діаграмі все здається простим:
Статична Component Auth 2.0 діаграма
Але статичну діаграму використовують для іншого. Її завдання — показати, що є три компоненти, інтеграція і напрямок інтеграції задано. Якщо дати цю діаграму для імплементації комусь, хто не працював з Auth 2.0, то ви отримаєте купу запитань і затримки у впровадженні. Також під час оцінювання обсягу робіт менш обізнаний розробник може подумати, що тут тільки три звернення між компонентами. В той час як насправді все по-іншому. Це стане очевидно, коли ми поглянемо на динамічну Sequence-діаграму:
Динамічна Sequence-діаграма Auth 2.0 аутентифікації через KeyCloak
Тут уже видно, що логіка набагато складніша й оцінювання часу на створення продукту буде вже зовсім іншим. Та навіть цю діаграму можна вдосконалити та додати URL-шаблони для запитів. Найцінніше те, що динамічні Sequence-діаграми задають порядок запитань між компонентами для реалізації складної логіки, а ще з’являється розуміння, як тестувати таку систему. Звичайно, це приклад і майже кожен інженер має досвід роботи з Auth 2.0, але якщо у вашому проєкті є складний алгоритм чи потреба в оркеструванні процесу, який не вартий окремої Activity-діаграми, але все ж таки складний, то Sequence-діаграми стануть у пригоді.
Крім того, динамічні діаграми широко використовують для моніторингу розподілених систем (мікросервісів тощо). Наприклад, інструменти Zipkin або Jaeger подають результати у такому вигляді:
Кілька рекомендацій до візуалізації
Завжди використовуйте легенду — окрему секцію на діаграмі, де ви роз’яснюєте, що позначає кожний елемент. Якщо застосовуєте формальний чи напівформальний (UML, BPMN) підхід, можна просто зазначити його. У частині легенд немає простору для спрощення, адже це важливий елемент у документації на проєкті. Наприклад, я часто бачу, що архітектори клієнта використовують стрілочку для зображення потоку даних у неформальних нотаціях, а архітектори сервісних компаній — стрілочку для зображення напрямку виклику. Тому ту саму діаграму різні інженери можуть читати зовсім по-різному.
Немає сенсу малювати дуже велику «діаграму всього». Якщо проєкт великий, така діаграма буде зовсім нечитабельною і складною для підтримки. Інколи її можна намалювати для себе один раз, щоб зрозуміти весь ландшафт рішень та їхню взаємодію. Але загалом мені подобається підхід Carnegie Mellon Software Engineering Institute (SEI). Він пропонує використовувати метод «точки зору» та зрізу системи. Відповідно до цього варто створювати діаграми, які служать одній меті та відображають обмежений набір елементів системи. Наприклад, щоб описати дизайн безпеки інфраструктури в AWS, ви можете зосередитися на групах безпеки, листах контролю, політиках безпеки сервісів та їх ролях, вказуючи протоколи обміну даних, назви ключів, сертифікатів, алгоритми шифрування тощо. Точно немає сенсу зображати на такій діаграмі, наприклад, розмір дисків, кількість процесорів, обсяг оперативної пам’яті тощо.
Варто зважати на те, кому ви хочете показувати діаграму. Наприклад, складні діаграми на бізнес-презентації можуть навіть ускладнити її, бо учасники почнуть гаяти час на те, щоб розібратись у цьому. Наприклад, у мене є окремі діаграми для бізнесу, менеджменту та інженерів. Так, час на підтримку документації збільшується, але стає легше доносити ідеї до визначеної аудиторії.
Використовуйте кольори розумно, багато відтінків одного кольору роблять діаграми важкими для сприйняття. До того ж серед вашої аудиторії можуть бути люди, які не розрізнюють кольори чи їхні відтінки (таких — до 8%). Так, групувати елементи за допомогою кольору у багатьох випадках варто (це, наприклад, допоможе відокремити сервіси, що вже існують, від сервісів, які ви хочете побудувати). Але все-таки я найчастіше використовую тільки чорний і білий для діаграм.
Намагайтеся використовувати елементи одного розміру, якщо не вкладаєте у нього певний сенс. Наприклад, розмір компонента може показувати вимоги до пам’яті та процесора або кількість Story Points, необхідних для його побудови. Ще старайтеся малювати лінії без перетинань, це додає діаграмам зрозумілості.
Наостанок поділюсь кількома корисними джерелами:
- Специфікація мови моделювання UML.
- Приклади UML-діаграм.
- Специфікація мови моделювання BPMN.
- Documenting Software Architectures: Views and Beyond 2nd Edition.
Тема діаграм широка. Маєте що додати з власного досвіду? Пишіть у коментарях. Буду радий конструктивній дискусії.
