Документирование решений с помощью диаграмм C4

В современных проектах часто возникают проблемы с пониманием архитектуры. Если вы работаете над большой системой со множеством компонентов, важно качественно документировать и визуализировать свои решения. Без чёткого и понятного представления архитектуры работать будет сложно.
Возьмём для примера большое корпоративное приложение. Допустим, вы разрабатываете систему управления фитнес-клубом FitLife. В такой системе много компонентов:
  • управление членством,
  • расписание занятий,
  • обработка платежей,
  • интеграция с внешними системами.
Если нет чёткого понимания, как эти компоненты взаимодействуют друг с другом, поддерживать и развивать код будет сложно. Разным командам будет трудно понять друг друга и договориться. Из-за этого появятся ошибки, а разработка будет занимать больше времени.

Нотации и подходы

Есть много разных нотаций и подходов для визуализации архитектуры. Вот некоторые из них.
У каждого подхода свои преимущества и недостатки. Важно выбрать метод, который соответствует вашим потребностям и поможет сделать ясную и понятную визуализацию.
В этом уроке мы рассмотрим модель C4. Сочетая в себе простоту и гибкость, она предлагает эффективный способ документирования архитектуры.
Мы будем строить диаграммы C4 для системы управления фитнес-клубом FitLife. В процессе подробно разберём каждый уровень модели, чтобы решить проблему непрозрачности архитектуры и улучшить взаимодействие между командами.

Модель C4

До появления C4 архитектуру в основном представляли с помощью разных стилей диаграмм UML. Они мощные, но нетехническим специалистам сложно в них разобраться.
Саймон Браун разработал модель C4, чтобы предложить более простой и интуитивно понятный способ описания архитектуры систем. Он акцентировал внимание на четырёх уровнях абстракции: контексте, контейнерах, компонентах и коде. Благодаря этому модель получилась универсальной — её понимают и используют разные стейкхолдеры.

Плюсы

  • Простота и чёткость. Модель C4 описывает архитектуру на разных уровнях абстракции. Она понятна и для технических специалистов, и для бизнес-экспертов.
  • Универсальность. Модель можно применять для описания разных типов систем. Она хорошо работает в проектах любого масштаба. А ещё — легко адаптируется под потребности команды или проекта.
  • Упрощение коммуникации в команде проекта. C4 улучшает коммуникацию между командами разработки и стейкхолдерами. Она обеспечивает единый язык для обсуждения архитектуры. Это помогает избежать недопониманий и улучшает совместную работу.
  • Гибкость. Модель упрощает процесс внесения изменений и улучшений в документацию архитектуры. Поэтому её можно использовать на всех этапах жизненного цикла проекта.

Минусы

  • Затраты времени. На создание и поддержку диаграмм нужно выделять время.
  • Модель слишком сложная для небольших проектов. На небольших проектах не всегда нужно использовать все уровни модели. Её приходится адаптировать под простые системы.
  • Зависит от инструментов. Чтобы модель хорошо себя показала, нужно использовать специальные инструменты для создания и обновления диаграмм. А ещё — обучать команду работать с этими инструментами.

Задание 1

Как архитектурные диаграммы помогают в процессе разработки ПО? Выберите один верный ответ.
Теперь рассмотрим структуру и уровни диаграмм С4.

Структура и уровни диаграмм C4

Модель C4 состоит из четырёх основных уровней:
  • Context diagrams — диаграммы контекста. Они показывают, как система выглядит в целом.
  • Container diagrams — диаграммы контейнеров. Важный момент: «контейнер» — это не сущность Docker. Так в C4 называют приложения и хранилища данных. Диаграммы контейнеров показывают высокоуровневые технические строительные блоки.
  • Component diagrams — диаграммы компонентов. Они переходят на уровень отдельного контейнера и показывают компоненты внутри него.
  • Code/classes diagrams — диаграммы кода. Показывают, как реализован отдельный компонент.
