用例描述说明了参与者如何通过系统与系统交互来实现目标。它是对用例图的补充：

• 用例图：显示参与者、系统范围及它们之间的关系。

• 用例描述：解释详细的行为、条件、规则和结果。

图提供地图，描述提供路线。

1. 什么是用例？

用例代表外部参与者通过系统实现的一个有价值的目标。

示例：

• 客户下订单

• 员工提交费用报销

• 患者预约就诊

• 管理员创建用户账户

• 客户重置密码

一个好的用例应具备：

• 以目标为导向

• 对参与者具有价值

• 从用户视角进行描述

• 独立于具体的屏幕布局

• 专注于可观察的系统行为

不佳的用例名称与改进后的用例名称

使用简短的动词–名词短语，例如提交费用报销, 跟踪发货，或批准贷款申请.

2. 核心概念

2.1 参与者

参与者是与系统交互的外部角色。

参与者可以是：

• 一个人

• 一个组织

• 另一个软件系统

• 一个硬件设备

• 一个计划或基于时间的触发器

示例：

• 客户

• 支持代理

• 仓库管理员

• 支付网关

• 电子邮件服务

• 管理员

参与者是一个角色，不一定是特定个人。例如，“客户”通常比“简·史密斯”更好。

主要参与者和辅助参与者

该主要参与者启动用例以实现目标。

该辅助参与者在执行过程中协助系统。

示例：

• 主要参与者：客户

• 辅助参与者：支付网关

• 用例：下订单

客户发起订单，而支付网关授权支付。

2.2 系统边界

系统边界定义了被建模系统内部的内容。

对于在线商店，边界可能包含：

• 浏览商品

• 将商品添加到购物车

• 下订单

• 进行支付

• 跟踪订单

以下内容在边界之外：

• 客户

• 支付网关

• 配送公司

• 电子邮件服务提供商

该边界防止了对系统职责的混淆。

2.3 用例

用例应描述一个能产生有意义结果的完整交互过程。

例如：

下订单：客户选择商品，提供配送信息，支付订单费用，并收到订单确认。

“验证信用卡号”可能是一个系统功能，但通常太小，无法作为独立的用户目标。它可能只是“下订单或“进行支付.

2.4 前置条件

前置条件说明了用例开始之前必须已经成立的状态。

示例：

• 客户拥有有效的账户。

• 商品可供销售。

• 员工已通过身份验证。

• 预约时段存在。

• 购物车中至少包含一件商品。

前置条件不是用例所执行的操作。

不当的前置条件：

客户登录。

更好的前置条件：

客户已通过身份验证。

2.5 后置条件

后置条件说明了用例结束后必须成立的状态。

示例：

• 订单已被记录。

• 支付已获授权。

• 已发送确认邮件。

• 费用报销单状态为已提交。

• 用户账户标记为活跃状态。

后置条件应描述结果，而非实现细节。

不良的后置条件：

该订单表已更新。

更好的后置条件：

订单已存储并可进行履行。

2.6 主要成功场景

主要成功场景，也称为基本流程或快乐路径，描述了正常的成功交互。

每个步骤应描述：

1. 参与者与系统之间的交互

2. 系统响应

3. 有意义的业务操作

示例：

1. 客户选择商品。

2. 系统显示当前购物车。

3. 客户输入配送信息。

4. 系统验证配送信息。

5. 客户提交订单。

6. 系统请求支付授权。

7. 支付网关授权支付。

8. 系统记录订单。

9. 系统显示订单确认信息。

除非对需求至关重要，否则应避免涉及特定界面的细节。

不佳的步骤：

客户点击右下角的蓝色按钮。

更好的步骤：

客户提交订单。

2.7 备选流程

备选流程描述了主场景的一种有效变体。

示例：

• 客户选择到店自提而非配送。

• 客户使用已保存的支付方式进行付款。

• 管理员批准附带条件的索赔。

• 用户使用一次性代码进行身份验证。

备选流程可能会重新汇入主流程。

示例：

A1. 客户使用已保存的支付方式
在第 6 步，客户选择一种已保存的支付方式。系统使用该方式请求授权，然后继续执行第 7 步。

