PlantUML 时序图全面指南：从基础到高级

在软件开发中，清晰地表达系统组件之间的交互至关重要。时序图（Sequence Diagram）是统一建模语言（UML）中的一种图表类型，它用于描述对象之间如何按时间顺序进行交互。PlantUML 是一种开源工具，它允许用户使用简单的文本语法来创建 UML 图表和其他类型的图表。本文将向您介绍如何使用 PlantUML 创建时序图，并通过一系列示例来展示其强大功能，包括参与者定义、消息传递、注释以及更复杂的控制结构等。

基本示例

->:表示绘制两者之间的关系;
–>:带有箭头的;
<-;<–也可以使用;
适用于顺序图,其他图的规则不同

@startuml
title study uml base

A -> B:hello sb
B -> A:hello SA

A --> B:hello SB
B --> A:hello SA
@enduml

生命参与者

使用关键字participant来声明,声明的顺序是默认的显示顺序

• actor :角色
• boundary :边界
• control :控制
• entity :实体
• database :数据库
• collections :集合
• queue :队列

@startuml
title 声明参与者

participant Participant as Foo
actor  Actor as Foo1 #red
boundary Boundary as Foo2 #green
control Control as Foo3
entity Entity as Foo4
database Database as Foo5
collections Collections as Foo6
queue Queue as Foo7

Foo -> Foo1: to actor
Foo -> Foo2 : to boundary
Foo -> Foo3 : to control
Foo -> Foo4 : to entity
Foo -> Foo5 : to database
Foo -> Foo6 : to collections
Foo -> Foo7 : to queue
@enduml

多行定义参与者

participant Participant[=title
—
““content””
]

@startuml
title 多行定义参与者
participant A[
    =title
    ----
    ""参与者""
]
participant B
A -> B
@enduml

在参与者中使用非字母

可以使用引号来定义参与者,使用as关键字给参与者一个别名

@startuml
title 参与者使用非字母

A -> "B()":hello
"B()"->"my name is sb" as sb
sb -->"B()": "your name is sb"
@enduml

给自己发消息

可以使用\n换行

@startuml
title 给自己发消息

B->B:my name is sb

A<-A:自己给自己发消息
@enduml

文本对齐

箭头的文本对齐可以使用skinparam sequenceMessageAlign,后接参数left、right或者center
也可以使用direction或reverseDirection来根据箭头的方式对齐文本
同时,也可以使用skinparam responseMessageBelowArrow true命令,让响应体显示在箭头下面

