Диаграмма C4 — это стандартизированный метод визуализации архитектуры, предназначенный для моделирования программных систем на нескольких уровнях структурной абстракции. Встроенный нативно в Mermaid.js, c4двигатель следует четырем основным уровням модели C4: Контекст (макроэкосистема), Контейнеры (приложения, службы и базы данных), Компоненты (внутренние структурные модули), и Динамические взаимодействия. Этот инструмент устраняет сложности с кастомной стилизацией CSS, применяя единообразные, готовые к презентации архитектурные блоки на основе ваших текстовых объявлений.
Понимание абстракций и ключевых слов диаграмм C4
Mermaid поддерживает четыре специализированных заголовка инициализации диаграмм в зависимости от уровня детализации, необходимого для вашей системы:
C4Context: Фокусируется на общей картине, отображая пользователей, основные программные экосистемы и внешние зависимости высокого уровня.C4Container: Приближается на один уровень, чтобы разложить автономные приложения, интерфейсы фронтенда, микросервисы, системы хранения баз данных и очереди.C4Component: Проникает глубоко внутрь контейнера, чтобы продемонстрировать внутренние модули на уровне кода, такие как контроллеры, службы и репозитории.C4Dynamic: Фокусируется на отслеживании взаимодействий данных во время выполнения или пошаговой последовательности транзакций между блоками инфраструктуры.
Базовая структура синтаксиса
Каждая диаграмма C4 начинается с конкретного заголовка уровня, за которым следует необязательное утверждение заголовка и макрокомпоненты, разделённые запятыми. Параметры находятся в скобках, строки ограничены двойными кавычками.
C4Context
title "Чертеж контекста системы для ядра интернета"
Person(customer, "Клиент банка", "Клиент банка с личными счетами.")
System(banking_system, "Система интернет-банкинга", "Позволяет клиентам просматривать информацию о счетах.")
Rel(customer, banking_system, "Использует", "HTTPS")
Полная макро-классификация элементов C4
Библиотека Mermaid C4 предоставляет обширный набор специализированных макросов, позволяющих чётко различать внутренние компоненты, внешние системы и слои баз данных на всех уровнях абстракции.
1. Макросы персоны и пользователя
Person(псевдоним, метка, [описание], [спрайт], [теги]): Моделирует внутреннего человека-пользователя или заинтересованного лица.Person_Ext(псевдоним, метка, [описание], [спрайт], [теги]): Моделирует внешнего пользователя (например, стороннего поставщика или аудитора), находящегося за пределами основных организационных границ.
2. Макросы системы и экосистемы программного обеспечения
System(псевдоним, метка, [описание], [спрайт], [теги]): Представляет внутреннюю группу программных систем, находящуюся под вашим прямым управлением.System_Ext(псевдоним, метка, [описание], [спрайт], [теги]): Моделирует важную внешнюю систему программного обеспечения, управляемую сторонней организацией (например, поставщики идентификации, основные банковские ведомости).SystemDb(псевдоним, метка, [описание], [спрайт], [теги]): Отображает блок хранилища данных на уровне системы в форме цилиндра.SystemDb_Ext(псевдоним, метка, [описание], [спрайт], [теги]): Отображает внешний уровень базы данных, управляемый сторонней организацией.
3. Макросы слоя контейнеров (уровень C4Container)
Container(псевдоним, метка, технология, [описание], [спрайт], [теги]): Моделирует отдельное исполняемое приложение, сервер API или интерфейс фронтенда.ContainerDb(псевдоним, метка, технология, [описание], [спрайт], [теги]): Отображает оболочку базы данных реляционного или нереляционного типа на уровне контейнера.Container_Ext(псевдоним, метка, технология, [описание], [спрайт], [теги]): Представляет внешний облачный контейнер или сервис приложения.ContainerDb_Ext(псевдоним, метка, технология, [описание], [спрайт], [теги]): Представляет внешний управляемый уровень хранения облачной базы данных.
4. Макросы слоя компонентов (уровень C4Component)
Component(псевдоним, метка, технология, [описание], [спрайт], [теги]): Отображает внутренний модуль на уровне кода, слой или контроллер класса.ComponentDb(псевдоним, метка, технология, [описание], [спрайт], [теги]): Моделирует внутреннюю систему хранения микрокомпонентов или систему кэширования файлов низкого уровня.
Границы контейнеров и структурная оболочка
Для обозначения зон безопасности, корпоративных брандмауэров или логических границ приложения Mermaid предоставляет три специализированных оболочки в виде скобок. Элементы, вложенные внутрь, визуально группируются вместе.
Enterprise_Boundary(псевдоним, метка) { ... }: Оборачивает высокий уровень систем внутри широкой визуальной границы, представляющей общую периметр корпоративной или компании инфраструктуры.System_Boundary(псевдоним, метка) { ... }: Группирует тесно связанные прикладные контейнеры или микросервисы внутри единого блока программной экосистемы.Container_Boundary(псевдоним, метка) { ... }: Изолирует компоненты на уровне кода внутри одного слоя контекста модуля приложения.
Расширенные операторы направленных отношений
Соединение блоков в диаграммах C4 зависит от Relмакроса или его явно направленных вариаций. Вместо передачи необработанных линий диаграммы потока, вы отслеживаете соединения семантически, объявляя векторы технологий непосредственно внутри логических блоков.
| Синтаксический токен отношения | Направление визуальной стрелки | Контекст выравнивания использования |
|---|---|---|
Rel(от, к, метка, [техн]) |
Динамический / Автоматизированный | Отношение по умолчанию. Позволяет алгоритму размещения определить лучший путь линии. |
BiRel(от, к, метка, [техн]) |
Двунаправленный (<–>) | Указывает на двусторонние взаимодействия, дуплексные протоколы или синхронные процессы. |
Rel_Back(от, к, метка, [техн]) |
Обратная стрелка сверху (<–) | Рисует отношение вперед в логике кода, но переворачивает видимую визуальную стрелку назад. |
Rel_Neighbor(от, к, метка, [техн]) |
Предпочтение горизонтального расположения | Принуждает целевой узел оставаться непосредственно рядом с исходным узлом на одной и той же горизонтальной строке. |
Rel_Down(от, к, метка, [техн]) / Rel_D(...) |
Прямо вниз (v) | Принуждает вертикальные потоки данных идти вниз к слоям базы данных или последующим фоновым процессам. |
Rel_Up(от, до, метка, [техн]) / Rel_U(...) |
Прямо вверх (^) | Принуждает маршруты отношений идти прямо вверх к компонентам пользовательского интерфейса клиента. |
Rel_Left(от, до, метка, [техн]) / Rel_L(...) |
Прямо влево (<-) | Направляет пути горизонтально влево от элемента холста. |
Rel_Right(от, до, метка, [техн]) / Rel_R(...) |
Прямо вправо (->) | Направляет пути горизонтально вправо от элемента холста. |
Пользовательская динамическая стилизация и тегирование (переопределение форм C4)
Чтобы отметить устаревшие приложения, выделить премиум-системы или подчеркнуть безопасные потоки данных, вы можете создавать пользовательские стили с помощью механизма тегов элементов. Вы определяете матрицу свойств тегов в верхней части документа, а затем добавляете эти метки к определениям элементов.
Ключевые слова для изменения стилизации:
UpdateElementStyle(имяЭлемента, bgColor, цветШрифта, [цветГраницы], [теневаяЗаливка]): Прямая замена цветовой палитры фона по умолчанию для явно заданного элемента.UpdateRelStyle(от, до, цветЛинии, цветТекста): Явно указывает на маршрут соединения для изменения цвета линий или описания соединения.
C4Context
title "Пользовательская цветовая схема глобальной архитектурной карты"
System(legacy_api, "Устаревший ядро биллинга", "Обрабатывает продление подписок.")
System(modern_portal, "Портал панели управления клиентов", "Современный веб-движок для пользовательского интерфейса.")
%% Прямые настройки цвета
UpdateElementStyle(legacy_api, "#d9534f", "#ffffff", "#c9302c")
UpdateElementStyle(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Реальный чертеж: Карта контейнера границ предприятия для системы электронной коммерции
Этот всесторонний многоуровневый чертеж контейнера отслеживает онлайн-экосистему электронной коммерции. Он изолирует внутренние основные серверы с помощью System_Boundary блочного контейнера, реализует внешние облачные ретрансляторы уведомлений через System_Ext, отображает внутренние хранилища реляционных баз данных вместе с внешними микросервисами отслеживания и фиксирует каналы связи с использованием явных параметров стека технологий.
C4Container
title "Чертеж контейнера для корпоративной платформы электронной коммерции"
Person(customer, "Онлайн-покупатель", "Просматривает элементы каталога и добавляет товары в цифровую корзину.")
System_Ext(payment_gateway, "Сервис API Stripe", "Внешний хранилище кредитных карт и процессинговый движок.")
System_Boundary(ecommerce_scope, "Периметр ядра электронной коммерции") {
Container(frontend_app, "Веб-приложение для магазина", "Next.js, React", "Доставляет статические ресурсы и обрабатывает сессии корзины пользователей.")
Container(checkout_service, "Микросервис оформления заказа", "Node.js, Express", "Обрабатывает рабочие процессы корзины и рассчитывает налог.")
ContainerDb(order_db, "База данных журнала заказов", "PostgreSQL", "Хранит исторические строки транзакций и защищённые записи журнала.")
}
%% Архитектурные пути взаимодействия
Rel(customer, frontend_app, "Просматривает продукты и размещает заказы с помощью", "HTTPS/Браузер")
Rel_Down(frontend_app, checkout_service, "Отправляет транзакции с данными о покупке через", "JSON/REST API")
Rel_Right(checkout_service, order_db, "Сохраняет транзакционные состояния внутри", "SQL/JDBC-соединение")
Rel_Left(checkout_service, payment_gateway, "Авторизует вызовы токенизированных платежей с помощью", "Безопасный TLS/HTTPS API")
Распространённые синтаксические ошибки и системные ограничения
При компиляции чистых диаграмм C4 для программных фреймворков обратите внимание на эти параметры выполнения, чтобы избежать сбоя диаграммы:
- Форматирование разделителей запятыми: В отличие от почти всех других схем Mermaid, макросы C4 требуют строгих запятых между параметрами:
Person(id, "Метка", "Описание"). Пропуск разделительной запятой полностью сломает построитель макета. - Зарезервированные кавычки для меток: Поля отображения, теги технологий и блоки описаний внутри макросов *должны* быть заключены в чёткие двойные кавычки. Вставка необработанного текста в поля без кавычек вызывает сбои при разборе.
- Порядок вложенности границ: При обёртывании элементов внутри
System_BoundaryилиEnterprise_Boundaryблока, вы должны явно очистить содержимое рабочей области, используя стандартные фигурные скобки{ }. Оставление открытой скобки границы или неправильное её соответствие нарушает отрисовку макетов. - Динамическая инициализация псевдонимов: Вы не можете создавать связи (
Rel) к идентификатору псевдонима, который не был явно инициализирован блоком макроса элемента выше него. Держите поток объявления последовательным сверху вниз.