О PlantUML

Давным-давно я уже писал про PlantUML. Это совершенно шикарный инструмент для описания диаграмм текстом. В первую очередь UML диаграмм, но не только.

С тех пор ничего не изменилось. PlantUML остаётся моим основным инструментом создания диаграмм. Чаще всего в виде онлайн редактора planttext.com.

Вот некоторые хитрости использования PlantUML.

Чаще всего я рисую диаграммы развёртывания. Потому что чаще всего мне нужно визуализировать, что где находится и как друг с другом взаимодействует. Иногда бывают полезны диаграммы последовательности. Но о них как-нибудь в другой раз.

Я предпочитаю явно использовать ключевые слова component, actor, чем использовать более короткий синтаксис со скобочками.

' вот так
component A
actor B

' а не так
[C]
:D:

Если просто накидать компоненты, то они выстраиваются рядами. Слева направо, сверху вниз.

component A
component B
component C
component D

Я сначала накидываю компоненты, а потом рисую связи. Порядок объявления компонент почти не влияет на порядок их расположения. А вот порядок объявления связей — влияет.

Стрелка с одним «минусом» (->, .>, ~>, =>) всегда старается нарисовать связь слева направо. И расположить компоненты соответствующим образом, в одном ряду.

component A
component B

A -> B

Если таким образом попытаться соединить более пары компонент, они будут размещены в одном ряду. Но вот стрелка может превратиться в дугу.

component A
component B
component C

A -> B
A -> C

Хоть в PlantUML и есть возможность указать направление стрелок, лучше на них не полагаться. Это лишь рекомендации. Лучше полагаться на изложенные здесь правила.

Поэтому, если нужна стрелка справа налево, поставьте компоненты в связи в соответствующем порядке

component A
component B
component C

A -> B
C <- A

Стрелка с двумя «минусами» (-->, ..>, ~~>, ==>) рисует вертикальную связь, сверху вниз, на один ряд вниз.

component A
component B

A --> B

Можно и в снизу вверх. Поставьте компоненты в связи в нужном порядке.

component A
component B

A --> B
A <-- B

Стрелка с тремя «минусами» (--->, ...>, ~~~>, ===>) рисует вертикальную связь на два ряда вниз. Чем больше «минусов» тем на большее число рядов вниз.

component A
component B
component C
component D

A --> B
A ---> C
A ----> D

Поиграть с длиной стрелок, бывает, помогает, чтобы навести порядок на диаграмме. Или добавить беспорядок.

component A
component B
component C
component D

A --> B
B --> C
C --> D
A ---> C 
B ---> D
A ----> D

Для борьбы с беспорядком лучше объединить компоненты в группы. Все эти cloud, folder, frame, node, package, rectangle специально созданы, чтобы быть контейнером (смысловым) для других элементов. Хотя контейнером на диаграмме развёртывания может быть всё что угодно. Прекрасно, что контейнеры могут быть анонимными.

cloud {
    component A
    component B
    A -> B
}
node {
    component C
    component D
    C -> D
}

A --> C
B --> D

Связи можно проставлять и между контейнерами (неанонимными), но это не очень красиво выглядит.

PlantUML по умолчанию генерирует картинки, пригодные для веба. Но для презентаций хочется картинку побольше/почётче. Достаточно добавить scale 2 в начало диаграммы. Или же взять изображение в SVG.

scale 2

component A
component B

A -> B

PlantUML написан на Java, а для генерации изображений по графам использует Graphviz. Не самый удобный стек, чтобы тащить его повсюду.

Но в PlantUML, в стандартном сервлете, очень интересно используются URL. Фактически в URL закодирован сам исходный текст диаграммы. Поэтому URL картинки с planttext.com вполне можно вставить в соответствующее поле на http://www.plantuml.com/plantuml/, и увидеть исходный текст.

Поэтому, если у вас уже есть где-то работающий PlantUML сервлет, легко добавить поддержку PlantUML диаграмм в любой вики-движок (или что там у вас). Например, в Redmine. Главное, правильно закодировать URL картинки.

Если хочется чего-то попроще и без Java, то есть альтернативная описывалка диаграмм на Python: diagrams.mingrammer.com.

Или на JavaScript (для встраивания в веб страницы): mermaid.

Но обе альтернативы всё же менее функциональны, чем PlantUML.

А очень продвинутый уровень использования PlantUML позволяет добавлять красивые иконки и делать диаграммы, непохожие на дефолтный PlantUML. Примеры и туториалы смотрите на The Hitchhiker’s Guide to PlantUML.

Спасибо Илье за ссылки.