Из этих уровней и складывается название модели.
В итоге С4 помогает составить многоуровневую карту вашего кода. Вы можете охватить взглядом сразу всю систему. Или увеличить масштаб интересующей области, чтобы рассмотреть детали.
Это визуализация от создателя модели — Саймона Брауна. Чтобы увеличить картинку, перейдите на официальный сайт C4 —https://c4model.com. CC BY 4.0
Итак, каждый из уровней отображает архитектуру системы с разной степенью детализации. Разные участники проекта могут использовать разные виды диаграмм для своих задач.
Рассмотрим, какие виды диаграмм бывают и кто их обычно использует.
Базовая модель C4 состоит из четырёх уровней.

Уровень 1. Диаграмма контекста — Context diagram

✏️ Диаграмма предоставляет общий обзор системы и её границ. Она показывает систему в окружении, выделяя основные внешние системы и пользователей, которые взаимодействуют с ней.
Её используют:
  • Бизнес-аналитики. Для демонстрации взаимодействия системы с внешними системами и пользователями.
  • Проектные менеджеры. Для определения основных стейкхолдеров и их взаимодействия с системой.
  • Архитекторы. Для общего представления системы и её окружения.
Пока вам не нужно погружаться в детали, мы будем использовать примеры автора модели с официального сайта. Они изображают архитектуру банковской системы.
Посмотрите, как это выглядит в целом. А когда перейдём к созданию диаграмм, мы вернёмся к примеру FitLife.
Пример диаграммы контекста для банковской системы. Автор — Саймон Браун. Источник: https://c4model.com. CC BY 4.0
Легенда диаграммы контекста. Источник: https://c4model.com. CC BY 4.0

Уровень 2. Диаграмма контейнеров — Container diagram

✏️ Диаграмма контейнеров показывает основные высокоуровневые контейнеры системы и взаимодействия между ними. Например, веб-приложения, базы данных, микросервисы.
Её используют:
  • Архитекторы. Для определения основных контейнеров системы и их взаимодействия.
  • Разработчики. Для понимания высокоуровневой структуры системы.
  • DevOps-инженеры. Для планирования развёртывания контейнеров и их взаимодействия.
Пример диаграммы контейнера для банковской системы. Автор — Саймон Браун. Источник: https://c4model.com. CC BY 4.0
Легенда диаграммы контейнера. Источник: https://c4model.com. CC BY 4.0

Уровень 3. Диаграмма компонентов — Component diagram

✏️ Диаграмма компонентов углубляется в один из контейнеров, показывая, из каких компонентов он состоит и как эти компоненты взаимодействуют друг с другом.
Её используют:
  • Разработчики. Для детального понимания внутренних структур контейнеров и их взаимодействий.
  • Архитекторы. Для проектирования внутренней структуры контейнеров.
  • Тестировщики. Для планирования тестирования компонентов и их взаимодействий.
Пример диаграммы компонентов для банковской системы. Автор — Саймон Браун. Источник: https://c4model.com. CC BY 4.0
Легенда диаграммы контейнера. Источник: https://c4model.com. CC BY 4.0

Уровень 4. Диаграмма кода — Code/classes diagram

✏️ Диаграмма кода отображает структуру кода в рамках одного из компонентов. Показывая классы или файлы и их взаимодействие.
Её используют:
  • Разработчики. Для детального проектирования и рефакторинга кода.
  • Тестировщики. Для понимания логики работы классов и планирования юнит-тестирования.
  • Архитекторы. Для верификации соответствия кода архитектурным требованиям.
Пример диаграммы кода для банковской системы. Автор — Саймон Браун. Источник: https://c4model.com. CC BY 4.0
Теперь вы знаете, как выглядят основные уровни модели C4. Кроме них, есть ещё три варианта диаграмм. Но их использовать необязательно.

Дополнительные виды диаграмм C4