2.8 异常流程

异常流程描述了不成功或异常的情况。

示例：

• 支付被拒绝。

• 商品缺货。

• 身份验证失败。

• 外部服务不可用。

• 所需数据无效。

异常流程应说明：

• 问题发生的位置

• 系统采取的操作

• 参与者看到的内容

• 用例是结束还是恢复

示例：

E1. 支付被拒绝
在第 7 步，支付网关拒绝该交易。系统显示原因，将订单标记为未付款，并允许客户选择另一种支付方式。

2.9 包含与扩展关系

包含

使用包含当一个用例始终调用另一个可复用行为时。

示例：

• 下订单包含计算总金额

• 下订单包含验证客户身份

• 取款包含验证个人识别码

被包含的行为是必需的。

下订单 <<包含>> 计算总金额

扩展

使用扩展当可选或条件行为补充基础用例时。

示例：

• 下订单可由应用折扣码扩展

• 结账可由添加礼品消息扩展

扩展行为并非总是执行。

应用折扣码 <<扩展>> 下订单

一条有用的规则：

• 包含：“这总是作为用例的一部分发生。”

• 扩展：“这在某些条件下可能发生。”

不要使用包含和扩展仅仅是为了将每个流程拆分成小块。过度分解会使模型难以理解。

2.10 泛化

泛化表示参与者或用例之间的继承关系。

示例：

• 员工是一个通用参与者。

• 经理是一个继承员工行为的专用参与者。

经理 --|> 员工

当专用元素确实是泛化元素的一种类型时，才使用泛化，而不仅仅是因为两个元素共享几个步骤。

3. 标准用例描述模板

以下模板适用于需求文档、项目规格说明和分析模型。

用例 ID:
用例名称:
目标:
范围:
级别:
主要参与者:
辅助参与者:
利益相关者及其利益:

触发器:

前置条件:

最小保证:

成功保证:

主成功场景:
1.
2.
3.

备选流程:
A1.
A2.

异常流程:
E1.
E2.

特殊要求:
- 性能
- 安全性
- 可用性
- 可用性
- 合规性

业务规则:

数据需求:

频率和数量:

假设:

开放问题:

相关用例:

字段说明

4. 示例：下订单

UC-001 — 下订单

目标：
允许客户购买一个或多个产品。

范围：
在线商店

级别：
用户目标

主要参与者：
客户

辅助参与者：

• 支付网关

• 库存服务

• 邮件服务

• 配送服务

利益相关者及其关注点：

• 客户： 希望成功购买产品并收到确认。

• 商店： 希望记录有效订单并收取款项。

• 仓库： 需要准确的履约信息。

• 支付网关： 需要有效的支付请求。

• 配送服务： 需要完整的配送地址。

触发条件：
客户提交购物车以进行结账。

前置条件：

• 购物车中至少有一件商品。

• 商品可供订购。

• 客户提供有效的配送地址。

• 系统能够与支付服务进行通信。

最低保障：

• 未支付的订单不被视为已确认。

• 如果订单无法完成，将通知客户。

• 如果支付失败，预留的库存将被释放。

成功保证：

• 支付已获授权。

• 订单已记录。

• 库存已预留。

• 客户收到确认信息。

• 履约信息已提供给仓库。

主要成功场景

1. 客户查看购物车。

2. 系统显示商品、数量、价格、税费、运费及总计金额。

3. 客户提供配送信息。

4. 系统验证配送信息。

5. 客户选择支付方式。

6. 客户提交订单。

7. 系统检查商品可用性。

8. 系统向支付网关请求支付授权。

9. 支付网关授权支付。

10. 系统创建订单。

11. 系统预留所订购的商品。

12. 系统向客户发送订单确认信息。

13. 系统显示订单编号和预计配送日期。

备选流程

A1. 客户使用已保存的地址

在第 3 步，客户选择之前保存的地址。系统显示该地址并继续执行第 4 步。

A2. 客户使用已保存的支付方式

在第 5 步，客户选择已保存的支付方式。系统使用该方式并继续执行第 6 步。

