Стаття про ІТ Архітектурні діаграми. Для чого, коли так як з ними працювати. Як створювати діаграми з допомогою коду. Огляд інструментів для написання діаграм.
Займаючись ІТ архітектурою, обов’язково приходиться мати справу із документуванням цієї архітектури. Забігаючи наперед, скажу, що в цій статті я не буду писати про методологічні підходи, стилі і практики при підготовці архітектурних документів. Для цього є чудова книга “Documenting Software Architectures: Views and Beyond, Second Edition”, яку я рекомендую, якщо ж тема вас зацікавила.
Я зупинюся на одному аспекті — діаграми, і як майстерно їх готувати, щоб не витрачати час на роботу заради роботи. Архітектори “малюють прямокутники і стрілки” — так досить часто можна почути роз’яснення ролі архетктора в розробці ІТ рішень. Справедливості ради, з цим важко посперечатися. Дійсно, архітектори готують дорожні карти, функціональні декомпозиції, діаграми розгортання, діаграми станів, reference архітектури, і т.д.
Більш детально я робив огляд ролі ІТ Архітектора в статті.
Діаграми, а вони потрібні?
Працюючи з різними командами, над різними продуктами, я часто ловлю себе на думці, що дуже не просто створювати архітектурні “картинки” так, щоб вони були зрозумілі стейкхолдерам. Але ж якщо вони викликають більше запитань, ніж дають відповідей, — це означає, що вони — “непотріб.” Наведу кілька типових індикаторів:
Що ця фігура означає?
Що означає різна форма контуру у фігур?
Що ця лінія чи стрілка означає?
Що за тип комунікації / асоціації відображено цією стрілкою чи лінією?
Що цей колір означає?
Відсутність звязків між елементами діаграми: це ізольовані сутності?
Що означають ці абревіатури? (неоднозначні / не задокументовані абревіатури)
Якщо ви документуєте архітектуру таким чином, що вище наведені запитання не виникають у читачів, тоді рухаємося далі — необхідність діаграм. Тут, на практиці, думки часто розділяються на дві протилежні групи. Перша — про те, що потрібно готувати якомога більше архітектурних документів, так сказати на всякий випадок. Альтернативна думка — ніякої документації не потрібно, якось так буде. До речі, це ж не лише в архітектурі так: бізнес аналіз, специфікації, інструкції для користувачів, і т.д. — там все те ж саме. Давайте розбиратися по порядку.
Чому ми готуємо діаграми? — щоб мати час займатися новими проектами
І так, почнемо із загального. Архітектура ІТ рішення — це умовний поділ цілого на частини, із звязками між цими частинами. Чим більша і складніша система, тим критичнішим є розподіл на частини, а отже і сама архітектура. Архітектура — це те, що змушує набори цих частин взаємодіяти і успішно працювати разом, як єдине ціле. Архітектурна документація потрібна для того, щоб:
допомагати архітекторам приймати правильні рішення;
пояснювати розробникам, як впроваджувати такі рішення;
пояснювати, чому саме такі рішення були прийняті.
Просто створювати архітектуру ІТ продукту не є чимось самодостатнім. Вона повинна бути правильним чином зкомунікована тим стейкхолдерам, які її потребуть, щоб втілити її в реальний продукт. Документація “говорить” за архітектора сьогодні. Вона потрібна, щоб архітектору не доводилося по сто разів відповідати на одні і ті ж запитання. Документація “говорить” за архітектора завтра, — коли він або вона вже не будуть працювати над цим продуктом.
Дизайнити архітектуру без документування — це все одно, що робити бізнес без реклами. Один ти знаєш, що ти робиш, більше ніхто. Ні компанії, ні продукту, ні вам цього не потрібно!
Коли потрібно працювати над архітектурною документацією? — точно не після завершення розробки
Процес документації часто на практиці трактується як “післядія”, — колись, потім. Щось таке, що потрібно зробити, тому що “так годиться.” Можливо умови контракту вимагають. Чи замовник вимагає. Або ж це є прописано в стандартах розробки нового продукту. Це все може бути дійсно схоже на правду. Я не відкидаю, що такі формулювання є виправдовуючими причинами. Але я точно знаю, що з таким баченням і відношенням до справи не варто розраховувати на успіх і якісний результат. Чому архітектор повинен витрачати свій час та енергію, тільки тому що пункт “архітектурна документація” є у менеджера в чек-списку на поставку?!
І так, найкращі архітектори виготовляють найкращу архітектурну документацію, не тому, що це “потрібно”, а тому, що вони бачать, що це важливо для конкретної справи: виготовлення високоякісного продукту і з якомога меншою кількістю “re-do.”
Документація допомагає архітектору під час роботи над створенням архітектори, а не після.
Краще один раз побачити, ніж сто разів почути — це про архітектурні діаграми
Розібралися з питаннями чому? потрібно документувати архітектуру, а також коли? цим потрібно займатися. А що має бути в цій документації, якою вона має бути, як знайти баланс між якістю і кількістю? Так як контекстом цієї статті я обрав лише діаграми, а не всі складові архітектурного документу, то я зупинюся виключно на них, діграмах. Для більш широкого і глибокого аналізу я відправляю вас до уже згаданої вище книги.
“Краще один раз побачити, ніж сто разів почути” — це ж стосується і архітектурних діаграм. Я переконаний, що центральне місце в архітектурній документації займають саме діаграми, тому то до них і найбльш прискіплива увага. Створюючи архітектурні діаграми, ми відображаємо внутрішню будову та поведінку ІТ продукту. Але не завжди вдається це робити належним чином. Або в результаті ми маємо надто деталізовані і перевантажені діаграми, або ж навпаки — нечіткі і розмиті по своїй суті, які викликають більше питань, ніж дають відповідей. Іноді взагалі діаграми не несуть ніякої цінності — марна трата часу.
Навіть коли вдалося знайти баланс між кількістю і якістю, і архітектор з командою створили діаграми, які дійсно потрібні , релеванті, і дозволили створити продукт бажаної якості, ми на практиці не завжди в змозі оновлювати документацію відповідно до змін в продукті. Чому так відбувається? Я вбачаю такі причини:
розробники часто не підтримують ідей по створенню та підтримці технічної документації; вони вважають це надлишковим, виснажливим і трудомістким процесом, аргументуючи, що вихідного коду достатньо;
витрати на підтримку документації не бюджетуються;
високі витрати на підтримку документації;
процеси управління життєвим циклом продукту не передбачають вимог і аспектів по актуалізації і синхронізації документації (і не лише архітектурної) відповідно до змін (функціональні і нефункціональні вимоги).
Disclaimer: цей список не претендує на вичерпність, і водночас я допускаю, що завжди є виключення.
7 правил, щоб зробити ваші архітектурні діаграми кращими
Отже, зафіксую деякі результати. Пропоную наступні 7 правил “гарно приготовлених” діаграм:
Робити документацію, виходячи із потреб користувачів (розробники, тестувальники, бізнес-аналітики, ІТ-інженери, ІТ-менеджери, і т.д.).
Уникати непотрібних повторень і дублювання в діаграмах.
Уникати неоднозначностей.
Використовувати і слідувати прийнятим стандартам.
Фіксувати обґрунтування змін (версіонування, привязка до дорожної карти продукту).
Тримати документацію в актуальному стані.
Переглядати документацію на предмет придатності.
Як можна готувати архітектурні діаграми краще, але за менший час?
Тепер у нас і є відповіді на питання що? мають представляти собою діаграми, щоб вони були цінними для команди, для стейкхолдерів. Час перейти до того, як можна покращити процес по створенню і, що важливіше, актуалізації архітектурних діаграм. Адже саме тоді вони є потрібними і ними є сенс користуватися. Ніхто ж не хоче генерувати “непотріб” ?!
Обмеживши котекст статті діаграмами, зараз я сфокусуюся виключно на тому, як можна оптимізувати роботу над ними.
Переваги від наявності архітектурної документації, в тому числі архітектурних діаграм, повинні перевищувати витрати на їх створення. Основні витрати — це перш за все human cost. Тому досягнення зменшення цих витрат із збереженням якості самої архітектурної документації я вбачаю в наявності відповідних інструментів, які здатні допомогти і оптимізувати участь людини у виробничому процесі. Як це можливо?
Інструмент може генерувати окремі діаграми самостійно, використовуючи уже написаний програмний код.
По мірі розвитку ІТ продукту, оновлення архітектурних артефактів може бути включено в процеси неперервної інтеграції і виконуватися на етапі збирання і підготовки артефактів продукту до поставки.
Для створення деяких діаграм достатньо текстового редактора.
Сьогодні уже важко знайти команду, яка не користується системою контролю версій для зберігання програмного коду. Багато команд уже навіть не розділяють документацію від репозиторіїв коду, і це прекрасно (привіт GitHub, Azure DevOps, …). Це ж так зручно писати *.md файли поруч із файлами вихідного коду. І діаграми є невідємною частиною більшості документів. Так чому ж тоді їх готувати десь в іншому редакторі, десь зберігати, і потім лише вставляти фінальну “запаковану” версію в markdown-файл документації!? Мені це здається незручним і нелогічним. Я хочу “писати” діаграми текстом і в markdown. І я так роблю, і вам рекомендую.
Як створювати діаграми текстовим описом
Розпочнімо з того, що ви як архітектор (я про роль, а не позицію) маєте свій вподобаний список мов моделювання (AML — Architecture Modeling Language) та типів діаграм. Обирати є з чого, тут проблем немає. Далі виникає логічне запитання: а як же тепер замінити (частково, не повністю) MS Visio і пересісти за Markdown редактор? Відповідь проста — markdown-подібні скриптові мови для генерації діаграм, графіків, графів, і т.д з текстового опису. І тут я вас запевняю, що майже для будь-якого типу діаграм уже існує рішення, яке дозволяє декларативно описувати ваші майбутні візуалізації. Ну і звісно, все це доступно також через CLI (Client User Interface) і на всіх платформах.
Як тут не натякнути на біль, коли ти паралельно живеш в двох світах (Windows і MacOS) і ти звик до MS Visio. Ну так, знавці, звісно, зараз скажуть, що уже є MS Visio Online. Я тут погоджуюся, що це, як ковток свіжого повітря, но все ж таки я не втомлююся чекати Visio для MacOS.
Інструменти для “написання” архітектурних діаграм
Приведу кілька інструментів, з допомогою яких можна описувати текстом діаграми різних видів.
Mermaid
Mermaid — Markdown-подібний синтаксис та інструмент, що дозволяє текстом описувати і автоматично генерувати діаграми. З його допомогою ти можеш створювати діаграми потоків (flow chart), UML-діаграми, кругові діаграми, діаграми Ганта, тощо.Більше того, він вже інтегрований з величезною кількість різноманітних сервісів та платформ, для прикладу GitHub, Azure DevOps, продукти Atlassian, і багато інших.
Приклад 1 — UML схема процесу
Діграма процесу – Mermaid
Приклад 2 — Git Graph (використовую дуже часто для опису процесів по командній розробці)
Git граф – Mermaid
PlantUML
PlantUML — дозволяє швидко “писати” UML діаграми, Archimate діаграми, ERD-діаграми, С4-діаграми, Ditaa діаграми, діаграми Ганта, ментальні карти, WBS-діаграми, AsciiMath і JLaTeXMath нотації.
Приклад — ERD
ERD діаграма – PlantUML
Nomnoml
Nomnoml — ще один інструмент для створення UML діаграм шляхом текстового опису.
Приклад.
UML Діаграма – Nomnoml
BlockDiag
BlockDiag — генератор зображень, який підтримує роботу зі створення UML діаграм.
Приклад.
Blockdiag
WaveDrom
WaveDrom — інструмент для створення Timing- та Waveform-діаграм шляхом текстового опису.
Приклад.
Wavedrom
GraphViz
GraphViz — продукт для візуалізації графів шляхом їх опису текстом.
Приклад — Data Structures.
Діаграма структури даних – GraphViz
Є ще багато схожих інструментів. Я тут згадав лише ті, якими я реально користувався і рекомендую.
Мені 🖤 (Mermaid, GraphViz <3 Azure DevOps)
Мої сценарії роботи наступні:
Простий сценарій — це ручне “написання” діаграм, використовуючи семантику того чи іншого інструменту. Найбільше я полюбляю Mermaid. З його допомогою я можу створити безпосередньо візуалізацію на wiki-сторінці в Azure DevOps, а не вставляти готовий png чи svg файл, після конвертації “raw” файла.
Складний сценарій — автодокументація. В мене є рішення та продукти, для яких документація включає багато різноманітних діаграм. Не розкриваючи деталей, наведу абстрактний приклад. Припустимо є інтеграційна шина (Enterprise Service Bus), на базі якої реалізовані обміни даних між деякою кількістю бізнес-систем. Вся логіка по інтеграції систем реалізована в так званих інтеграційних пакетах, які по суті виконують ETL операції над бізнес-даними. Так ось, вся документація формується автоматично під час поставки кожної нової версії продукта, базуючись на наступних технологіях:
continuous integration & continuous delivery реалізовано на Azure DevOps;
діаграми будуються з допомогою GraphViz;
документація будуються бібліотекою, написаній на PowerShell (внутрішня розробка), вона ж і взаємодіє з GraphViz.
Таким чином, залучення вище згаданих інструментів (і подіних їм) дали можливість:
Зменшити в рази “ручне” створення та підтримку діаграм, які відображають структуру та поведінку окремих компонентів.
Генерувати документацію в повністю автоматичному режимі, без залучення human cost.
Діаграми як код — отримати всі переваги і зручності використання систем контролю версій в роботі із створення і підтримки діаграм. Щоб оцінити ефект, просто уявіть собі, що з якихось причин у вашої команди пропала можливість використовувати Git під час розробки.
Kroki.io — уніфікований API в роботі із генераторами архітектурних діаграм
Здавалося б на цьому можна було закінчувати, якби не один момент. Різноманітність інструментів — це звісно добре. Проте, кожен з них вимагає низки рутинних дій, таких як встановлення, оновлення, налаштування. А кожна із них тягне за собою залежності, відповідно до того, на якій технології написаний продукт: Ruby on Rails, Python, Java, … . В результаті я відкрив для себе — Kroki.io — інструмент, який просто надає API для роботи із BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (через PlantUML), Ditaa, Erd, GraphViz, Mermaid, Nomnoml, PlantUML, SvgBob, UMLet, Vega, Vega-Lite, WaveDrom… І багато ще обіцяють попереду!
Кілька слів про Kroki.io
уже підтримує роботу з величезною кількістю інстурментів по створенню діаграм, графів, графіків, інших візуалізацій із тексту;
безкоштовний;
з відкритим вихідним кодом;
підтримує експорт в png, svg, jpeg, pdf, base64;
доступний як сервіс (безкоштовно і вам нічого не потрібно робити, щоб почати ним користуватися). Не production-ready, виключно як демо-версія;
також доступний як self-hosted — можете встановити і зконфігурувати в себе. Я саме так і зробив. Все що потрібно, це Docker, Docker Compose. Процес встановлення і налаштування займає кілька хвилин.
4 кроки, щоб почати використовувати Kroki.io
Встановити Docker. Щоб перевірити встановлену версію, виконайте наступну команду в терміналі:
docker --versionЗапустіть контейнер kroki. Відразу даю команду із всіма параметрами, щоб запустити контейнер в detached режимі, і прокинути локальний порт 8080 на порт 8000 в контейнері. Виконайте в терміналі команду
docker run -p8080:8000 -d yuzutech/krokiГотово. Щоб перевірити, запустіть ‘/path/to/kroki version’ в терміналі. Якщо інсталяція пройшла успішно, ви побачите версію Kroki CLI.
Загальний вид командного інтерфейсу взаємодії з Kroki:
/path/to/kroki <command> [options] <arguments>
До практики
А ось так на практиці виглядає робота.
Docker образ yuzutech/kroki дозволяє працювати не з усім набором доступних діаграм, лише із наступними:
/c4plantuml
/ditaa
/erd
/graphviz
/dot
/nomnoml
/plantuml
/svgbob
/umlet
/vega
/vegalite
Для того, щоб користуватися BlockDiag, ActDiag, NwDiag, SeqDiag, Mermaid чи BPMN потрібно запустити ще ряд контейнерів: yuzutech/kroki-blockdiag, yuzutech/kroki-mermaid, yuzutech/kroki-bpmn
Для спрощення можна скористатися командою docker-compose up -d щоб запустити кілька контейнерів одночасно, читаючи наперед підготовлений файл docker-compose.yml
Посилання на відповідний розділ документації приведу в кінці статті ⬇.
Я підготував репозиторій на GitHub, де ти зможеш знайти більше десятка прикладів різних типів діаграм, їх опис у різних нотаціях, їх графічне представлення. Посилання також в кінці статті.
Підводячи підсумки
Продовжуйте розвиввати продукт, використовуючи лише достатній набір архітектурних діаграм; не створюйте їх, якщо команда їх не потребує.
“Ручне” створення та підтримка діаграм, які відображають структуру та поведінку окремих компонентів у більшості випадків є неоптимальним підходом і перетворюється на марну трату часу. Генеруйте діаграми з коду, який ви вже маєте в наявності у ваших репозиторіях.
Замість створення надмірної кількості діаграм, зупиніться на двох-трьох, які всесторонньо описують продукт на різних рівнях абстракції і дійсно є необхідні для команди.
Завжди оновлюйте діаграми. Це завдання значно полегшується, якщо діаграми не містять занадто багато деталей — надавайте перевагу абстракціям.
Виховуйте внутрішню культуру команди щодо розуміння необхідності архітектурних документів, в тому числі діаграм.
Ніколи не створюйте архітектурні діаграми просто “щоб було”, щоб виправдати свою роль як архітектора.
Спробуйте kroki.io, — мені він до вподоби.
Корисні посилання
Книга “Documenting Software Architectures: Views and Beyond, Second Edition.”
Стаття-огляд ролі ІТ-Архітектор на моєму сайті.
Mermaid, PlantUML, UMLlet, Nomnoml, BlockDiag, WaveDrom, GraphViz, — інструменти, які я згадував у статті, для генерування архітектурних діаграм із тексту.
Kroki.io — API для роботи із BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (через PlantUML), Ditaa, Erd, GraphViz, Mermaid, Nomnoml, PlantUML, SvgBob, UMLet, Vega, Vega-Lite, WaveDrom…
Як користуватися Kroki.io — детальна інструкція.
Інструкція по встановленню kroki.io.
GitHub репозиторій із прикладами діаграм.
Щиро дякую!
