軟件文檔寫作-plantuml畫用例圖和時序圖

背景

當下的軟件開發人員，不可避免的需要輸出一些軟件設計文檔，作為一個軟件工程專業畢業的工程師，最常用的設計工具就是UML，使用UML工具繪制一些軟件相關的圖，是必備技能，也是輸出的技術文檔中的重要組成部分。不關注逆向工程，這里只關注快速的繪制對應的圖，plantuml是一款比較不錯的工具。本節先初步熟悉用例圖和時序圖。

plantuml介紹

官網主頁

功能介紹：

支持快速繪制

• 時序圖
• 用例圖
• 活動圖
• 類圖
• 組件圖
• 狀態圖
• 對象圖
• 部署圖
• 定時圖

還支持非UML圖：

• 架構圖
• 甘特圖
• 思維導圖
• ER圖

以及不常用的的圖：

• SDL（規范描述語言）
• 線框圖形界面
• Ditaa
• 數學公式

畫完圖之后，可以生成PNG,SVG,Latex格式的圖片;

業務場景

x項目的用戶后端服務,包括用戶登錄，用戶積分模塊；

用例圖

用戶角度描述系統功能

語法

基本對象	語法	說明
用例	usecase 詳細名稱 as 簡稱	定義一個用例
用例帶自描述	usecase 詳細名稱 as “詳細描述可分行”	定義一個用例並詳細描述
角色	actor :角色全稱: as 角色簡稱	定義一個角色
角色和用例建立聯系並設置關系	角色簡稱-->usercase簡稱:關系名稱	建立角色和用例的關系
繼承	角色<豎線--角色 或者 用例<豎線用例	描述角色跟角色之間的繼承關系或者用例跟用例之間的繼承關系
單行注釋	note 位置 of 用例或者角色簡稱 : 注釋內容	增加單行注釋
多行注釋	note 位置 of 用例或者角色簡稱 換行 注釋內容 換行 end note	添加多行注釋
構造類型	《父類》	定義角色或者用例的構造類型，即父類
簡單箭頭	->水平， -->垂直線,箭頭也可以改變方向或者是雙向的	不用指明方向的箭頭
方位箭頭	-位置->	帶位置的箭頭， 位置是 right left down up 上下左右
分割圖	newpage	把一頁分成兩頁
定義默認方向	left to right direction	設置默認方向

---

系統用例圖

內部系統用例

@startuml

left to right direction

actor : 其它LX提供給TA的后端系統: as otherLxTaBackendService

note top of otherLxTaBackendService
比如tianansp
負責活動和文章的服務
比如tiananseason
負責西游活動的服務
通過dubbo的rpc方法調用
end note

usecase 修改用戶積分 as changeUserPoint
usecase 查詢用戶總積分 as getUserTotalPoint
usecase 登錄校驗 as getRestContextByAccessToken


otherLxTaBackendService --> getRestContextByAccessToken:獲取用戶的登錄態[RPC]
otherLxTaBackendService --> changeUserPoint:活動增加或者扣減積分[RPC]
otherLxTaBackendService --> getUserTotalPoint: 查詢用戶當前總積分[RPC]


@enduml

生成的圖：

外部系統用例

@startuml

'left to right default

actor : ta用戶: as taUser

usecase  用戶登錄  as  userLogin
usecase 查詢積分明細 as findUserPointDetail
usecase 改變積分 as changeUserPointDetail


note bottom of userLogin
TA用戶登錄
LX交互的后端系統
LX的saas系統
構造登錄態
end note

taUser -right-> userLogin: 登錄進LX交付的功能[REST]
taUser --> changeUserPointDetail : 修改積分\n閱讀文章\n分享文章\n參加活動[REST]
taUser --> findUserPointDetail : 查詢積分\n消費獲取\n明細[REST]

@enduml

時序圖（順序圖）

展示對象跟對象之間的協作關系

語法

對象	語法	說明
箭頭和線	-> <-實線箭頭 <-- -->虛線箭頭	標識參與者之間的消息傳遞
參與者	actor 角色 boundary 帶邊界 control控制 entity 實體 database 數據庫 collections 集合 participant 參與者	標識參與者
重命名	participant 參與者詳細名稱 as 簡稱	重命名參與者
定義順序	participant 參與者詳細名稱 order 排序號	序號越小越靠前
參與者含有特殊字符	“參與者”	雙引號包圍
箭頭樣式	丟失的消息 ->x 實心箭頭 -> 虛箭頭 ->> 半實心箭頭 -\ 半虛箭頭 -\ 箭頭末尾加0 ->o	各種箭頭
箭頭顏色	參與者1-[顏色定義]->參與者	改變箭頭顏色
消息自動編號	autonumber	放在開始的位置
設置	title,header,footer	header footer title在開始的地方定義
組合消息條件分支	alt/else end	條件分支
組合消息循環分支分支	loop end	循環
組合消息 group	group end	分組
單行注釋	note 位置 ：注釋內容	給消息增加備注
多行注釋	note 位置（right,left,over） 換行 注釋內容 換行 end note	給消息增加備注
改變注釋的形狀	hnote 六邊形 rnote 四邊形	注釋的形狀
分隔符	分割備注內容	橫向划分模塊
引用	ref over 參與者1 參與者2 : 引用內容	引用
延遲	···標識延遲 ···	消息固定延遲
空間	3根豎線	間隔
激活生命線	activate 參與者	激活生命線
取消激活生命線	deactivate 參與者	激活生命線
返回	return 參與者	返回
創建參與者	create 參與者	標識創建對象
快捷鍵	++ 激活參與者 --取消激活參與者 ** 創建參與者 ！！銷毀參與者	見語法說明
創建盒子	box "box的命名" #背景色 換行 參與者1 參與者2 end box	縱向划分模塊

