需求工程构成了任何成功软件项目的基础。在各种可用的技术中，用例描述仍然是从用户角度捕捉功能需求最有效的方法之一。一个编写良好的用例能够弥合业务需求与技术实现之间的差距，确保所有利益相关者对系统行为有统一的理解。
然而，这些描述中的模糊性常常导致开发错误、范围蔓延和测试失败。本指南提供了一种结构化的方法，使用统一建模语言（UML）标准来编写精确且可操作的用例描述。通过遵循既定模式，团队可以创建出既作为设计蓝图又作为验证检查清单的文档。
🔍 理解核心组成部分
在撰写叙述性文本之前，必须明确构成完整用例的结构元素。这些组件确保场景具有边界且可度量。
1. 执行者 🧍
执行者代表与系统交互的实体所扮演的角色。执行者位于系统边界之外。它们可以是：
- 人类执行者：真实的人，例如客户、管理员或技术人员。
- 外部系统：触发或接收数据的其他软件或硬件接口。
- 基于时间的执行者：由时钟或定时器触发的事件，例如计划的备份过程。
定义执行者时，应分配具体角色而非具体职位名称。例如，使用“注册用户”而非“约翰·多伊”。这样即使人员变动，需求依然有效。
2. 系统边界 ⬜
系统边界定义了软件内部与外部的内容。它明确了责任归属。方框内的所有内容都是系统；方框外的所有内容都是环境。这一区分对于确定特定错误或操作的责任方至关重要。
3. 目标 🎯
每个用例代表执行者希望实现的单一目标。如果描述中包含多个无关的目标，则应将其拆分为独立的用例。单一目标可确保用例保持可测试性和可管理性。
📋 用例描述的结构
全面的描述不仅限于简单的图表。它还需要一个详细的文本说明，以描述交互流程。以下是专业需求文档中使用的标准结构。
元数据与标识
- 用例ID：用于追踪的唯一标识符（例如，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、名称和流程的结构化格式。
- 将主成功场景与替代流程和异常流程分开。
- 使用主动动词和具体术语。
- 在开发开始前与利益相关者验证描述。
投入时间编写清晰的需求在整个项目生命周期中都会带来回报。它能减少返工，明确期望，确保最终产品满足用户的实际需求。
