使用plantuml，業務交接就是這麼簡單
你好，我是軒脈刃。
最近交接了一個業務，原本還是有挺複雜的業務邏輯的，但發現交接過來的專案大有文章，在專案程式碼中有一個docs資料夾，裡面躺著若干個 puml 檔案，這些puml檔案把業務中最核心的一些業務流程圖和時序圖都繪製清楚了。看到這個資料夾無異於發現了一個大寶藏。這種在程式碼中附帶說明，程式碼即一切的做法我在開源專案也是這麼做的，只是不知道，原來時序圖還能使用plantuml如此編寫，在這之前，我還都只用過畫圖軟體繪製過時序圖。學之，學之，於是就進入了plantuml的坑了。
plantuml 本身就是一個開源專案，在github上有它的倉庫 https://github.com/plantuml/plantuml 和 組織 https://github.com/plantuml 。作者是Arnaud Roques，這裡有一篇 https://modeling-languages.com/interview-plantuml/ 對他的訪談，聊到他創作plantuml的初衷是什麼？“keeping the documentation up to date”。翻譯過來叫“讓交接專案的程式設計師少一些wtf”，哈，果然程式設計師的痛點都差不多。
plantuml 是使用java開發的，最早release版本應該是在2009年，我看github上至今仍然以1個月1個版本的速度釋出release更新著。它最大的好處就是使用純文字來繪製圖形。是的，不僅僅是時序圖，它可以繪製類圖，流程圖，部署圖，甘特圖，思維導圖：
官方文件在：https://plantuml.com/zh/
比如我現在使用最多的就是它的時序圖。（官方文件翻譯為“順序圖”，而官方文件的“時序圖”是時間線的意思）
https://plantuml.com/zh/sequence-diagram
這種複雜的分組流程
用下列簡單的文字就能描述出來了。
@startuml
Alice -> Bob: 認證請求
Bob -> Alice: 認證失敗
group 我自己的標籤 [我自己的標籤2]
Alice -> Log : 開始記錄攻擊日誌
loop 1000次
Alice -> Bob: DNS攻擊
end
Alice -> Log : 結束記錄攻擊日誌
end
@enduml
頗為神奇。
plantuml支援的時序圖的關鍵字我整理了一下。
actor（角色）boundary（邊界）control（控制）entity（實體）database（資料庫）collections（集合）queue（佇列）order(順序)as(別名)\n（換行）skinparam responseMessageBelowArrow true（文字對齊）-> --> ->o ->>（各種箭頭樣式）autonumber（自動對訊息編號）header（頁首）footer(頁尾)newpage分頁group(分組)loop（迴圈）note left of，note right of或note over(增加備註)hnote和rnote備註框形狀note across(多個參與者增加備註)==（分隔符）ref over（引用）...延遲maxMessageSize（文字最大長度）||限定空間activate和deactivate（生命線啟用，取消啟用）destroy（生命線消失）return（返回）create建立參與者++啟用目標（可選擇在後面加上#color）--撤銷啟用源**建立目標例項!!摧毀目標例項[]進入和發出?縮短teoz瞄點和持續<< >>構造型別box包裹參與者hide footbox移除腳註[skinparam](https://plantuml.com/zh/skinparam)改變外觀
至於繪製的工具，各種ide目前已經都支援了。我自己在vscode和goland上都嘗試過繪製非常大的時序圖，goland的繪製會比vscode慢一些，甚至在這個plantuml比較複雜的時候，goland會出現記憶體不足，載入失敗的錯誤。但是在vscode中，沒有出現過。
在plantuml可以支援的型別中，目前最讓我覺得有用的就是時序圖和jsom/yaml 資料，時序圖不用說了，對於json和yaml，一旦非常大的配置檔案，使用json/yaml來進行描述，閱讀起來是多麼痛苦的事情，特別是yaml，需要對比鎖進層次。而使用plantuml，能繪製出非常通俗易懂（逼格十足）的配置檔案層次圖，是非常爽的一件事情。
好了，後續交接專案的時候，別再寫一大堆的wiki了，用用plantuml吧，讓下任接手者為之驚豔一番。
參考文章：