PlantUML - 时序图

时序图主要内容

下面是一个简单的时序图，我们可以很容易并且美观的表达我们的交互流程，只需要在箭头的两边指定一个名字，加上描述即可：

@startuml

bkloanapply -> bkloanapprove : request
bkloanapprove --> bkloanapply : response 

@enduml

参与者

在上面的例子里，我们不用声明一个参与者，也可以很好的运行，但是存在以下问题：

• 名字如果定义太长，下面的代码会一直用很长的名字来编写，不够清晰。（我们可以使用 as 关键字来重命名）
• 无法改变参与者类型，默认参与者为 participant
• 如果要改变参与者名字，需要全局搜索所有名字一起替换。

所以，建议大家在编写时统一在最上方定义好参与者。

@startuml

participant bkloanapply as a
participant bkloanapprove as b

a -> b : request
b --> a : response

@enduml

除了 participant 外，我们还可以使用其他一些关键字来声明参与者，看大家喜好使用：

@startuml

actor Foo1
boundary Foo2
control Foo3
entity Foo4
database Foo5
collections Foo6

Foo1 -> Foo2 : To boundary
Foo1 -> Foo3 : To control
Foo1 -> Foo4 : To entity
Foo1 -> Foo5 : To database
Foo1 -> Foo6 : To collections

@enduml

图中展示的参与者顺序和代码写的先后顺序一致，虽然官方提供了 order 关键字来定义顺序，但是不建议使用（能少记一点是一点，改一下代码顺序就完了~）

上面的参与者在一开始就定义好了，我们还可以使用关键字 create 放在第一次接收到消息之前，以强调本次消息实际上是在创建新的对象（图中的表现是箭头指向参与者而不是生命线）。

@startuml

participant bkloanapply as a
participant bkloanapprove as b

a -> b : request
create bkloandecision as c
b -> c : request2

create control bkdmc as d
b -> d : request3
note right: this is note!

b --> a : response

@enduml

如果觉得使用关键字太繁琐了，我们还可以使用缩写符号 ** 来代替，比如上图还可以这么写：

@startuml

participant bkloanapply as a
participant bkloanapprove as b
participant bkloandecision as c
control bkdmc as d

a -> b : request
b -> c ** : request2

b -> d ** : request3
note right: this is note!

b --> a : response

@enduml

包裹参与者

可以使用 box 和 end box 画一个盒子将参与者包裹起来。

@startuml

box "贷前" #LightBlue
    participant bkloanapply as a
    participant bkloanapprove as b
end box
participant bkloandecision as c

a -> b : request
b -> c : request2
return response2
b --> a : response
@enduml

箭头样式

@startuml

participant bkloanapply as a
participant bkloanapprove as b

a ->x b
a -> b
a ->> b
a -\ b
a \\- b
a //-- b
a ->o b
a o\\-- b
a <-> b
a <->o b

@enduml

当消息的接收源或发送源不确定时，我们可以使用 [ 或 ] 符号来代替。

@startuml

participant bkloanapply as a

[o-> a : 接收到消息
a -> a : 处理逻辑
a ->o] : 发出消息

@enduml

标题、页头、页尾

我们可以使用 title 来表示标题，header 和 footer 表示页头和页尾。

@startuml

header 一期
footer Page %page% of %lastpage%
title 扫码付

participant bkloanapply as a
participant bkloanapprove as b

a -> b : request
b --> a : response

@enduml

分割多张图

上面说页头页尾时我们举了个例子，页尾显示为 Page 1 of 1 ，那什么时候会出现多页呢？newpage 关键字就是用来分页使用的，它可以使所有页面共用相同的参与者以及标题、页头、页尾、样式等所有元素。

@startuml

header 一期
footer Page %page% of %lastpage%
title 扫码付

participant bkloanapply as a
participant bkloanapprove as b

a -> b : request
b --> a : response

newpage

a -> b : request2
b --> a : response2

@enduml

组合消息

我们可以通过以下关键词将组合消息：

