Mastering PlantUML: From Basics to Advanced Sequence Diagrams

Introduction

When designing systems I often need sequence diagrams. Traditional tools like draw.io become cumbersome for complex diagrams, so I turned to PlantUML, an open‑source text‑based diagramming tool.

What is PlantUML?

PlantUML is a multi‑functional component that quickly creates various UML diagrams from simple textual descriptions, including sequence, use‑case, class, object, activity, component, deployment, state, and more.

Beyond UML, PlantUML also supports JSON, YAML, EBNF, architecture diagrams, etc. Because diagrams are defined in plain text, they can be version‑controlled and embedded directly in source code.

Quick Start

PlantUML Plugins

Popular IDEs such as Visual Studio Code, IntelliJ IDEA, and Eclipse provide PlantUML plugins with real‑time preview, syntax highlighting, and export features.

Hello World

The simplest diagram can be written using the arrows

->

,

-->

and

:

to pass messages between participants.

<code>@startuml
老张 -> 老王 : 老王，你好啊
老王 --> 老张: 老张，你好啊

老张 -> 老王: 最近有空一起喝茶
老张 <-- 老王: OK
@enduml</code>

Sequence Diagram Syntax

Declaring Participants

Use the

participant

keyword to declare participants; the order defines the default display order. Other keywords such as

actor

,

boundary

,

control

,

entity

,

database

,

collections

,

queue

are also supported. Participants can be renamed with the

as

keyword.

<code>@startuml
participant Participant as Foo
actor       Actor       as Foo1
boundary    Boundary    as Foo2
control     Control     as Foo3
entity      Entity      as Foo4
database    Database    as Foo5
collections Collections as Foo6
queue       Queue       as Foo7
@enduml</code>

Message Types

Synchronous message:

A -> B: text

Asynchronous message:

A ->> B: text

Return message:

A <-- B: text

Self‑call:

A -> A: text

Lifelines and Activation Bars

Lifelines represent an object's existence over time; activation bars show when an object is active. Keywords

activate

,

deactivate

, and

destroy

control these bars.

<code>@startuml
participant User
User -> A: DoWork
activate A
A -> B: << createRequest >>
activate B
B -> C: DoWork
activate C
C --> B: WorkDone
destroy C
B --> A: RequestCreated
deactivate B
User -> User: Done
deactivate A
@enduml</code>

Grouping and Alternatives

Use

group

to visually group interactions and

alt

/

else

to model conditional flows.

<code>group Login Process
A -> B: Request
...
end group

alt Success
A -> B: OK
else Failure
A -> B: Error
end</code>

Notes and Colors

Notes add explanatory text and can be positioned with

note left of

,

note right of

, or

note over

. Colors can be assigned directly with

#color

or globally via

skinparam

.

<code>@startuml
actor User #Green
participant Service #B4A7E5
User -[#red]> Service: Message
activate Service #Blue
@enduml</code>

Conclusion

PlantUML offers a Markdown‑like, text‑based experience that is easy to learn, version‑control friendly, and integrates with many IDEs, making it a powerful tool for creating clear and maintainable diagrams.