Прежде чем приступать к конкретным архитектурным схемам, таким как модели C4 или временные линии последовательности, необходимо понимать основные правила, регулирующиеПрактическое руководство по PlantUML. PlantUML использует чистую, высокоинтуитивную систему текстовой нотации. Как только вы поймете, как движок открывает документы, назначает имена структурным компонентам и направляет линии соединений, создание любой сложной схемы системы станет полностью естественным.
Этот краткий обзор охватывает общие механики структурного синтаксиса, применимые ко всем типам диаграмм PlantUML внутри рабочей среды VPasCode.
1. Обязательные обертки документа
Каждый блок кода PlantUML должен начинаться и заканчиваться явными тегами фреймворка. Эти теги сообщают парсеру VPasCode запустить правильный движок отображения в вашем окне предварительного просмотра:
@startuml— Эта точная строка должна быть помещена в самое начало вашего скрипта. Ничто не должно предшествовать ей.@enduml— Эта точная строка должна быть помещена в самое конец вашего скрипта, обозначая завершение блока данных диаграммы.
Любой код, написанный вне этих двух маркеров, будет безопасно проигнорирован компилятором, или может вызвать предупреждение проверки синтаксиса в панели диагностики вашей рабочей среды.
2. Объявление элементов: идентификаторы и отображаемые метки
При моделировании программной системы вы будете создавать различные структурные элементы, такие как компоненты, базы данных, участники или микросервисы. В PlantUML вы можете явно объявить элемент, определив его тип, внутренний сокращенный идентификатор и удобное для пользователя имя, заключенное в кавычки:
компонент microservice_id как "API обработки платежей"
база_данных db_id как "SQL-запросы пользовательских транзакций"Почему это является лучшей практикой: Использование короткого, чистого внутреннего идентификатора (например,microservice_id) значительно ускоряет рисование линий отношений в будущем. Если вам когда-либо понадобится изменить внешнюю метку с «API обработки платежей» на «Глобальный сервис оплаты», вам нужно будет изменить только одну строку кода, а не обновлять десятки строк в вашем скрипте.
3. Освоение стрелок отношений и направления маршрутизации
Соединения между узлами системы рисуются с использованием комбинаций тире (-) и угловых скобок (>). Длина тире и наличие направляющих ключевых слов дают вам неявный контроль над тем, как автоматизированный движок компоновки масштабирует вашу диаграмму:
- Базовые соединения:
A --> Bрисует стандартную направленную стрелку, указывающую от элемента A прямо к элементу B. - Пунктирные линии зависимостей: Замена тире точками создает пунктирную линию, которая является отраслевым стандартом для обозначения асинхронных зависимостей или сетевых вызовов:
A ..> B. - Принудительная ориентация компоновки: Хотя движок компоновки автоматически разделяет блоки, вы можете явно задать ориентацию, вставив ключевое слово направления непосредственно в строку стрелки:
A -up-> B(Принудительно отображает B выше A)A -down-> B(Принудительно отображает B ниже A)A -left-> B(Принудительно отображает B слева от A)A -right-> B(Принудительно отображает B справа от A)
4. Добавление контекста в строке: метки и комментарии к коду
Четкая документация в значительной степени зависит от добавления соответствующего контекста вокруг ваших визуальных линий и текстовых скриптов:
Метки линий соединения
Вы можете добавить пояснительный текст непосредственно к любой линии соединения, добавив двоеточие (“:) сразу после вашего сопоставления отношений:
client_id --> api_id : "HTTPS POST /v1/checkout"Написание комментариев к коду
Если вы хотите оставить административное примечание, кредит на дизайн или пояснение архитектуры внутри вашего скриптового файла, не отображая визуальный блок на холсте, используйте одинарную кавычку (“'). Это сообщает движку пропустить анализ этой строки полностью:
' TODO: Нам нужно обновить этот блок границы, как только завершится миграция DevOps
[Устаревший монолит] --> [Новый микросервис]Теперь, когда вы знакомы с глобальными обертками синтаксиса, объявлениями компонентов и параметрами стрелок направления PlantUML, вы полностью готовы начать создание сложных системных форм. Перейдите на следующую страницу, чтобы открыть нашу коллекцию Архитектура и диаграммы высокого уровня!