A3. 客户选择门店自提

在第 3 步，客户选择门店自提而非配送。系统显示可用门店及自提日期，然后继续执行第 5 步。

异常流程

E1. 商品不可用

在第 7 步，系统判定某商品不可用。系统识别该不可用商品，更新购物车，并提示客户重新审核订单。

E2. 支付被拒绝

在第 9 步，支付网关拒绝支付。系统不会确认订单，释放库存预留，显示失败消息，并允许客户选择其他支付方式。

E3. 支付网关不可用

在第 8 步，支付网关未在配置的超时时间内响应。系统将支付尝试标记为待处理，通知客户，并防止重复提交订单。

业务规则

• 订单必须至少包含一个产品。

• 产品数量必须大于零。

• 当可用库存不足时，无法订购该产品。

• 订单确认前必须获得支付授权。

• 价格和税费使用当前定价规则进行计算。

• 客户只能在履行开始前取消订单。

特殊要求

• 在正常负载下，订单摘要应在两秒内显示。

• 支付信息不得以明文形式存储。

• 重复提交不得创建重复订单。

• 系统必须记录支付和订单状态变更的审计轨迹。

5. 用例级别

用例描述可以以不同的详细程度编写。

概要级用例

概要级用例描述一个广泛的业务流程。

示例：

履行客户订单

这可能包括：

• 接收订单

• 拣选产品

• 打包订单

• 发货订单

用户目标级用例

这通常是需求分析中最有用的级别。

示例：

下订单

它描述了一个主要参与者在一次会话中可以实现的目标。

子功能级用例

这描述了一个更小、可复用的系统行为。

示例：

• 计算订单总额

• 验证支付

• 生成发票

当行为被复用或技术复杂时，子功能级用例很有用，但它们不应取代用户目标用例。

6. 编写高质量的用例描述

使用以参与者为中心的语言

从参与者的角度撰写：

客户提交订单。

避免使用以实现为中心的描述：

OrderController 调用订单服务。

后者应属于设计文档，而非业务用例。

保持每个步骤原子化

避免将过多动作合并：

客户输入详细信息、选择支付方式、确认订单并收到电子邮件。

通过分离交互来改进：

1. 客户输入配送信息。

2. 系统验证该信息。

3. 客户选择支付方式。

4. 客户确认订单。

5. 系统发送确认信息。

描述可观察的行为

读者应能判断该需求是否已实现。

弱：

系统处理请求。

更强：

系统验证请求，记录索赔，为其分配索赔编号，并显示提交状态。

避免过早进行用户界面设计

使用：

客户提供配送信息。

而非：

客户将地址输入文本框，然后点击绿色的“继续”按钮。

第二个版本不必要地限制了界面。

保持主流程成功

不要在基本流程中填入所有可能的错误。将错误放入异常流程中。

单独识别业务规则

业务规则通常适用于多个用例。将它们分开可以避免重复和不一致的文本。

明确失败行为

对于每个重要失败，请指定：

• 数据是否已保存

• 事务是否已回滚

• 参与者是否可以重试

• 是否通知管理员

• 用例是结束还是恢复

7. 从需求到用例

一个实用的工作流程是：

1. 识别正在建模的系统。

2. 列出外部参与者。

3. 询问每个参与者想要完成什么。

4. 将每个目标转换为用例名称。

5. 定义系统边界。

6. 编写主要成功场景。

7. 添加替代流程和异常流程。

8. 添加业务规则和特殊要求。

9. 绘制用例图。

10. 与利益相关者一起审查模型。

11. 将用例与需求、测试和设计工件关联起来。

参与者-目标分析

一个有用的问题是：

该参与者需要从系统中获得什么业务结果？

8. 用例图符号

最常见的元素包括：

• 参与者：外部角色

• 用例：系统能力或参与者目标

• 系统边界：系统范围

• 关联：参与者参与某个用例

• 包含：必需的复用行为

• 扩展：可选或条件行为

• 泛化：专用参与者或用例

用例图不应尝试展示以下内容：

• 每个工作流步骤

• 数据库表

• 类属性

• 详细的业务规则

