Master PlantUML: From Basics to Advanced Sequence Diagram Techniques

Introduction

Hello, I am Su San. While designing systems I often need to draw many sequence diagrams. I used draw.io before, tried the built‑in diagram tool of Yuque, but complex diagrams quickly become cumbersome. Colleagues recommend PlantUML, which turned out to be a professional solution.

1. What Is PlantUML?

PlantUML is a versatile component that creates diagrams quickly and directly using a simple, intuitive language.

PlantUML is an open‑source tool that lets you describe UML diagrams—such as sequence, use‑case, class, object, activity, component, deployment, state, and especially sequence diagrams—in plain text. It also supports other charts like JSON, YAML, EBNF, architecture diagrams, etc. Because diagrams are defined as text, they can be embedded in source code, version‑controlled, and collaboratively edited.

2. Quick Start

PlantUML Plugins

Many popular IDEs provide PlantUML plugins (VS Code, IntelliJ IDEA, Eclipse). Plugins offer real‑time preview, syntax highlighting, and export features. IDEA’s plugin feels the most powerful but is memory‑heavy; VS Code is lighter.

IntelliJ IDEA – "PlantUML integration" lets you view and edit PlantUML diagrams directly in the IDE.

VS Code – PlantUML extension .

Hello World!

Using the arrow symbols ->, --> and : you can pass messages between participants without explicitly declaring them.

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

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

3. PlantUML Sequence Diagram Syntax

Declaring 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. The as keyword renames participants.

@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 set participant colors with # followed by a color code.

@startuml
actor Bob #blue
participant Alice #SkyBlue
participant "I have a really
long name" as L #00ff00
Alice->Bob: Authentication Request
Bob->Alice: Authentication Response
Bob->L: Log transaction
@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: 自调用

Lifeline and Activation Bar

A lifeline is the vertical dashed line representing an object's existence over time. An activation bar (a rectangle on the lifeline) shows when the participant is active. activate – start activation deactivate – end activation destroy – terminate the 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

Nested activations and colored lifelines are also supported.

@startuml
participant User
User -> A: DoWork
activate A #FFBBBB
A -> A: Internal call
activate A #DarkSalmon
A -> B: << createRequest >>
activate B
B --> A: RequestCreated
deactivate B
deactivate A
A -> User: Done
deactivate A
@enduml

Groups and Alternatives

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

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

alt condition1
A -> B: Message for condition1
else condition2
A -> B: Message for condition2
end

Notes

Notes add explanatory text. Position them with note left of, note right of, or note over. Background colors can highlight notes.

@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 assign colors directly to elements using #colorCode 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

4. Complete Example – Google Login Flow

The following diagram models a login process that adds Google OAuth as an alternative authentication method.

@startuml
skinparam ParticipantBackgroundColor #DeepSkyBlue
actor User as c #DeepSkyBlue
participant "Client" as client
participant "API Gateway" as ga
participant "User Service" as user
database "Database" as DB #DeepSkyBlue
participant "Google Service" as google #LightCoral

activate c #DeepSkyBlue
activate client #DeepSkyBlue
c->client: User login

group #LightCoral Google login client flow
  client -> google: Request Google OAuth
  activate google #DeepSkyBlue
  google --> client: Login URL
  client -> google: Redirect to login page
  google -> google: User logs in
  google --> client: Google token
  deactivate google
end

client -> ga: Login request
note right #LightCoral: New third‑party login request
activate ga #DeepSkyBlue
ga -> user: Forward request
activate user #DeepSkyBlue

alt #DeepSkyBlue Regular login
  user -> DB: Query user info
  activate DB #DeepSkyBlue
  DB -> user: User info
  deactivate DB
  user -> user: Verify password
else Google login
  group #LightCoral Google login server flow
    user -> google: Verify token
    activate google #DeepSkyBlue
    google --> user: User info
    deactivate google
    user -> user: Store/Update user
  end group
end

user --> ga: Login result
deactivate user
ga -> client: Response
deactivate ga
alt #DeepSkyBlue Success
  client -> c: Login success
else Failure
  client -> c: Login failure
end
deactivate client
@enduml

5. Summary

PlantUML feels very comfortable to use. Its main advantages are:

Markdown‑like, WYSIWYG experience that avoids manual layout adjustments.

Text‑based diagrams are version‑control friendly and support collaborative editing.

Yuque supports inline PlantUML, allowing direct editing within documentation.

PlantUML also offers strong extensibility; consult the official documentation ( https://plantuml.com/zh/ ) for advanced syntax and techniques.