Master PlantUML: From Quick Start to Advanced Sequence Diagram Techniques

Introduction

Hello, I am Lao San. While designing systems I needed many sequence diagrams. I used draw.io and Yuque before, but they struggled with complex diagrams, so I looked for a more professional tool. A colleague recommended PlantUML, which turned out to be very handy.

What is PlantUML?

PlantUML is a multi‑functional component that quickly creates diagrams using a simple, intuitive textual language.

PlantUML is an open‑source tool that lets you describe UML diagrams—such as sequence, use‑case, class, object, activity, component, deployment, and state diagrams—using plain text. It also supports other charts like JSON, YAML, EBNF, and architecture diagrams. Because diagrams are text‑based, they integrate well with source code, version control, and collaborative workflows.

Quick Start

PlantUML Plugins

Popular IDEs and editors provide PlantUML plugins (e.g., Visual Studio Code, IntelliJ IDEA, Eclipse) offering real‑time preview, syntax highlighting, and export features. VS Code is lightweight, while IDEA offers a richer experience at the cost of higher memory usage.

IntelliJ IDEA – "PlantUML integration" plugin

VS Code – PlantUML extension

Hello World!

Here is the simplest example using the arrow symbols ->, --> and : to pass messages without explicitly declaring participants.

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

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

PlantUML Sequence Diagram Syntax

Below are key syntax elements for sequence diagrams.

Declaring Participants

Use the participant keyword to declare participants, which determines the default display order. You can also use actor, boundary, control, entity, database, collections, and queue to set different shapes.

@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

You can rename participants with the as keyword.

Colors can be set using # followed by a hex code.

@startuml
actor Bob #blue
participant Alice #SkyBlue
participant "I have a really
long name" as L #00f00
@enduml

Message Passing

Synchronous message:

A -> B: text

A -> B: 同步消息文本

Asynchronous message:

A ->> B: text

A ->> B: 异步消息文本

Return message:

A <-- B: text

A <-- B: 返回消息文本

Self‑call:

A -> A: text

A -> A: 自调用

Lifelines and Activation Bars

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

@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
A -> User: Done
deactivate A
@enduml

Nested activation bars and colors can be used for internal calls.

@startuml
participant User
User -> A: DoWork
activate A #FFBBBB
A -> A: Internal call
activate A #DarkSalmon
@enduml

Automatic activation/deactivation can be expressed with A->B++ and A <--B--.

Grouping and Alternatives

Use group to logically group interactions and alt / else for conditional flows.

group GroupName
A -> B: Message
...
end group

alt condition1
A -> B: Message when condition1 true
else condition2
A -> B: Message when condition2 true
end

Notes

Notes add explanatory text and can be positioned with note left of, note right of, or note over. Background colors can highlight notes.

@startuml
participant Alice
note left of Alice #aqua
This is displayed left of Alice.
end note
@enduml

Colors

Colors can be set directly on elements or globally with skinparam.

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

@startuml
skinparam ActorBorderColor #DarkOrange
skinparam ParticipantBackgroundColor #SkyBlue
actor User
participant Service
@enduml

Complete Example

The following diagram shows a login flow that adds Google OAuth to an existing system.

@startuml
skinparam ParticipantBackgroundColor #DeepSkyBlue
actor 用户 as c #DeepSkyBlue
participant "客户端" as client
participant "服务网关" as ga
participant "用户服务" as user
database "数据库" as DB #DeepSkyBlue
participant "Google服务" as google #LightCoral

activate c #DeepSkyBlue
activate client #DeepSkyBlue
c->client:用户登录

group Google登录客户端流程
  client -> google: 请求Google OAuth登录
  activate google #DeepSkyBlue
  google-->client: 登录url
  client->google: 跳转登录页
  google -> google: 用户登录
  google --> client: Google登录Token
  deactivate google
end

client -> ga: 登录请求
activate ga #DeepSkyBlue
ga -> user: 请求转发
activate user #DeepSkyBlue

alt 常规登录
  user -> DB: 查询用户信息
  activate DB #DeepSkyBlue
  DB -> user: 用户信息
  deactivate DB
  user->user: 登录密码校验
else Google登录
  user -> google: 验证token
  activate google #DeepSkyBlue
  google --> user: 用户信息
  deactivate google
  user->user: 存储或更新用户信息
end

user-->ga: 登录结果
deactivate user
ga -> client: 响应
deactivate ga

alt 成功
  client -> c: 登录成功
else 失败
  client -> c: 登录失败
end

deactivate client
@enduml

Conclusion

PlantUML is comfortable to use because it offers a Markdown‑like WYSIWYG experience, stores diagrams as text for version control and collaboration, and integrates with platforms like Yuque for inline editing. Its extensibility and flexibility allow developers to create simple to complex diagrams efficiently.