• 屏幕布局

• 内部算法

这些内容应放在活动图、类图、序列图或书面需求中。

9. PlantUML 图表示例

以下示例对“下订单”用例及相关行为进行建模。

@startuml
left to right direction

skinparam packageStyle rectangle
skinparam shadowing false
skinparam usecase {
    BackgroundColor #F8FBFF
    BorderColor #2F5597
    ArrowColor #555555
}

actor Customer
actor "Payment Gateway" as Payment
actor "Inventory Service" as Inventory
actor "Email Service" as Email
actor "Delivery Service" as Delivery

rectangle "Online Store" {
    usecase "Browse Products" as Browse
    usecase "Manage Cart" as Cart
    usecase "Place Order" as PlaceOrder
    usecase "Calculate Order Total" as CalculateTotal
    usecase "Check Product Availability" as CheckStock
    usecase "Authorize Payment" as AuthorizePayment
    usecase "Reserve Inventory" as ReserveInventory
    usecase "Send Order Confirmation" as SendConfirmation
    usecase "Track Order" as TrackOrder
    usecase "Apply Discount Code" as ApplyDiscount
}

Customer --> Browse
Customer --> Cart
Customer --> PlaceOrder
Customer --> TrackOrder

Payment --> AuthorizePayment
Inventory --> CheckStock
Inventory --> ReserveInventory
Email --> SendConfirmation
Delivery --> TrackOrder

PlaceOrder ..> CalculateTotal : <<include>>
PlaceOrder ..> CheckStock : <<include>>
PlaceOrder ..> AuthorizePayment : <<include>>
PlaceOrder ..> ReserveInventory : <<include>>
PlaceOrder ..> SendConfirmation : <<include>>

ApplyDiscount ..> PlaceOrder : <<extend>>

@enduml

解释

• “客户 发起 下订单.

• 下订单 始终包括计算、库存检查、支付授权、库存预留和确认。

• 应用折扣码 是可选的，因此它扩展了 下订单.

• 外部服务参与特定的系统行为。

• 系统边界是 在线商店 矩形。

元素的精确位置由渲染引擎控制。重要的建模决策包括参与者、用例、边界和关系。

10. 在 Visual Paradigm VPasCode 中创建图表

VPasCode 是一个基于浏览器的文本转图表平台，支持 PlantUML、Mermaid、Graphviz 及其他图表格式。它提供源代码编辑和实时渲染，使图表能够随代码变化而自动更新。

基本工作流程

1. 打开 VPasCode 编辑器。

2. 创建一个新的 PlantUML 图表。

3. 粘贴 PlantUML 源代码。

4. 确认编辑器已识别 PlantUML 语法。

5. 查看实时预览。

6. 在源代码窗格中编辑参与者、用例、关系和样式。

7. 导出或复制渲染后的图表。

8. 将图表添加到项目文档中。

VPasCode 支持 PlantUML 用例图，并提供浏览器中的实时渲染。它还提供了 PlantUML 图表的示例和样式选项。

AI 辅助生成的示例提示

如果使用 AI 图表生成功能，一个有用的提示是：

为在线商店创建一个 PlantUML 用例图。

主要参与者：
- 客户

辅助参与者：
- 支付网关
- 库存服务
- 邮件服务
- 配送服务

主要用例：
- 浏览商品
- 管理购物车
- 下订单
- 跟踪订单

下订单必须包括：
- 计算订单总额
- 检查商品可用性
- 授权支付
- 预留库存
- 发送订单确认

应用折扣码应扩展下订单。

使用名为“在线商店”的系统边界。

将生成的代码视为起点。审查是否：

• 参与者确实是外部的

• 用例代表用户目标

• 包含 和 扩展被正确使用

• 系统边界准确

• 关系反映真实的业务行为

VPasCode 还支持在基于文本的图表编辑与 Visual Paradigm 的图形建模工具之间切换，当团队希望基于源代码进行版本控制编辑，同时利用可视化编辑进行布局优化时，这将非常有用。

11. 维护 PlantUML 用例图

使用有意义的别名

别名使关系更易于维护：

