PlantUML 與 Sublime Text

什麼是 PlantUML

身為一個 PM，在工作中難免會需要繪製 UML 做為專案溝通以及系統設計之用，以我個人而言最常使用的是活動圖 (Activity Diagram) 以及序列圖 (Sequence Diagram)。

以往繪製這類型的圖表，我會使用的工具是 draw.io。這類工具的方便性在於透過拖拉的方式，可以輕易的產製所需的圖表；但是缺點也很明顯，要修改的時候往往動輒得咎，光是為了重新拉線對齊可能就浪費了不少時間。另外一個缺點則是，這種圖表類型的檔案，如果要做版本管理就不是那麼理想。

因應這樣的需求， Diagram-as-code 的方式橫空出世。以類似程式語法的文字描述圖表，再透過對應引擎轉換為圖形。因為是使用代碼的方式儲存，更易於文件化與版本控制。

PlantUML 就是其中一種 Diagram-as-code 工具，官方網站上提供了滿多的範例與語法說明。而除了 UML 之外，PlantUML 還可以繪製甘特圖、心智圖等非 UML 的圖表。

用 Docker-compose 安裝 PlantUML

要使用 PlantUML 需要安裝 Java 以及 GraphViz。我不喜歡在本機環境安裝太多東西，所以一樣使用 Docker-compose 來安裝 PlantUML。docker-compose.yaml 檔案內容如下：

services:
  plantuml-server:
    build:
      context: .
      dockerfile: Dockerfile.jetty
    image: plantuml/plantuml-server:jetty
    container_name: plantuml-server
    ports:
      - 8080:8080
    environment:
      - BASE_URL=plantuml

啟動 docker 後，用瀏覽器打開 http://localhost:8080/plantuml/，就可以看到以下的畫面

左側的輸入框可以輸入 PlantUML 語法，會在右側看到即時的結果，輸入框的選單可以匯出及匯入圖表。

 ┌───┐          ┌─────┐
 │Bob│          │Alice│
 └─┬─┘          └──┬──┘
   │    hello      │   
   │──────────────>│   
 ┌─┴─┐          ┌──┴──┐
 │Bob│          │Alice│
 └───┘          └─────┘

比較有趣的是，匯出可以選擇 ASCII 的形式匯出(如上)，而匯入如果是選擇 PlantUML 匯出的圖片檔(如：.png)，也會在輸入框以代碼的方式呈現，應該是把代碼存入圖片的 meta 中了。

安裝 Sublime Text 的 PlantUML package

雖然可以透過本地端伺網頁使用 PlantUML，但總是沒那麼方便，還要匯出代碼再放到相對應的目錄中才能做版本控制。幸好 PlantUML 與許多文字編輯器都有整合，也包含了我常用的 Sublime Text。

打開 Package Manager，輸入 plantuml，可以看到 PlantUmlDiagrams 這個套件。

安裝完成後，Syntax 選單也會出現 PlantUmlDiagrams，底下有 Diagram 與 DiagramEx 兩種。不過我實際使用上，DiagramEx 這個 Syntax 似乎有點問題，所以我主要是使用 Diagram。

接著設定 PlantUML 的 User Settings，由於 jar 實際上是在 docker 裡，所以我沒有設定。都是透過 server 來產出檔案。

{
    "output_format": "png",
    "plantuml_server": "http://localhost:8080/plantuml/",
    // "jar_file": "C:/Users/plantuml.jar",
    "charset": "UTF-8"
}

Command Palette 中會有兩個選項，分別是 Continually Generate Diagram 以及 Generate Diagrams for Active View。前者應該是可以隨著代碼的修改持續生成圖片，但是推測因為我沒有指定 jar file，所以這個功能實際上跟 Generate Diagrams for Active View 一樣，都是 render 一次而已。

Mac 沒有預設的 Key Bindings，每次都要透過 Command Palette 來產生圖檔也不是很方便，所以我也手動加了 Key Binding。

[
    {"keys": ["super+shift+m"], "command": "display_diagrams"}
]

實際上使用，以簡單的範例來說，在 Sublime Text 中輸入以下文字。

@startuml
Bob -> Alice : hello
@enduml

接著按下 command + shit + m，就會自動產出圖形。

下一步

因為是透過代碼畫圖，所以也可以叫 ChatGPT 幫你畫圖 XD