Нотация C4: полный гайд с примерами и разбором ошибок

Конспект статьи. Автор оригинала: Екатерина Ананьева (katherine_a, GetAnalyst)

Расширенная версия популярной статьи автора о C4 с новыми примерами и типичными ошибками новичков.

Основы

Нотацию создал Саймон Браун. Не обязательно рисовать все четыре уровня — только нужные команде. Элементов немного: человек, система, контейнер, компонент, связи. Для брокеров, БД и внешних систем используются теги и стили.

Правила оформления

• У каждого элемента — название, тип и описание.
• Для контейнеров и компонентов — технология.
• Стрелки однонаправленные и подписанные, между контейнерами указан протокол.

Context

Пользователи и интеграции без внутреннего устройства. Типичная ошибка — рисовать внешнюю систему фигурой человека. Цвета допустимы, но объясняются в легенде. Для набора равноправных систем — диаграмма System Landscape.

Container

Контейнер — то, что отдельно запускается и разворачивается. Библиотеки, классы, реплики и серверы — не контейнеры. Если сервисов много — несколько диаграмм вместо одной перегруженной.

Component и Code

Компоненты — контроллеры, сервисы, репозитории, клиенты внешних систем внутри одного контейнера; показывать только архитектурно значимое. Уровень Code — UML-классы и ER-схемы, обычно не нужен.

Инструменты

Основной выбор автора — draw.io; Structurizr удобен для генерации из кода и работы с нейросетями; PlantUML допустим. В статье есть промпт для генерации Structurizr DSL и задача на поиск ошибок.