Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама

Що таке модель C4 і як документувати архітектуру, щоб документація не застаріла?

Модель C4 (Саймон Браун) - спосіб описувати архітектуру на чотирьох рівнях деталізації, як карта з різним масштабом:

1. Контекст системи (Context). Система як одна коробка, навколо - користувачі й зовнішні системи, з якими вона взаємодіє. Для всіх, включно з нетехнічними людьми.

[Покупець] → [Інтернет-магазин] → [Платіжна система]
                       ↓
               [Служба доставки]

2. Контейнери (Containers). Що всередині системи як окремо розгортається й запускається: вебзастосунок Laravel, SPA, мобільний застосунок, база PostgreSQL, Redis, воркери черг, пошуковий рушій. «Контейнер» тут - не Docker, а окрема одиниця, що виконує код чи зберігає дані.

3. Компоненти (Components). Структура всередині одного контейнера: модулі, основні сервіси, їх відповідальності й залежності.

4. Код (Code). Класи й зв'язки (UML) - зазвичай не малюється вручну, бо швидко застаріває; генерується з коду за потреби.

Чому C4 зручна:

  • різні аудиторії - бізнесу показують рівень 1, новим розробникам - 1-3;
  • єдина нотація замість «квадратиків і стрілок», де кожен розуміє позначення по-своєму;
  • кожна стрілка підписана (що передається, яким протоколом) - найчастіший недолік неформальних діаграм.

Як не дати документації застаріти:

  • малювати лише рівні 1-2 (іноді 3) - вони змінюються рідко. Детальніше документує сам код;
  • діаграми як код - Structurizr DSL, PlantUML, Mermaid у репозиторії: змінюються в тому самому pull request, що й код, і рецензуються разом;
  • поруч із кодом, а не в окремій вікі, яку ніхто не відкриває;
  • ADR для рішень, C4 - для структури: діаграма показує «що», ADR - «чому»;
  • перевірка на онбордингу: нова людина проходить документацію і позначає, що не відповідає реальності.

Додаткові діаграми C4: динамічні (послідовність взаємодії для важливого сценарію) і розгортання (як контейнери розміщені на серверах і в хмарі).

Головна думка: документація архітектури має бути достатньою, а не повною. Діаграма контексту й контейнерів, що актуальні, - цінніші за сотню докладних, але застарілих.

Докладніше в документації: Модель C4

1

Схожі питання