跳到主要内容

State Machine (stateDiagram-v2) 範本

用途：狀態轉換、lifecycle、UI flow、Pipeline 狀態

適用場景：

  • 「這個訂單從建立到完成有哪些狀態」
  • 「設備 state model」
  • 「Pipeline 的 IDLE → RUNNING → COMPLETED」

注意：用 stateDiagram-v2（v1 已過時），不要寫 stateDiagram。

範本 1：基本狀態機​

關鍵語法：

  • [*] 起始/終止狀態
  • --> 狀態轉換
  • : 文字 轉換條件

範本 2：含 Guard Condition 的狀態機​

使用時機：Pipeline、工作流程、設備 state model。

關鍵技巧：用 [condition] 表達 guard condition。

範本 3：巢狀狀態（複合狀態）​

使用時機：狀態裡還有子狀態（如：設備「運轉中」底下還有 idle/running/paused）。

範本 4：平行狀態（Fork / Join）​

使用時機：需要平行處理的流程（金流、庫存同時檢查）。

範本 5：含 Note 說明​

使用時機：需要為某個狀態加詳細說明時。

客製化指南​

狀態命名​

  • ✅ 大寫（如 IDLE、RUNNING）— 符合慣例
  • ❌ 避免動詞（如 Processing 而非 Process）

Transition 標註​

  • 簡單：只寫事件名（start）
  • 完整：寫事件 + guard（report_completion(pass)<br/>[all done]）

何時用 stateDiagram vs flowchart​

情境用 stateDiagram用 flowchart
明確有「狀態」概念（如 IDLE/RUNNING）✅❌
只是流程步驟❌✅
有進入/離開狀態✅❌
決策樹❌✅

Real-world 範例​

  • internal/workflow/pipeline-state-machine.md — Pipeline 完整狀態機

Anti-patterns​

❌ 沒有起始/終止​

A --> B
B --> C

應該是：

[*] --> A
A --> B
B --> C
C --> [*]

❌ 狀態名用動詞​

Start --> Process --> Finish

應該是：

Started --> Processing --> Completed

❌ transition 無說明​

IDLE --> RUNNING

應該寫觸發條件：

IDLE --> RUNNING : user clicks Start