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.

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

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

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.

@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

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.

@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

Grouping and Alternatives

Use group to visually group interactions and alt / else to model conditional flows.

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

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

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.

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

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.