• alt/else
• opt
• loop
• par
• break
• critical
• group, 后面紧跟着消息内容

关键词 end 用来结束分组。（注：分组可以嵌套使用）

@startuml

participant bkloanportal as a
participant bkloanapply as b
participant bkloanapprove as c
participant bkloandecision as d
participant bkdmc as e

a -> b : 前准入咨询
b -> d : 前准入咨询
return 前准入是否准入

opt 可选条件
b -> d : 会员准入咨询
end

alt 前准入准入
    b --> a : 准入
else 前准入不准入
    b --> a : 不准入异常码
end

a -> b : 提交申请
return : 提交成功，返回单号

b -> c : 开启调查

loop 所有采集项
    c -> e : 开始采集
end

c -> d : 授信准入
c -> d : 固化授信

@enduml

消息序列编号

我们可以使用 autonumber 自动对消息进行编号，这里列举的是最通用也是最简单，如果想使用复杂的编号，自行去官网查阅。

@startuml

autonumber
participant bkloanapply as a
participant bkloanapprove as b

a -> b : request
b --> a : response

@enduml

分隔符

你可以通过使用 == 关键词来将你的图表分割多个步骤。

@startuml

participant bkloanapply as a
participant bkloanapprove as b

==分隔符1==
a -> b : request1
return : response1

==分隔符2==
a -> b : request2
return : response2

@enduml

添加注释

我们可以在消息的左边、右边、消息中间增加注释，大体有以下几种：

• note left : msg 和 note left of a : msg ，在消息左侧添加注释，不同的是右边的 of a 可以指定在哪个消息的左边添加注释，如果是当前发消息的主体，这两者作用一样。
• note right : msg 和 note right of a : msg ，在消息右侧添加注释，同上。
• note over a : msg ，在消息中间增加注释。
• note over a,b : msg ，在多个消息中间增加注释。

如果注释内容过多，想让它换行展示，我们可以使用两种方式：

• 直接在注释的内容里添加 \n 即可。
• 直接换行分两行注释

@startuml

participant bkloanapply as a
participant bkloanapprove as b

a -> b : request
note left : note left a
note left of b: note left b

return response
note right : line1\nline2

b -> b : 自言自语
note left
    line1
    line2
    line3
end note

note over b : note over b
note over a,b : note over a and b

@enduml

如果你觉得默认的注释框不好看，PUML还提供了另外两种形状，hnote 六边形和 rnote 长方形：

@startuml

participant bkloanapply as a
participant bkloanapprove as b

rnote left a : 长方形
hnote over b : 六边形

@enduml

生命线的激活与撤销

关键字 activate 和 deactivate 用来表示参与者的生命活动。一旦参与者被激活，它的生命线就会显示出来。

@startuml

participant bkloanapply as a
participant bkloanapprove as b
participant bkloandecision as c

a -> b : request
activate b

b -> c : request2
activate c
return response2
deactivate c

b --> a : response
deactivate b

@enduml

同样，我们还可以使用嵌套的生命线。

@startuml

participant bkloanapply as a
participant bkloanapprove as b
participant bkloandecision as c

a -> b : request
activate b

b -> b : invoke self
activate b
b -> c : request2
activate c
return response2
deactivate c
deactivate b

b --> a : response
deactivate b

@enduml

当然，我们也可以使用 ++ 和 -- 来作为 activate 和 deactivate 的缩略符号（如果使用 return 作为返回，不需要使用 --），同样，上面的例子也可以简写成：

@startuml

participant bkloanapply as a
participant bkloanapprove as b
participant bkloandecision as c

a -> b++ : request
b -> b++ : invoke self
b -> c++ : request2
return response2
b--

return response

@enduml

构造类型和圈点

我们可以使用 << 和 >> 给参与者添加构造类型。在构造类型中，你可以使用 (X,color) 格式的语法添加一个圆圈圈起来的字符。

@startuml

