需求工程構成了任何成功軟件專案的基石。在各種可用技術中，用例描述仍然是從用戶角度捕捉功能需求最有效的方法之一。一個撰寫良好的用例能夠彌合業務需求與技術實現之間的差距，確保所有利益相關者對系統行為有統一的理解。
然而，這些描述中的模糊性經常導致開發錯誤、範圍蔓延和測試失敗。本指南提供了一種結構化的方法，利用統一建模語言（UML）標準來撰寫精確且可執行的用例描述。透過遵循既定的模式，團隊可以創建出既可用作設計藍圖，又可用作驗證清單的文檔。
🔍 理解核心組件
在撰寫敘述性文字之前，必須明確界定構成完整用例的結構元素。這些組件確保情境具有明確的邊界且可衡量。
1. 作用者 🧍
作用者代表與系統互動的實體所扮演的角色。作用者位於系統邊界之外。它們可以是：
- 人類作用者：真實的人，例如顧客、管理員或技術人員。
- 外部系統：觸發或接收資料的其他軟體或硬體介面。
- 基於時間的作用者：由時鐘或計時器觸發的事件，例如定時備份程序。
定義作用者時，應分配具體的角色而非具體的職稱。例如，使用「註冊使用者」而非「John Doe」。這樣即使人員變動，需求仍能保持有效。
2. 系統邊界 ⬜
系統邊界定義了軟體內部與外部的範圍。它明確了責任歸屬。方框內的一切都是系統；方框外的一切都是環境。這種區分對於確定特定錯誤或動作的責任人至關重要。
3. 目標 🎯
每個用例代表作用者希望達成的單一目標。如果描述中包含多個無關的目標，則應拆分為獨立的用例。單一目標可確保用例保持可測試且易於管理。
📋 用例描述的結構
完整的描述不僅僅是簡單的圖示。它需要詳細說明互動流程的文字規範。以下是專業需求文檔中使用的標準結構。
元資料與識別資訊
- 用例編號：用於追蹤的唯一識別碼（例如：UC-001）。
- 用例名稱：由動詞-名詞短語描述的動作（例如：「提交訂單」）。
- 主要作用者：啟動動作的主要使用者。
- 次要作用者：任何支援系統或使用者。
- 優先級：關鍵、高、中或低。
前置條件
前置條件定義了用例開始前系統的狀態。如果這些條件未滿足，用例便無法啟動。這有助於測試人員理解所需的設定。
- 使用者必須已登入系統。
- 購物車中必須至少包含一件商品。
- 付款網關必須處於線上狀態。
後置條件
後置條件描述了用例成功完成後系統的狀態。它們作為功能的接受標準。
- 資料庫中會建立一筆新的訂單記錄。
- 會向使用者發送電子郵件確認訊息。
- 庫存數量會被更新。
事件流程
這是描述的核心。它概述了參與者與系統所執行的步驟順序。通常分為主要成功情境與延伸情境。
🚀 主要成功情境（順利路徑）
主要成功情境描述了所有事情都順利進行的理想路徑。過程中沒有錯誤、中斷或替代決策。每個步驟都必須是原子性的，也就是單一動作，無法再細分而不失去意義。
撰寫這些步驟時，請遵循以下原則：
- 為步驟編號： 使用 1、2、3… 來表示順序。
- 明確指出來源： 明確指出是誰啟動了該步驟（參與者或系統）。
- 使用主動動詞： 以動作詞開頭，例如「選擇」、「輸入」、「顯示」或「驗證」。
- 避免使用技術術語： 描述使用者所看到的內容，而非背後的資料庫查詢。
🛑 替代與例外流程
現實世界中的使用情況很少遵循完美路徑。延伸情境用來處理與主要流程的偏差。這對於穩健的需求收集至關重要。
替代流程
當參與者選擇與主要路徑不同的選項時，就會發生這些情境。它們仍會達成相同的目標，只是途徑不同。
- 範例： 使用者選擇在結帳時套用折扣碼。
例外流程
當發生錯誤時就會出現這些情況。系統必須妥善處理錯誤。用例的目標可能會失敗，也可能會恢復。
- 範例： 網關返回錯誤訊息。
- 範例： 使用者資金不足。
擴展應參考主成功場景中出現偏差的具體步驟編號。
📝 實際範例：「處理付款」
為了說明這些概念，請考慮一個通用的付款處理場景。此範例示範如何將抽象概念轉化為具體步驟。
| 步驟 | 參與者/系統 | 動作 | 回應 |
|---|---|---|---|
| 1 | 參與者 | 選擇「立即付款」按鈕。 | – |
| 2 | 系統 | 顯示付款表單。 | 表單出現，並包含信用卡欄位。 |
| 3 | 參與者 | 輸入信用卡資訊。 | – |
| 4 | 系統 | 驗證信用卡資料。 | 檢查格式與到期日。 |
| 5 | 系統 | 將交易提交至網關。 | – |
| 6 | 網關 | 返回授權。 | 成功或錯誤代碼。 |
| 7 | 系統 | 確認付款。 | 顯示成功畫面。 |
替代流程 A（無效卡片）：
- 在第 4 步，如果驗證失敗，顯示錯誤訊息。
- 允許使用者重新輸入資料。
替代流程 B（逾時）：
- 在第 5 步，如果網關在 10 秒內未回應，顯示逾時訊息。
- 允許使用者重試或取消。
🛠 清晰與精確的最佳實務
撰寫需求是一項隨著練習而提升的技能。遵循特定標準可減少業務分析師、開發人員與測試人員之間的誤解。
1. 保持細緻度
不要將多個動作合併為一個步驟。如果某一步驟要求使用者點擊按鈕，然後輸入文字，應將其拆分為兩個步驟。細緻度可確保為每個具體互動撰寫測試案例。
2. 避免假設
永遠不要假設使用者了解技術術語。除非介面明確顯示，否則避免使用「解析」、「提交」或「快取」等詞語。應描述結果，而非機制。
3. 語彙的一致性
使用受控詞彙。如果在某一節中稱之為「產品」，在另一節中就不應稱為「項目」。不一致會讓開發人員混淆，並導致資料庫對應錯誤。
4. 關注行為，而非實作
描述系統做了什麼，而非如何執行。例如，應寫「系統檢查庫存」，而非「系統查詢 SQL 庫存表格」。前者讓實作團隊能選擇最佳技術。
⚠️ 應避免的常見陷阱
即使經驗豐富的撰寫者也會犯錯。及早識別這些模式可避免在開發週期後期重做。
陷阱 1：「神級用例」
當單一使用案例試圖完成太多任務時，就會發生這種情況。如果一個使用案例有50個步驟，很可能涵蓋了多個目標。應將其拆分為更小、更專注的使用案例。
陷阱2：遺漏前置條件
跳過前置條件會讓測試人員對初始狀態感到困惑。這通常會導致不穩定的測試，因為環境未正確設置，測試會隨機失敗。
陷阱3：模糊的動詞
避免使用「管理」、「處理」或「執行」等詞語。這些詞語過於寬泛。應改用「更新」、「刪除」、「計算」或「發送」。精確的用詞能消除歧義。
陷阱4：混雜細節層級
不要將高階業務目標與低階的UI點擊混在一起。主成功場景應保持在邏輯層級。UI細節可於線框圖或UI規格中另行記錄。
🔗 與其他規格的整合
使用案例並非孤立存在。它們與需求文件中的其他實體相互關聯。
- 可追溯性：每個使用案例都應對應到具體的使用者故事或業務目標。這確保每個功能都有其目的。
- 測試案例：主成功場景中的步驟可直接轉換為正面測試案例。擴展部分則轉換為負面測試案例。
- UI設計：參與者和步驟會影響導航結構與畫面配置。
- 資料庫設計：步驟中提到的資料（例如「輸入信用卡」）會影響資料模型的需求。
📊 比較：有效與無效描述
良好需求與不良需求之間的差異，通常在於細節程度與清晰度。下表突顯了這些差異。
| 功能 | ❌ 無效描述 | ✅ 有效描述 |
|---|---|---|
| 參與者 | 「使用者」 | 「註冊管理員」 |
| 步驟 | 「處理登入」 | 「輸入使用者名稱和密碼」 |
| 結果 | 「系統檢查存取權限」 | 「系統會根據資料庫驗證憑證」 |
| 例外 | 「如果失敗」 | 「如果憑證錯誤，顯示錯誤訊息並重設欄位」 |
| 範圍 | 「管理所有內容」 | 「檢視和編輯使用者個人檔案」 |
請注意，有效的描述會提供具體的動作與明確的界線。這能降低開發人員實作功能時的認知負擔。
🧩 處理複雜情境
並非所有需求都適合簡單的線性流程。有些情境涉及平行流程或條件邏輯。
包含與擴展關係
在UML中，用例之間可以相互關聯。一個包含關係發生在一個用例總是需要另一個用例才能運作的情況下。例如，「下訂單」總是包含「驗證付款」。這能減少描述中的重複。
一個擴展關係允許一個用例在特定條件下向另一個用例新增行為。例如，「套用折扣」僅在使用者擁有優惠碼時才會擴展「下訂單」。
並行流程
對於複雜系統，單一流程可能不夠。應使用子流程或獨立圖表來表示並行活動。確保這些流程之間的互動點明確定義。
🔍 審查與驗證
描述撰寫完成後，必須進行驗證。文件在獲得相關利益相關者審查前，不能視為完整。
- 走查：與業務負責人進行走查。請他們閱讀步驟，並確認是否符合其心智模型。
- 可行性檢查：與資深開發人員討論。確保這些步驟在專案限制下技術上可實現。
- 完整性：檢查是否有遺漏的錯誤路徑。如果網路中斷會怎麼樣？如果資料庫已滿又會如何？
- 一致性：確保整個需求文件中的術語一致。
🛠 工具與格式
用例描述的格式可根据專案需求而有所不同。常見的格式包括：
- 結構化文字： 適合用於 Word 或 Google Docs 的編號清單格式。
- 表格格式： 便於快速瀏覽的表格佈局，通常用於試算表中。
- 資料庫項目： 儲存在需求管理工具中，以確保可追蹤性。
- 維基頁面： 可協作的頁面，支援版本歷史記錄與連結功能。
無論使用何種媒介，內容結構都保持一致。目標是可存取性與清晰性，而非特定的檔案類型。
🔗 從需求到測試
用例描述的最終價值在於其在測試階段的實用性。測試人員利用主要成功場景來定義「順利路徑」測試，並利用擴展內容來定義「負面路徑」測試。
若用例描述模糊不清，測試案例將不完整。這會導致覆蓋範圍出現漏洞，並讓缺陷進入生產環境。清晰的描述可作為業務與工程團隊之間的合約。
📈 衡量品質
要如何判斷你的用例品質是否良好？請留意以下指標：
- 可測試性： 測試人員能否僅憑此文字撰寫出測試案例？
- 無歧義性： 是否只有一種可能的解釋？
- 可追蹤性： 是否能將其與業務目標連結起來？
- 完整性： 是否涵蓋所有主要路徑與例外情況？
🏁 重點總結
撰寫有效的用例描述需要紀律與細節關注。這不僅僅是記錄系統的功能，更在於定義其行為的邊界。透過專注於原子步驟、明確的前置條件，以及穩健的例外處理，團隊能減少歧義，並提升交付品質。
需要記住的關鍵要素包括：
- 明確定義參與者與系統邊界。
- 使用包含 ID、名稱與流程的結構化格式。
- 將主要成功場景與替代與例外流程分開。
- 使用主動動詞與具體術語。
- 在開發開始之前，與相關方驗證描述內容。
花時間撰寫清晰的需求，能在整個專案生命週期中帶來回報。這能減少重做工作，明確期望，並確保最終產品符合使用者的實際需求。
