軟件文檔寫做-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老系統

原創不易，轉載請註明出處，歡迎溝通交流。