participant bkloanapply as a <<System>>
participant LoanApplyService as applyService << (C,#ADD1B2) Class>>
participant LoanAdmitService as admitService << (C,#ADD1B2) >>

a -> applyService : request
applyService -> admitService : request2
return response2
applyService --> a : response

@enduml

样式设置

修改颜色

如果你想修改默认参与者的颜色，可以在参与者名字后面加上 #颜色 。

如果你想修改默认箭头的颜色，只需要在箭和头之间加上 [#颜色] 就可以了。

如果你想修改备注的颜色，只需要在备注后加上 #颜色 就可以了，其他类型需要修改颜色的同理。

@startuml

participant bkloanapply as a #red
participant bkloanapprove as b #green
participant bkloandecision as c #99FF99

a -[#green]> b ++#green : request
note left #green : green note

b --[#brown]> a-- : response

b -> c : request2

@enduml

修改字体或者其他样式

因为用的场景不多，默认的样式还蛮好看的，再说UML图的目的就是清晰表达思路，过多的样式会占用我们比较多的时间，如果实在想修改，可以自行在官网查阅。

案例

只看不练假把式，我们通过一个例子实际的去运用它，这个例子中包含了80%上面说的内容，练完后几乎可以应对一切时序图啦。

本例通过贷前系统的采集流程进行一个梳理：

@startuml
title 重构后的采集流程
autonumber
skinparam roundcorner 30
skinparam sequenceArrowThickness 2

actor 用户 as user #red
participant bkloanportal as portal
box "贷前" #LightBlue
    participant bkloanapply as apply
    participant bkautoapprove as autoapprove
    participant bkpreloancore as preloancore
    database 贷前DB as db
end box

box "流程" #DarkSalmon
    control 流程引擎 as flow
end box

participant bkloandecision as decision
participant 产品工厂 as factory
participant bkdmc as dmc

user -> portal : 申请贷款
portal -> apply : 前准入咨询
apply -> decision++ : 前准入咨询
return 前准入是否准入

alt 前准入不准入
    apply --> portal : 不准入
    portal --> user : 提示前端弹出\n【当前没有申贷资格】\n提示用户
else 前准入准入
    portal -> apply : 提交申请
    apply -> decision++ : 会员准入咨询
    return 会员准入结果
    note left : 需要支持轮询采集\n需要的分组和排序
    apply -> db : 提交申请
    apply -> autoapprove : 广播申请成功消息
    autoapprove -> flow : 开启并行采集流程
    autoapprove -> preloancore : 采集节点初始化
    preloancore -> factory ** : 读取调查审批产品
    preloancore -> preloancore : 节点解析
    preloancore -> db : 持久化所有节点信息
    autoapprove -> preloancore : 咨询所有采集是否完成

    alt 所有采集没有完成
        autoapprove -> preloancore : 获取下一批节点
        loop 一批节点
            autoapprove -> flow : 启动采集子流程
            autoapprove -> preloancore : 查询该采集项在dmc内是否存在有效数据
            activate preloancore
            preloancore -> dmc ** : getObject
            activate dmc
            return 数据
            deactivate dmc
            preloancore --> autoapprove : 是否存在有效数据
            deactivate preloancore
            alt 存在有效数据
                autoapprove -> preloancore : 更新节点状态EXIST_DATA
                autoapprove -> flow : 唤醒主流程
            else 不存在有效数据
                autoapprove -> preloancore : 授权咨询
                autoapprove -> preloancore : 发起采集
                preloancore -> db : 创建采集请求
                preloancore -> dmc : 发起采集collectObject
                autoapprove o-> autoapprove : 接到采集完成消息
                autoapprove -> preloancore : 根据rqsNo查询采集请求
                activate preloancore
                preloancore -> db++ : 查询采集请求
                return 采集请求
                preloancore --> autoapprove : 采集请求
                deactivate preloancore
                autoapprove -> flow : 唤醒子流程继续执行
                autoapprove -> preloancore : 完成采集
            end
        end
    end
end

@enduml