С точки зрения C4, эти диаграммы необязательные. Их можно применять по необходимости. Например, если нужно объяснить поведение системы или отдельных компонентов в динамике. Или понять, как система будет развёрнута на оборудовании.

Диаграммы последовательностей — Dynamic diagrams

✏️ Диаграмма последовательностей показывает взаимодействие объектов в определённом временном порядке, акцентируя внимание на порядке сообщений между объектами.
Её используют:
  • Разработчики. Для понимания последовательности взаимодействий между объектами при выполнении операций.
  • Тестировщики. Для планирования тестирования сценариев взаимодействий.
  • Бизнес-аналитики. Для демонстрации функциональных требований и сценариев использования.
Пример диаграммы последовательностей для банковской системы. Автор — Саймон Браун. Источник: https://c4model.com. CC BY 4.0
Легенда диаграммы последовательностей. Источник: https://c4model.com. CC BY 4.0

Диаграммы развёртывания — Deployment diagrams

Эти диаграммы показывают физическое размещение программных артефактов на узлах развёртывания.
Кто использует:
  • Девопс-инженеры. Для планирования и управления развёртыванием системы.
  • Архитекторы. Для проектирования архитектуры развёртывания.
  • Системные администраторы. Для настройки и поддержки инфраструктуры развёртывания.
Пример диаграммы развёртывания для банковской системы. Автор — Саймон Браун. Источник: https://c4model.com. CC BY 4.0
Легенда диаграммы развёртывания. Источник: https://c4model.com. CC BY 4.0
Ещё есть третий вариант диаграмм — System Landscape diagram, или диаграмма системного ландшафта. Но её редко используют. Фактически это вариации диаграммы контекста, где убрали фокус с конкретной программной системы.
Вы можете прочитать более подробное описание диаграмм на сайте Саймона Брауна.

Задание 2

Какие виды диаграмм обязательны для C4? Выберите все правильные ответы.

Задание 3

Соотнесите вид диаграммы и то, что она описывает.
Взаимодействие системы с внешними системами и пользователями
Диаграмма контекста
Основные контейнеры системы и их взаимодействие
Диаграмма контейнеров
Внутренняя структура одного из контейнеров системы
Диаграмма компонентов
Детальная структура кода одного из компонентов
Диаграмма кода
Теперь вы знакомы с диаграммами C4. Пора переходить от теории к практике — разберёмся, как создавать такие диаграммы.

Как создавать диаграммы C4

Диаграммы C4 создают в пять шагов:
Рассмотрим процесс на примере системы управления фитнес-клубом FitLife. Мы пройдёмся по каждому из уровней C4 и создадим диаграммы, которые им соответствуют.

Шаг 1. Соберите требования и определите границы системы

На этом шаге:
  • Определите основные функции и компоненты системы.
  • Определите внешние системы и пользователей, которые будут взаимодействовать с вашей системой.
Например, FitLife — это система управления фитнес-клубом. Она автоматизирует процессы управления членством, расписанием занятий, обработки платежей и интеграции с внешними системами.
Система включает в себя веб-приложение и мобильное приложение для пользователей, административный интерфейс для управления, а также разные службы для обработки данных и взаимодействия с внешними API и банковскими системами.

Шаг 2. Создайте диаграмму контекста

На этом шаге:
  • Опишите вашу систему и её окружение.
  • Укажите внешние системы и пользователей, которые взаимодействуют с вашей системой.
На этом уровне мы покажем основные взаимодействия системы FitLife с внешними пользователями и системами. На диаграмме контекста нужно показать такие элементы:
  • User — пользователь системы фитнес-клуба, который использует функционал системы для управления своим членством и расписанием занятий.
  • Administrator — администратор, управляющий системой и осуществляющий поддержку пользователей.
  • FitLife System — основная система, которая управляет членством, расписанием занятий и обработкой платежей.
  • Third-Party API — внешний API для интеграции данных о фитнесе.
  • Bank System — внешняя банковская система для обработки платежей.