@startuml
title 文本对齐
skinparam sequenceMessageAlign right
A->B:你好sb****
B->A:你好sha***
@enduml
```plantuml
@startuml
skinparam reverseDirection left
A->B:根据箭头的方向一起文本
B->A:看看有没有对齐
@enduml
@startuml
skinparam direction left
A->B:你好sb*****************
B->A:你好sha****************
@enduml

@startuml
title 响应消息显示在箭头下面
skinparam responseMessageBelowArrow true
a->b:hello sb
a<-b:hello sha
@enduml

改变箭头方式

• 添加最后的x表示丢失的消息
• 使用\或/表示只拥有箭头的底部或顶部部分
• 使用重复箭头头(例如>>或//)表示拥有一个薄的图纸
• 使用–表示拥有一个点状箭头
• 在箭头头添加最后的o
• 使用双向的箭头<->

@startuml
a->x b
a-> b
a->>b
a-\b
a\\-b
a//--b
a<->b
@enduml

@startuml
title 箭头颜色
a-[#red]>b:hello
a<[#green]-b:ok
@enduml

对消息编号

使用关键字autonumber对消息编号
autonumber start用于制定编号的初始值
autonumber start increment同时指定编号和每次增加的值
也可以在双括号内指定编号的形式
格式是由java的decimalFormat类实现的:(0表示数字;#也表示数字但默认为0)
也可以使用html标签来制定格式

@startuml
autonumber
a->b:请求1
a<-b:返回参数

autonumber 20
a->b:请求2
a<-b:返回参数

autonumber 30 5
a->b:请求3
a<-b:返回参数

autonumber "<b>[000]"
a->b:请求4
a<-b:返回参数

autonumber 15 "<b>(<u>##</u>)"
a->b:请求5
a<-b:返回参数

autonumber 40 10 "<font color=red><b>message 0"
a->b:请求6
a<-b:返回参数
@enduml

页面标题、页眉和页脚

title关键字为页面添加标题
页面可以使用header和footer显示页眉和页脚

@startuml
header Page Header
footer Page %page% of %lastpage%
title 页面标题

a->b:message1
a<-b:message2

@enduml

分隔示意图

newPage用于把一张图分割成多张
在newPage之后添加文字,作为新的示意图标题

@startuml
title 分隔示意图
a->b:message1
a<-b:message2

newPage

a->b:message3
a<-b:message4

@enduml

组合消息

可以使用关键词来组合消息

• alt/else
• opt
• loop
• par
• break
• critical
• group 后面紧跟消息内容
• end 结束分组

@startuml
title 组合消息
user->manage:auth request
alt success
    user<-manage:success accept
else fail
    user<-manage:auth fail
    group own label
    user->log:search log
        loop 1000 times
            user->manage:dns attack
        end
    user->log:break log
    end
else another fail
    user->manage:repeat auth request
end
@enduml

注释信息

note left和note right关键字在信息后面添加注释
也可以使用end note关键字添加多行注释

也可以使用note left of,note right of或note over在节点的相对位置放置注释

@startuml
title 注释信息
a->b:hello
note left:this is left note
b->a:ok
note right:this is right note

b->b:i am thinking
note left
a note
can also be defined
on several lines
end note
@enduml

@startuml
participant a
participant b

note left of a #green
this is displayed
left of a
end note

note right of a:this is displayed right of a

note over a:this is displayed over a

note over a,b #red : this is displayed \n over b and a

note over b,a
this is yet another example of
a long note
end note
@enduml

分隔符

==关键字可以将图表分割成多个逻辑步骤

@startuml
title 分隔符
==初始化==
a->b:认证请求
a<-b:认证响应
==重复==
a->b:认证请求
a<-b:认证响应
@enduml

引用

ref over关键字用来实现引用

@startuml
title 引用
participant user
actor manage
ref over user,manage:init
user->manage:hello
ref over manage
this can be on
several lines
end ref
@enduml

延迟

…表示延迟,还可以给延迟添加注释

@startuml
title 延迟
a->b:request
...
a<-b:response
...after five minutes...
a<-b:god bey
@enduml

生命线的激活与撤销

activate和deactivate表示参与者的生命活动
destroy表示一个参与者的生命线的终结
也可以使用自动激活关键字(autoactivate)需要与return关键字配合
return可以用于生成一个带有可选文本标签的返回信息，返回的点是导致最后一次激活生命线的点

@startuml
participant user
participant h5
participant manage
participant db

user->h5:search query
activate h5
h5->manage:<<createRequest>>
activate manage
manage->db:query sql
activate db
bd->manage:query result
destroy db
manage->h5:<<returnResponse>>
deactivate manage
h5->user:response
deactivate h5

user->db:use query sql
activate db
db->db:use engin
return result
@enduml

包裹参与者

box和end box可以将参与者包裹起来

@startuml
title 包裹参与者

box "包裹" #LightBlue
participant user
participant manage
end box
participant another

user->manage:request
manage->user:response
user->another:request
another->manage:response
@enduml

外观参数

可以使用skinparam改变字体和颜色

@startuml
title 外观参数

skinparam sequenceArrowThickness 2
skinparam roundcorner 20
skinparam maxmessagesize 60
skinparam sequenceParticipant underline

actor user
participant "first class" as A
participant "second class" as B
participant "last class" as C

user->A:doWork
activate A
A->B:createRequest
activate B
B->C:doWork
activate C
C->B:workDone
destroy C
B->A:request created
deactivate B
A->user:done
deactivate A
@enduml

特定外观参数

• nosolid 虚线(默认情况)
• solid 实线
• skinparam style strictuml 线头的形状三角形

@startuml
title 特定外观参数
a->b:hello
b->a:ok
@enduml

@startuml
title 特定外观参数
skinparam lifelineStrategy solid
a->b:hello
b->a:ok
@enduml

@startuml
title 特定外观参数
skinparam style strictuml
a->b:hello
b->a:ok
@enduml

分组信息着色

@startuml
title 分组信息着色

a->b:request
alt#Gold #LightBlue successful case
    b->a:authentication accepted
else #Pink failure
    b->a:authentication regected
end
@enduml

组合示例

用户登录流程示例

@startuml
title 用户登录流程

|用户|
start
:输入用户名和密码;
:点击登录按钮;

|前端|
->|前端| :校验表单;
if (表单有效?) then (是)
    ->|后端| :发送POST请求 /login, 包含用户名和密码;
else (否)
    :显示错误信息;
    stop
endif

|后端|
:接收请求;
:解析JSON数据;
:校验参数（用户名和密码非空且格式正确）;
if (参数校验通过?) then (是)
    ->|数据库| :查询用户信息;
    |数据库|
    -->|后端| :返回用户数据或不存在;
    |后端|
    if (用户存在?) then (是)
        :验证密码;
        if (密码匹配?) then (是)
            :创建会话令牌;
            ->|前端| :响应HTTP 200 OK, 返回会话令牌;
        else (否)
            ->|前端| :响应HTTP 401 Unauthorized;
            stop
        endif
    else (否)
        ->|前端| :响应HTTP 404 Not Found;
        stop
    endif
else (否)
    ->|前端| :响应HTTP 400 Bad Request;
    stop
endif

|前端|
:处理响应;
if (HTTP 200 OK) then (是)
    :保存会话令牌到cookie或localStorage;
    :重定向至主页;
else (其他状态码)
    :显示错误消息;
endif

stop
@enduml

用户登录时序图

@startuml
title 用户登录时序图

actor User
participant "Frontend" as FE
participant "Backend" as BE
participant "Database" as DB

User -> FE: 输入用户名和密码
User -> FE: 点击登录按钮
FE -> FE: 校验表单
alt 表单有效
    FE -> BE: 发送POST请求 /login, 包含用户名和密码
    BE -> BE: 解析JSON数据
    BE -> BE: 校验参数（用户名和密码非空且格式正确）
    alt 参数校验通过
        BE -> DB: 查询用户信息
        DB --> BE: 返回用户数据或不存在
        alt 用户存在
            BE -> BE: 验证密码
            alt 密码匹配
                BE -> BE: 创建会话令牌
                BE --> FE: 响应HTTP 200 OK, 返回会话令牌
                FE -> FE: 保存会话令牌到cookie或localStorage
                FE -> FE: 重定向至主页
            else 密码不匹配
                BE --> FE: 响应HTTP 401 Unauthorized
                FE -> FE: 显示错误消息
            end
        else 用户不存在
            BE --> FE: 响应HTTP 404 Not Found
            FE -> FE: 显示错误消息
        end
    else 参数校验未通过
        BE --> FE: 响应HTTP 400 Bad Request
        FE -> FE: 显示错误消息
    end
else 表单无效
    FE -> FE: 显示错误信息
end

@enduml

通过这篇文章，我们学习了如何利用 PlantUML 来绘制时序图，了解了参与者声明、消息发送、文本对齐、箭头样式、组合消息、注释、延迟处理、生命线激活与撤销等基本概念和高级特性。此外，我们还通过实际案例展示了用户登录流程的时序图，帮助读者更好地理解这些知识在真实场景中的应用。掌握 PlantUML 不仅能够提高您的文档撰写效率，还能使沟通更加直观有效。希望本文能成为您掌握这项技能的良好起点。
更多精彩内容请关注以下公众号