连接愿景与执行：掌握用例描述的案例研究

Table of Contents hide

1 引言

2 1. 基础概念

3 2. 标准规范模板

4 3. 案例研究叙述：UC-201 取现

引言

在现代软件工程中，需求不一致仍然是导致项目延期、范围蔓延和利益相关者不满的主要原因。尽管用例图等可视化建模技术能够有效展示系统边界、参与者和高层次目标，但它们本质上缺乏开发、测试和质量保证所需的详细信息。这正是 用例描述 变得不可或缺。

精心编写的用例叙述能够将抽象的系统目标转化为可操作的、分步的规范。通过记录精确的交互、决策点和错误处理路径，团队建立了一个单一的真相来源，使产品负责人、开发人员、测试人员和业务分析师保持一致。本案例研究探讨了有效用例文档的构成要素，展示了结构化叙述、标准化模板和互补的可视化模型如何融合，生成清晰无歧义的功能规范。通过一个实际的ATM取款场景，我们将探讨如何捕捉业务逻辑、管理偏差，并从概念到实现保持可追溯性。

Mastering Use Case Descriptions

1. 基础概念

在编写详细规范之前，必须理解赋予用例结构完整性的核心组成部分：

参与者： 任何与系统交互以实现目标的实体（人、外部系统或硬件）。
- 主要参与者： 发起交互以实现特定目标（例如，银行客户）。
- 次要/支持参与者： 在执行过程中向系统提供必要服务或数据（例如，核心银行API或支付网关）。
前置条件： 用例开始前系统或环境必须已存在的状态。这些条件被视为成立，且在流程中不进行验证。
触发事件： 触发用例的特定事件或用户操作。
主成功场景（基本流程）： 导致参与者目标成功完成的最优、无错误的步骤序列。通常被称为“愉快路径”。
扩展 / 可选与异常流程： 对主流程的已记录偏离。
- 可选流程： 实现相同目标的不同有效路径（例如，使用不同的支付方式）。
- 异常流程： 中断目标并需要特定处理的错误条件、验证失败或系统约束。
后置条件： 用例成功完成后系统、数据或环境的确定状态。

2. 标准规范模板

一致性对于可维护性至关重要。以下模板提供了一种广泛采用的结构，确保完整性的同时避免不必要的冗余：

字段	描述
用例ID与名称	一个唯一的标识符和一个动词-名词标题（例如，`UC-201：取现`).
参与者	列出所有主要和次要参与者。
描述	用例目的和业务价值的简明摘要。
前置条件	启动前所需的系统或环境状态。
触发事件	启动交互的精确事件。
主成功场景	编号的、按顺序的步骤，详细说明默认的成功路径。
扩展/异常	与特定主场景步骤对应的分支流程（例如，`3a`, `8b`).
后置条件	成功完成后系统的最终状态。

3. 案例研究叙述：UC-201 取现

以下规范展示了该模板和基础概念如何应用于现实世界的银行场景。

用例ID与名称： UC-201 - 取现
主要参与者：银行客户
次要参与者：核心银行系统 / ATM网络
描述：描述已认证的银行客户如何使用自动柜员机（ATM）从其支票账户或储蓄账户中取现。
前置条件：ATM保持活跃的网络连接，并且拥有足够的现金。
触发条件：客户将银行卡插入ATM读卡器。

主成功场景（基本流程）

系统读取银行卡并提示输入个人识别号码（PIN）。
客户输入其PIN。
系统与核心银行系统验证PIN。
系统显示可用的交易选项。
客户选择“取现”。
系统提示选择账户类型（支票/储蓄）和取款金额。
客户选择目标账户并输入可用金额。
系统与核心银行系统核验资金是否充足。
系统扣除账户金额，并命令现金发放装置释放指定金额。
系统发放现金，弹出银行卡，并打印交易凭条。
客户领取现金、银行卡和凭条。

扩展（替代与异常流程）

3a. 无效PIN：
1. 系统通知客户PIN错误，并要求重新输入。
2. 客户输入新的PIN。
3. 返回第3步继续。
4. 异常：如果客户连续三次输入无效PIN，系统将保留银行卡并终止会话。
8a. 资金不足：
1. 系统显示“资金不足”错误，并提示客户输入更低金额或取消操作。
2. 客户选择“取消”。
3. 系统退出卡片并终止会话。

后置条件

交易被安全记录，账户余额被准确更新，ATM实际现金库存相应减少，终端重置为空闲欢迎界面。

4. 编写最佳实践

为确保用例描述保持可操作性、可扩展性和对开发人员友好，应遵循以下既定准则：

保持黑盒视角： 记录什么系统从用户视角所执行的操作，而非如何其内部实现方式。避免引用数据库模式、API端点或UI像素位置。
使用主动语态与清晰语法： 使用直接的主谓结构以消除歧义。
- 避免： “系统评估PIN。”
- 推荐： “系统验证PIN。”
明确映射扩展： 始终将替代流程和异常流程直接关联到它们分叉的步骤编号（例如，5a 从步骤5分叉）。这有助于保持可追溯性并简化测试用例的生成。
聚焦基本业务流程（EBP）： 每个用例应代表一个由单一参与者对单个业务事件作出的完整且有价值的任务。避免记录细粒度的UI点击或系统微交互。
区分前置条件与触发器： 前置条件是一种静态状态（例如，“用户具有活跃会话”），而触发器是一种动态操作（例如，“用户点击‘提交订单’”）。将二者区分开来可防止逻辑重叠和范围混淆。

5. 可视化系统交互

虽然文字叙述提供深度，但可视化模型能立即呈现结构清晰性。在规范中整合用例图和时序图，可确保利益相关者对系统边界和时间执行达成统一理解。

A. 用例关系图

该图描绘了参与者之间的交互，定义了系统边界，并展示了可重用行为之间的包含关系。

PlantUML

在VPasCode中编辑PlantUML

PlantUML Edit PlantUML in VPasCode

@startuml
skinparam theme plain
skinparam packageStyle rectangle

actor "银行客户" as customer
actor "核心银行系统" as bank

rectangle "ATM系统" {
    usecase "取现" as UC_Withdraw
    usecase "查询余额" as UC_Balance
    usecase "用户认证" as UC_Auth
    
    ' 包含关系
    UC_Withdraw ..> UC_Auth : <<include>>
    UC_Balance ..> UC_Auth : <<include>>
}

customer --> UC_Withdraw
customer --> UC_Balance
UC_Withdraw --> bank
UC_Balance --> bank
@enduml

Edit PlantUML in VPasCode

在VPasCode中编辑PlantUML

B. 主成功场景的顺序图

该图将主成功场景（取现用例）转化为时间顺序图，清晰地展示了消息传递流程、同步点以及系统之间的交接。