Master PlantUML: Quick Guide to Creating Sequence Diagrams

Introduction

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

What is PlantUML?

PlantUML is a versatile component that quickly creates diagrams using a simple, markdown‑like language.

PlantUML supports UML diagrams such as sequence, use‑case, class, object, activity, component, deployment, state, as well as other charts like JSON, YAML, EBNF, and architecture diagrams. Because diagrams are described in plain text, they can be version‑controlled and embedded directly in source code, making collaboration easy.

Quick Start

PlantUML Plugins

Popular IDEs provide PlantUML plugins (e.g., Visual Studio Code, IntelliJ IDEA, Eclipse) that offer real‑time preview, syntax highlighting, and export features. IDEA’s plugin is feature‑rich but heavyweight; VS Code is lighter.

IntelliJ IDEA: "PlantUML integration" lets you view and edit PlantUML diagrams inside the IDE.

Hello World!

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

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

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

PlantUML Sequence Diagram Syntax

Declare Participants

Use the participant keyword to declare participants; the declaration order determines the default display order. You can also use keywords like actor, boundary, control, entity, database, collections, queue to set different shapes, and rename them with as.

@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 Passing

Arrows indicate message types:

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: 自调用

Lifeline and Activation Bar

Lifelines are vertical dashed lines representing an object's existence over time; activation bars show when a participant is active. activate – start activation deactivate – end activation destroy – terminate lifeline

@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

Groups and Alternatives

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

group 分组名
A -> B: 消息
...
end group

alt 条件1
A -> B: 满足条件1的消息
else 条件2
A -> B: 满足条件2的消息
end

Notes

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

@startuml
participant Alice
participant Bob
note left of Alice #aqua
This is displayed left of Alice.
end note
note right of Alice: This is displayed right of Alice.
note over Alice: This is displayed over Alice.
@enduml

Colors

You can set colors directly with #hex or use skinparam for global styling.

@startuml
actor 用户 #Green
participant 参与者 #B4A7E5
用户 -[#red]> 参与者:消息
activate 参与者 #Blue
@enduml

@startuml
skinparam ActorBorderColor #DarkOrange
skinparam ParticipantBackgroundColor #SkyBlue
actor 用户
participant 参与者
@enduml

Full Example

A more complete diagram shows a login flow that integrates Google OAuth, with participants for user, client, gateway, user service, database, and Google service, demonstrating groups, alternatives, notes, and color styling.

@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 #LightCoral Google登录客户端流程
  client -> google : 请求Google OAuth登录
  activate google #DeepSkyBlue
  google-->client:登录url
  client->google:跳转登录页
  google -> google : 用户登录
  google --> client : Google登录Token
  deactivate google
end

client -> ga : 登录请求
note right #LightCoral: 新增登录方式，三方登录请求实体
activate ga #DeepSkyBlue
ga ->user:请求转发
activate user #DeepSkyBlue
alt #DeepSkyBlue 常规登录
  user -> DB : 查询用户信息
  activate DB #DeepSkyBlue
  DB -> user : 用户信息
  deactivate DB
  user->user:登录密码校验
else Google登录
  group #LightCoral Google登录服务端流程
    user->google:验证token
    activate google #DeepSkyBlue
    google-->user:用户信息
    deactivate google
    user->user:存储或更新用户信息
  end group
end
user-->ga:登录结果
deactivate user
ga -> client : 响应
deactivate ga
alt #DeepSkyBlue 成功
  client -> c : 登录成功
else 失败
  client -> c : 登录失败
end
deactivate client
@enduml

Conclusion

PlantUML offers a markdown‑like, WYSIWYG experience that eliminates manual layout adjustments.

Because diagrams are text‑based, they work well with version control and collaborative development.

Integration with documentation platforms (e.g., Yuque) allows inline editing of PlantUML code.

For more advanced features, refer to the official documentation at https://plantuml.com/zh/ .