老居生活筆記: 在 Neovim 使用 plantuml-previewer.vim 為專案繪製設計文件

2023-03-09

在 Neovim 使用 plantuml-previewer.vim 為專案繪製設計文件

如何在 Neovim 啟用 PlantUML 的教學影片

常言道：「文不如表，表不如圖；一圖勝過千言萬語」。可知圖像給予人們的感覺，比文字乃至表格，更為強而有力。

UML (Unified Modeling Language，中文譯名：「統一塑模語言」），這套透過圖形規範，針對「軟體」塑形造模的方法論，自推出以來，廣被當作：描述系統／軟體架構，乃至軟體設計的工具。

以個人而言，我相信：「在軟體專案導入UML 圖，可協助我檢驗軟體設計的合理化，乃至在檢驗的過程中，察覺思考上的錯誤，乃至系統埋下了潛在的問題。個人好用的UML 圖為：循序圖及類別圖。我好使用循序圖來表達「功能細部設計」；而類別圖則用於描述軟體的 Domain Model 。在繪圖的過程，經常會發現原先未考量之事，所以程式碼在尚未動手撰寫前，便已先行「重構」和優化，避免了事後的重工，乃至除錯工作。」

雖說使用 UML 圖，對於軟體的開發有著諸多的好處。但也不得不承認，手工繪圖是件細鎖的煩人事。UML圖能為軟體開發人員帶來效益，但製圖過程卻費力耗時的反作用力，反而使人寧可放棄的問題，似乎被某些天賦異稟的軟體天才所發現，於是乎，這世界有了：PlantUML 的發明。PlantUML 的迷人之處在於：可用「文字敘述」描繪製作 UML 圖。

在 Neovim 眾多的 Plugins 中，plantuml-previewer.vim可供使用者在 Neovim 中「描繪」及「預覽」繪圖的成果。

  -- PlantUML
  use({ "weirongxu/plantuml-previewer.vim" })
  -- PlantUML syntax highlighting
  use({ "aklt/plantuml-syntax" })
  -- provides support to mermaid syntax files (e.g. *.mmd, *.mermaid)
  use({ "mracos/mermaid.vim" })

以下是個展示範例：在使用 Django 開發「部落格（Blog）」的專案中。欲使用「循序圖（Sequence Diagram）」描述的「閱讀某則貼文」的功能規格。

閱讀貼文（Post）的文字描述

「描繪」此功能的循序圖，其「描述」文字如下：

@startuml
autonumber "[00]"

actor    User
control	 Django.Router		as Router
control  Django.Template	as Template
boundary post_detail     	as View
boundary CommentForm     	as Form
entity   Post				as Model
entity   Comment			as Comment
database database			as DB

User -> Router : url: /blog/  (post_detail)
Router -> View : post_detail(request, year, month, day, post)
View -> Model : get_object_or_404(Post, slug=post, \n status='published', publish__year=year, \n publish__month=month, publish__day=day)
Model -> DB : sql_query()
DB --> Model : post
Model --> View : post
View -> Comment: post.comments.filter(active=True)
Comment --> View: comments
View -> Form: CommentForm()
Form --> View: form
View --> Template: render(request, \n uri_of_template, \n {post, comments, form})
Template --> User: /blog/post/list.html
@enduml

最後，在文章結束之前，提供以下一些參考資料。希望對想了解 PlantUML 多一點；或是「如何在 Neovim 導入 PlantUML 之人」，能有所助益！