Справочник по C4 Model в PlantUML

Подключение библиотек

Для работы с C4 необходимо подключить соответствующие файлы. Можно подключить все сразу или только нужный уровень детализации (рекомендуется для ускорения рендеринга).

' Подключить все (включает все уровни)
!include C4.puml

' Или подключить только нужный уровень:
!include C4_Context.puml    ' Системный контекст (Level 1)
!include C4_Container.puml  ' Контейнеры (Level 2)
!include C4_Component.puml  ' Компоненты (Level 3)
!include C4_Deployment.puml ' Развертывание (Level 4)
!include C4_Dynamic.puml    ' Динамические диаграммы

Элементы диаграммы

Все элементы имеют базовый синтаксис: Макрос(alias, "Название", "Технология", "Описание", $tags="тег", $sprite="иконка").

Person (Люди и роли)

Макрос Описание

Person(alias, "Название", "Описание")

Внутренний пользователь или роль.

Person_Ext(…​)

Внешний пользователь (отображается с пунктирной рамкой/другим цветом).

System (Системы)

Макрос Описание

System(alias, "Название", "Технология", "Описание")

Внутренняя программная система.

System_Ext(…​)

Внешняя система (например, сторонний API).

SystemDb(…​)

Система, являющаяся базой данных.

SystemQueue(…​)

Система, являющаяся очередью сообщений.

Container (Контейнеры)

Макрос Описание

Container(alias, "Название", "Технология", "Описание")

Внутренний контейнер (приложение, микросервис).

Container_Ext(…​)

Внешний контейнер.

ContainerDb(…​)

Контейнер базы данных.

ContainerQueue(…​)

Контейнер очереди сообщений.

Component (Компоненты)

Макрос Описание

Component(alias, "Название", "Технология", "Описание")

Внутренний компонент.

Component_Ext(…​)

Внешний компонент.

ComponentDb(…​)

Компонент базы данных.

ComponentQueue(…​)

Компонент очереди сообщений.

Deployment Node (Узлы развертывания)

Используются для отображения физической инфраструктуры. Поддерживают вложенность.

Макрос Описание

Deployment_Node(alias, "Название", "Технология", "Описание")

Базовый узел развертывания (сервер, кластер, ЦОД).

Deployment_Node_L(…​)

Узел с принудительным выравниванием по левому краю (полезно для раскладки).

Deployment_Node_R(…​)

Узел с принудительным выравниванием по правому краю.

Связи (Relationships)

Связи показывают взаимодействие между элементами.

Направленные связи

Макрос Направление

Rel(from, to, "Название", "Технология")

Автоматическое направление (выбирается движком).

Rel_U(from, to, …​)

Вверх (Up).

Rel_D(from, to, …​)

Вниз (Down).

Rel_L(from, to, …​)

Влево (Left).

Rel_R(from, to, …​)

Вправо (Right).

Двусторонние и скрытые связи

Макрос Описание

BiRel(from, to, "Название", "Технология")

Двусторонняя связь (стрелки с обоих концов).

Rel(from, to, "", "") + hide link

Невидимая связь. Используется для принудительного управления раскладкой без отображения стрелки.

Границы (Boundaries)

Границы используются для группировки элементов. В C4 для Deployment диаграмм роль границ выполняют сами Deployment_Node.

Enterprise_Boundary(eb, "Название компании") {
    System_Boundary(sb, "Название системы") {
        Container_Boundary(cb, "Название приложения") {
            Component(c1, "Компонент 1")
        }
    }
}

Стилизация и Теги

Позволяют менять внешний вид элементов и связей без изменения базовых skinparam.

Теги (Tags)

' Добавить тег для элемента
AddElementTag("fallback", $bgColor="#c0c0c0", $fontColor="#ffffff", $borderColor="#999999")

' Добавить тег для связи
AddRelTag("fallback", $textColor="#c0c0c0", $lineColor="#c0c0c0", $lineStyle="dashed")

' Применение тега
System(sys, "Система", $tags="fallback")
Rel(sys1, sys2, "связь", $tags="fallback")

Глобальное обновление стилей

' Изменить стиль всех элементов определенного типа
UpdateElementStyle("person", $bgColor="#e0f7fa", $borderColor="#006064")
UpdateElementStyle("container", $bgColor="#e8f5e9")

' Изменить стиль всех связей
UpdateRelStyle($textColor="#333333", $lineColor="#555555", $lineThickness="2")

Макет, Легенда и Свойства

Легенда

Директива Описание

LAYOUT_WITH_LEGEND()

Размещает легенду в правом верхнем углу (внутри холста).

SHOW_LEGEND()

Размещает легенду внизу диаграммы (рекомендуется).

HIDE_LEGEND()

Скрывает легенду.

Свойства (Properties)

Добавление таблиц свойств внутрь элементов (например, для указания IP, версий, портов).

' Убрать стандартный заголовок "Properties"
WithoutPropertyHeader()

' Добавить свойство внутрь Deployment_Node или Container
Deployment_Node(node, "Сервер", "Ubuntu") {
    AddProperty("IP", "192.168.1.10")
    AddProperty("CPU", "8 vCPU")
    Container(app, "App", "Java")
}

Управление раскладкой (Layout)

' Масштабирование
scale 1.5
scale 2000 width

' Направление графа (по умолчанию top to bottom)
top to bottom direction
left to right direction

' Альтернативные движки раскладки (если стандартный дает сбои)
!pragma layout smetana
!pragma layout elk

' Расстояния между элементами
skinparam nodesep 100  ' расстояние между узлами на одном уровне
skinparam ranksep 150  ' расстояние между уровнями

Полезные приемы (Tips & Tricks)

Принудительное выравнивание в одну линию

Используйте блок together, чтобы заставить PlantUML расположить элементы на одном уровне (rank).

together {
    Person(user1, "Пользователь 1")
    Person(user2, "Пользователь 2")
}

Группировка связей

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

Использование спрайтов

PlantUML и C4 поддерживают встроенные спрайты (OpenIconic, Material, etc.).

Person(user, "Пользователь", $sprite="person")
System(web, "Web App", $sprite="globe")

Список доступных спрайтов: https://plantuml.com/sprite

Полный пример (Deployment Diagram)

Diagram