---

登錄接口時序圖

@startuml

autonumber "<b>[00]"

title 登錄接口時序圖

actor "TA用戶" as User #white
participant "TAAPP" as TAAPP #gold
box "LX交付" #gray
participant "LX交付SDK" as LXSDK #orange
participant "LX交付后端\ntiananuser" as LXServer #red
participant "LXsaas后端" as LXSaasServer #gray
end box
participant "TA后端" as TAServer #green

activate User

User -> TAAPP ++:  登錄TAAPP\n打開健康TAP頁面
==sdk對接==
TAAPP -> LXSDK ++:  userId\n或者加密信息

==后端對接==

LXSDK -> LXServer ++: 登錄轉換為LX登錄態接口
==TA后端對接==
LXServer <-> TAServer ++: 用戶信息校驗\n
==對接saas==
LXServer <-> LXSaasServer ++: 注冊並登錄\n到LXSaas
==構造LX專屬登錄態==
LXServer -> LXServer ++: 登記用戶信息\n保存登錄令牌到redis

LXServer -> LXSDK ++: 構造LX專屬登錄態(token)
==后端對接完成==

LXSDK --> TAAPP ++: 正常使用LX交互功能

TAAPP --> User ++: 看到LX交互功能


@enduml

改變用戶積分

@startuml

autonumber "<b>[#]"

actor TAapp用戶 as taUser

control 網關 as nginx
box 接口程序 #green
boundary Web服務器 as tomcat
end box
collections Redis as redis
database Mysql as mysql

taUser -> nginx  ++ : 看文章，增加積分

nginx ->> tomcat ++ : 負載均衡策略遭到一台tomcat

==接口處理流程開始==
tomcat --> tomcat ++ : 參數判斷
alt 參數判斷不合法
    tomcat -[#red]> taUser ++ : 參數傳錯誤
else 參數合法

tomcat -> mysql ++ : 插入積分改變的明細記錄
return 表記錄id

tomcat ->redis ++ : 獲取緩存中用戶對應的記錄id

alt 緩存中userId對應的積分id存在
    tomcat -> mysql ++ : 更新用戶的總積分
else 緩存中userId對應的積分id不存在
    tomcat -> mysql ++ : 查詢得到用戶對應的id
    alt 用戶的總積分記錄在數據庫中存在
        tomcat -> mysql ++ :更新用戶的總積分
    else userId對應的積分記錄id不存在
        tomcat -> mysql ++ :插入用戶的總積分記錄
    end
    return 用戶積分記錄對應的記錄id
    tomcat -> redis ++: 用戶積分記錄對應的記錄id保存到redis
    return 無返回值
end
tomcat ->redis: 清除掉總積分緩存，分頁緩存，總條數緩存

return  用戶增加積分明細記錄id

end

tomcat -[#green]> taUser ++ : 改變積分成功
@enduml

查詢用戶積分

@startuml

title 查詢用戶積分明細接口時序圖

autonumber

actor TA用戶 as taUser
boundary Web服務 as tomcat
collections Redis as redis
database Mysql as mysql


taUser -> tomcat ++ : 請求查詢總積分和明細
|||

tomcat -> tomcat ++: 參數校驗

opt 參數校驗不通過
tomcat -> taUser --:   參數校驗不通過
end
... ...
tomcat <-> redis ++: 明細總數

opt 明細總數不存在
 tomcat <-> mysql ++: 查詢明細總數
 tomcat <-> redis ++: 保存明細總數
end 


opt 明細總條數為 0 
    tomcat -> taUser ++: 查詢成功，記錄為空
end

tomcat <-> redis ++: 查詢明細記錄
opt 明細記錄為空
tomcat <-> mysql ++: 查詢明細記錄
tomcat <-> redis ++: 保存明細記錄
end

tomcat -> tomcat ++: 明細記錄組裝到返回對象中

tomcat -> redis ++: 查詢用戶的總積分
opt 用戶的總積分
tomcat <-> mysql ++: 查詢用戶的總積分
tomcat <-> redis ++: 保存用戶的總積分

tomcat -> tomcat ++: 用戶的總積分組裝到返回對象中


tomcat -> taUser ++: 返回積分明細

end


@enduml

小結

1. plantuml可以繪制很多軟件設計文檔中的圖，包括架構圖，ER圖，UML圖；
2. 用例圖宏觀的描述了系統的功能；
3. 時序圖比較細致的描述了單個接口的內部處理流程；
4. 接受老項目的時候，按照UML圖去一個一個畫出來，可以盡快的hold老系統

原創不易，轉載請注明出處。