usecase "Place Order" as PlaceOrder
Customer --> PlaceOrder

添加注释

' 核心客户交易
usecase "Place Order" as PlaceOrder

注释有助于其他团队成员理解源代码并维护图表。

保持图表聚焦

如果图表包含太多用例：

• 创建上下文图

• 按业务领域创建单独的图表

• 使用包分组

• 通过文档链接相关图表

• 避免在最高层级展示所有子功能

使用一致的命名

选择一种约定并始终如一地应用它：

• 下订单

• 取消订单

• 跟踪订单

避免混合使用如下风格：

• 下订单

• OrderCancellation

• tracking_function

将源代码与项目一起存储

典型的仓库结构可能如下：

docs/
  use-cases/
    UC-001-place-order.md
    UC-002-track-order.md
  diagrams/
    online-store-use-cases.puml

保留.puml源代码纳入版本控制，使得变更可审查且可复现。

12. 可追溯性

成熟的流程将用例与项目的其他工件关联起来。

可追溯性有助于回答：

• 哪些需求已被覆盖？

• 哪些用例尚未测试？

• 哪些设计组件支持业务目标？

• 如果需求发生变化，哪些内容会受到影响？

13. 常见错误

将内部组件建模为参与者

如果数据库或内部服务位于系统边界内部，通常不应将其建模为参与者。

参与者必须位于被建模系统的外部。

将屏幕视为用例

屏幕是用户界面元素，不一定是用户目标。

使用：

提交费用报销

而非：

费用报销屏幕

使用include来表示每个共享步骤

仅凭共享措辞不足以证明包含用例的合理性。应使用include来表示当行为是强制性的且具有独立意义时。

使用extend来表示常规步骤

如果某种行为总是发生，则不应将其建模为扩展。

编写实现细节

避免引用：

• 控制器

• 数据库表

• API 端点

• 类

• 内部方法

除非该文档是专门的技术设计文档。

省略失败行为

如果用例仅解释成功情况，则是不完整的。应涵盖支付拒绝、无效数据、超时、授权失败以及资源不可用等情况。

用例范围过宽

“管理整个业务”不具备可操作性。应将宽泛的目标分解为以用户目标为层级的用例。

用例范围过小

“验证字段”和“显示消息”通常是系统步骤，而非独立的参与者目标。

14. 审查清单

在批准用例描述之前，请验证：

范围与参与者

• 系统边界是否清晰？

• 是否已识别所有外部参与者？

• 参与者是否为角色而非具体个人姓名？

• 是否仅在支持系统为外部系统时才对其进行建模？

目标质量

• 该用例是否为主要参与者提供价值？

• 名称是否为清晰的动宾短语？

• 用例是否处于合适的层级？

流程质量

• 主场景是否描述了成功的结果？

• 每个步骤是否原子化且可观察？

• 是否已记录替代路径？

• 是否已记录异常路径？

• 恢复行为是否清晰？

条件与结果

• 前置条件是否可测试？

• 成功保证是否明确？

• 是否定义了最低限度保证？

• 业务规则是否与操作步骤分离？

图表质量

• 所有用例是否都在正确的边界内？

• 参与者关联是否有意义？

• “包含”关系是否为强制性的？

• “扩展”关系是否为可选或条件性的？

• 图表是否在不包含过多细节的情况下仍可阅读？

需求质量

• 每个重要步骤是否可测试？

• 是否包含了非功能性需求？

• 未解决的问题是否已记录？

• 用例是否与需求和测试用例相关联？

15. 建议的交付物结构

对于完整的项目包，请使用以下结构：

1. 系统上下文
2. 参与者目录
3. 用例图
4. 用例目录
5. 详细用例描述
6. 业务规则
7. 非功能性需求
8. 可追溯性矩阵
9. 开放问题与假设
10. PlantUML 源文件

优秀的用例描述应足够精确以满足分析师的需求，让利益相关者易于理解，并能由质量保证团队进行测试。最佳工作流是：使用书面描述来定义行为，使用用例图来传达范围和关系，并在 VPasCode 中使用 PlantUML 以保持可视化模型易于编辑和维护。

参考资料