💡 Рисовать диаграммы вручную вам не придётся. Все диаграммы, которые вы увидите дальше в уроке, сделаны с помощью PlantUML. Вы создаёте текстовое описание системы, а инструмент отрисовывает по нему диаграмму. В следующем уроке мы расскажем, как им пользоваться.
Дополнили текстовое описание — указали, как элементы взаимодействуют. Затем оформили описание по требованиям PlantUML и загрузили его в инструмент. Получилась такая диаграмма:

Шаг 3. Создайте диаграмму контейнеров

На этом шаге:
  • Определите основные контейнеры внутри вашей системы. В C4 контейнеры — это приложения и хранилища данных.
  • Покажите взаимодействие между контейнерами и внешними системами.
На этом уровне мы детализируем основные контейнеры системы FitLife и их взаимодействия. На диаграмме контейнера нужно показать:
  • Web Application — веб-приложение, реализованное на Java с использованием Spring. Оно обрабатывает взаимодействие с пользователем.
  • Mobile Application — мобильное приложение, реализованное на Kotlin и Swift. Оно позволяет пользователям управлять своим членством.
  • Payment Service — сервис для обработки платежей, реализованный на Node.js.
  • Database — база данных на PostgreSQL, хранящая информацию о пользователях и расписании занятий.
  • Third-Party API — внешний API для интеграции данных о фитнесе.
  • Bank System — внешняя банковская система для обработки платежей.
Получилась такая диаграмма:

Шаг 4. Создайте диаграмму компонентов

На этом шаге:
  • Выберите один из контейнеров и детализируйте его внутреннюю структуру.
  • Определите основные компоненты внутри контейнера и их взаимодействие.
На этом уровне мы детализируем компоненты внутри веб-приложения FitLife. На диаграмме компонентов нужно показать:
  • AuthController — компонент, который обрабатывает аутентификацию и авторизацию пользователей.
  • UserController — компонент, который управляет профилями пользователей.
  • ScheduleController — компонент, который управляет расписаниями занятий.
  • PaymentController — компонент, который обрабатывает платежи.
  • Service Layer — слой бизнес-логики.
  • Repository Layer — слой доступа к данным.

Шаг 5. Создайте диаграмму кода

На этом шаге:
  • Детализируйте код одного из компонентов.
  • Покажите основные классы или файлы и их взаимодействие.
На этом уровне мы детализируем структуру кода компонента управления профилями пользователя. На диаграмме нужно показать:
  • User — класс, который представляет пользователя системы. У него есть атрибуты name и email. А ещё методы — register() и login().
  • Membership — класс, который представляет членство пользователя. Его атрибуты — type, startDate и endDate. Его методы — activate() и cancel().
  • Schedule — класс, который представляет расписание занятий. Его атрибуты — date и activity. Его методы — addActivity() и removeActivity().
Ещё описали, как классы взаимодействуют. В итоге получилась такая диаграмма:

Задание 4

Расположите этапы создания архитектурных диаграмм в правильном порядке.
Создание диаграммы компонентов
Шаг 4
Создание диаграммы контейнеров
Шаг 3
Создание диаграммы кода
Шаг 5
Сбор требований и определение границ системы
Шаг 1
Создание диаграммы контекста
Шаг 2

Анализ и интерпретация диаграмм C4

Итак, диаграммы C4 помогают создать чёткую и понятную архитектуру, упрощают коммуникацию между командами и стейкхолдерами, облегчают разработку и поддержку системы. На примере FitLife мы разобрали, как их создать.
Ещё важно уметь анализировать и интерпретировать эти диаграммы. Это поможет выявить проблемы, улучшить взаимодействия между компонентами и сделать так, чтобы все участники проекта понимали устройство архитектуры.
Есть четыре метода для анализа и интерпретации диаграмм C4. Рассмотрим каждый из них на примере системы управления фитнес-клубом FitLife.

