用 Markdown 畫循序圖小記
有時候寫設計文件、 API 溝通文件或除錯筆記時，只靠文字描述流程其實很吃力。像是「前端先呼叫 API，API 再查 DB，查不到就回錯誤，查到再呼叫第三方服務」這種流程，文字一長就容易讓人失焦。
這時候循序圖就很好用，因為它很適合表達「誰先呼叫誰、資料怎麼流動、同步還是非同步、回應在哪裡回來」。而 Markdown 最大的好處，就是可以把圖跟說明放在同一份文件裡，不用另外開畫圖工具。
循序圖適合拿來畫什麼
循序圖最適合描述這類問題：
- 一個需求從使用者操作到後端完成，中間經過哪些系統。
- 多個服務之間的呼叫順序。
- 同步與非同步流程差異。
- 錯誤處理或 timeout 發生在哪個階段。
如果只是想表達系統有哪些模組，可能類別圖或架構圖比較適合；但如果重點是「順序」，我通常先想到循序圖。
現在比較推薦直接用 Mermaid
早期很多 Markdown 平台會支援 sequence 這種語法，但不同平台支援度不一致。現在如果是自己管文件系統、部落格或 Git 平台，通常我會優先用 Mermaid，因為：
- 語法比較常見。
- 支援度比較高。
- 之後要放到 GitHub、GitLab、Hugo 或其他文件平台，比較容易沿用。
一個最基本的 Mermaid 循序圖長這樣：
這種寫法拿來畫 API 請求、登入流程、排程執行流程都很直觀。
如果你的環境還支援舊語法
我以前也有記過 sequence 這種寫法，範例如下：
|
|
如果你手上的 Markdown 工具剛好支援，還是可以繼續用。不過新專案如果沒有歷史包袱，我會建議直接改用 Mermaid。
常用箭頭怎麼看
不管是舊語法還是 Mermaid，核心觀念其實差不多，重點是箭頭代表的意思：
|
|
最常見的用法是：
- 請求用
->>或-> - 回應用
-->>或-->
像「程式回傳結果」這種，我自己通常會用虛線箭頭來區分，看圖時會更容易理解哪段是 request、哪段是 response。
一個比較接近實務的範例
下面這個範例是登入流程，包含驗證失敗的分支：
這種圖的價值在於，光看圖就能知道：
- 驗證邏輯在哪裡。
- session 寫到哪裡。
- 成功與失敗分支怎麼走。
畫圖時我自己會注意的事
-
參與者名稱不要太抽象。
例如直接寫Frontend、Order API、Redis，通常比系統 A、系統 B好懂。 -
一張圖只講一件事。
如果把登入、權限檢查、寄信通知、審核流程全部塞在同一張圖，最後通常會看不懂。 -
回應與請求最好用不同箭頭習慣表示。
團隊看久了會形成默契，文件閱讀成本會很低。 -
錯誤分支最好畫出來。
很多 bug 都是在 timeout、驗證失敗、重試這些分支發生的。
小結
如果只是想快速把流程畫出來，Markdown 加 Mermaid 真的很省時間。尤其在需求討論、 code review、 issue 說明或 incident 復盤時，循序圖往往比一大段文字更快讓人進入狀況。
我自己現在的做法是：先用文字列出參與者，再把關鍵步驟轉成循序圖。這樣文件不會只有圖，也不會只有字，工程師讀起來會舒服很多。
參考資料：