编写用例文档

文档中应包括哪些部分，为什么要包括这些部分

Scott W. Ambler
Ronin International 总裁
2000 年 10 月 5 日

内容：

Scott Ambler 阐明了基本用例和系统用例之间的区别，并针对如何编写这两类用例的文档提出了一些建议（主要讨论系统用例）。本文由《The Object Primer 2 ^nd Edition》的第三章改编而来。

当记录基于组件的系统的行为需求时，用例是最常用的技术之一。开发人员常问的一个问题是，“用例文档应该包括哪些信息？”尽管我在此提到的一些部分是可选的，但在我看来，将这些部分包括在用例文档中不失为一个好主意。当编写基本用例的文档时（另请参阅前一篇技巧 Modelling essential use cases），我倾向于略去可选部分（因为基本用例关注的是是什么，而不是 为什么，因此不必像系统用例那样复杂）。当编写系统用例时，我通常将所有部分都包括在内。回顾一下，基本用例和系统用例之间的主要区别是，系统用例包括了高级实现决策，而基本用例是要以与技术和实现无关的方式捕捉用户的意图。

参与者 (actor) 和被包含的用例这两个部分实际上只看用例图即可确定。但是，按我的经验，各个用例最好相互独立 — 换句话说，用例应该包含理解它们所需的全部关键信息以及它们所在的上下文。这使您的主题问题专家 (SME) 能够分别充实各个用例。（他们可能上午以小组为单位协同工作，下午则各自独立地以最快的速度充实所分配的用例，从而提高了整个小组的生产效率。）

用例的各个组成部分

• 名称。名称无疑应该表明用户的意图或用例的用途，如“研究班招生”。
• 标识符 [可选]。唯一标识符，如 "UC1701"，在项目的其他元素（如类模型）中可用它来引用这个用例。
• 说明。概述用例的几句话。
• 参与者 [可选]。与此用例相关的参与者列表。尽管这则信息包含在用例本身中，但在没有用例图时，它有助于增加对该用例的理解。
• 状态 [可选]。指示用例的状态，通常为以下几种之一：进行中、等待审查、通过审查或未通过审查。
• 频率。参与者访问此用例的频率。这是一个自由式问题，如用户每次录访问一次或每月一次。
• 前置条件。一个条件列表，如果其中包含条件，则这些条件必须在访问用例之前得到满足。
• 后置条件。一个条件列表，如果其中包含条件，则这些条件将在用例成功完成以后得到满足。
• 被扩展的用例 [可选]。此用例所扩展的用例（如果存在）。扩展关联是一种广义关系，其中扩展用例接续基用例的行为。这是通过扩展用例向基用例的操作序列中插入附加的操作序列来实现的。这总是使用带有 <> 的用例关联来建模的。
• 被包含的用例 [可选]。此用例所包含用例的列表。包含关联是一种广义关系，它表明对处于另一个用例之中的用例所描述的行为的包含关系。这总是使用带有 <> 的用例关联来建模的。也称为使用或具有 (has-a) 关系。
• 假设 [可选]。对编写此用例时所创建的域的任何重要假设。您应该在一定的时候检验这些假设，或者将它们变为决策的一部分（请参阅下文），或者将它们添加到操作的基本流程或可选流程中。
• 基本操作流程。参与者在用例中所遵循的主逻辑路径。因为它描述了当各项工作都正常进行时用例的工作方式，所以通常称其为 适当路径 (happy path) 或主路径 (main path) 。
• 可选操作流程。用例中很少使用的逻辑路径，那些在变更工作方式、出现异常或发生错误的情况下所遵循的路径。
• 修改历史记录 [可选]。关于用例的修改时间、修改原因和修改人的详细信息。
• 问题 [可选]。如果存在，则为与此用例的开发相关的问题或操作项目的列表。
• 决策。关键决策的列表，这些决策通常由您的 SME 作出，并属于用例的内容。将这些决策记录下来对于维护团体记忆库 (group memory) 是相当重要的。