Метод 1. Проверьте полноту и ясность

  • Убедитесь, что все основные элементы системы и их взаимодействия отражены на диаграммах.
  • Проверьте, что диаграммы понятны всем стейкхолдерам, включая тех, кто не имеет технического образования.
Диаграмма контейнеров FitLife. Нужно убедиться, что все основные контейнеры (WebApp, MobileApp, PaymentService и Database) отображены на диаграмме. И что взаимодействия между ними тоже показаны.
На остальных уровнях будет так же — нужно проверить, что диаграмма содержит ключевую информацию об этом уровне системы.

Метод 2. Выявите узкие места и потенциальные проблемы

  • Определите компоненты, которые могут стать узкими местами. Например, контейнеры с высокой нагрузкой.
  • Оцените взаимодействия между компонентами на предмет потенциальных проблем — например, задержек или сбоев в коммуникации.
Диаграмма контекста FitLife. Нужно понять, насколько система зависит от внешних API и банковских сервисов — могут ли сбои в API или банковской системе негативно повлиять на работу всей системы.
Диаграмма контейнеров FitLife. Нужно оценить нагрузку на PaymentService и Database. Высокая частота запросов к базе данных или к сервису обработки платежей может создать узкое место.
Диаграмма компонентов FitLife. Нужно проверить, что компоненты AuthController и PaymentController содержат необходимые меры безопасности для защиты данных пользователей и обработки платежей.
Диаграмма кода FitLife. Нужно оценить, насколько сложное взаимодействие между классами, и определить методы, которые могут стать узкими местами при высоких нагрузках.

Метод 3. Проанализируйте безопасность

  • Проверьте диаграммы на предмет потенциальных уязвимостей, связанных с доступом к данным и авторизацией пользователей.
  • Убедитесь, что критически важные компоненты защищены соответствующими механизмами безопасности.
Диаграмма контекста FitLife. Нужно проверить, что взаимодействие с банковской системой и API защищено и данные передаются по защищённым каналам.
Диаграмма контейнеров FitLife. Нужно проверить, что взаимодействия между WebApp, MobileApp и PaymentService защищены. Убедитесь, что данные пользователей в базе данных шифруются.
Диаграмма компонентов FitLife. Нужно убедиться, что компоненты AuthController и PaymentController содержат необходимые меры безопасности для защиты данных пользователей и обработки платежей.
Диаграмма кода FitLife. Нужно проверить, что классы, связанные с обработкой данных пользователей и платежей, содержат необходимые меры безопасности.

Метод 4. Оцените масштабируемость

  • Определите, какие компоненты системы могут требовать масштабирования при увеличении нагрузки.
  • Оцените возможности горизонтального и вертикального масштабирования компонентов.

Задание 5

Перед вами диаграмма компонентов FitLife. Какие компоненты отвечают за взаимодействие с базой данных?
Разные методы анализа помогают выявлять узкие места, улучшать взаимодействие между компонентами и обеспечивать безопасность и масштабируемость системы. На примере FitLife вы увидели, как эти методы можно применить на практике.
Осталось обсудить ещё один важный момент — как улучшать диаграммы на основе фидбэка. Разберём это прямо сейчас, а потом подведём итоги урока.

Как улучшать диаграммы C4 на основе обратной связи

Работа с диаграммами C4 — это не одноразовое событие, а процесс. По мере развития проекта, получения новых данных и обратной связи от команды и стейкхолдеров вам нужно будет обновлять и улучшать диаграммы. В этом разделе мы рассмотрим, как эффективно собирать и использовать обратную связь для улучшения диаграмм C4.
Есть четыре метода для получения обратной связи.

Метод 1. Ревью команды

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

Метод 2. Вовлекайте стейкхолдеров

Проводите презентации диаграмм для бизнес-экспертов и стейкхолдеров. Собирайте их мнения о том, насколько диаграммы понятны и какие аспекты можно улучшить.

Метод 3. Используйте инструменты для комментариев

Используйте онлайн-инструменты (например, Confluence, Google Docs) для размещения диаграмм и сбора комментариев. Поощряйте команду оставлять свои замечания и предложения прямо на диаграммах.

Метод 4. Анализируйте инциденты и проблемы

Анализируйте возникшие инциденты и проблемы в системе, чтобы выявить недостатки в архитектуре. Обновляйте диаграммы, чтобы учитывать полученные уроки и улучшения.

Сергей

Пример FitLife

Улучшение диаграммы контекста

Обратная связь: стейкхолдеры сообщили, что не хватает деталей о взаимодействии с внешними API.
Улучшение: добавили больше информации о типах данных и протоколах, которые используются для взаимодействия с внешними системами.

Новая версия диаграммы

Улучшение диаграммы контейнеров

Обратная связь: разработчики указали, что нужно более детально описать взаимодействия между контейнерами.
Улучшение: добавили описания типов данных, которые используются в коммуникации между контейнерами.

Новая версия диаграммы

Улучшение диаграммы компонентов

Обратная связь: разработчики отметили, что нужно больше информации о взаимодействии между слоями логики и данных.
Улучшение: добавили детали о вызовах между компонентами и слой сервисов.

Новая версия диаграммы

Улучшение диаграммы кода

Обратная связь: разработчики предложили добавить больше классов для улучшения детализации.
Улучшение: добавили новые классы для более полного представления логики приложения.

Новая версия диаграммы

Задание 6

Выберите все методы получения и обработки обратной связи, которые эффективны при работе с диаграммами C4.

Итоги

Чтобы поддерживать и развивать код проекта было проще, нужно создать понятную и чёткую визуализацию архитектуры.
C4 — это многоуровневая модель для описания архитектуры систем, которую разработал Саймон Браун. Она состоит из четырёх уровней абстракции:
  • Context diagrams (диаграммы контекста) — показывают, как система выглядит в целом.
  • Container diagrams (диаграммы контейнеров) — показывают высокоуровневые технические строительные блоки (приложения, микросервисы, базы данных).
  • Component diagrams (диаграммы компонентов) — показывают компоненты внутри отдельного контейнера.
  • Code/classes diagrams (диаграммы кода) — показывают, как реализован отдельный компонент.
К плюсам C4 относят простоту и чёткость, универсальность, гибкость. Ещё у модели низкий порог входа — с ней удобно работать и техническим специалистам, и бизнесу. Но у модели есть и минусы: создание и поддержка диаграмм C4 требует времени, а для их разработки нужно использовать специализированные инструменты. На небольших проектах не все уровни модели будут востребованы.
Чтобы использовать модель, нужно пройти такие шаги: сначала соберите требования и определите границы системы, затем в порядке очереди создайте диаграмму контекста, диаграмму контейнеров, диаграмму компонентов и диаграмму кода.
Чтобы диаграммы приносили пользу, они должны адекватно отражать систему. Тогда на их основе вы сможете выявлять проблемы. Для анализа и интерпретации диаграмм используют четыре метода: проверку полноты и ясности диаграммы, выявление узких мест и потенциальных проблем системы, анализ безопасности и оценку масштабируемости.
Работа с диаграммами C4 — это не одноразовое событие, а процесс. Вовлекайте команду в работу над диаграммами. Есть четыре метода получения обратной связи: ревью команды, вовлечение стейкхолдеров, использование инструментов для комментирования, анализ проблем и инцидентов.
В следующем уроке расскажем про инструменты для создания и поддержания документации — PlantUML и MkDocs.

Дополнительные материалы

В начале урока мы перечислили основные подходы к визуализации архитектуры. Если вы хотите узнать о них больше, вот несколько хороших ресурсов: