简介以“好食上餐厅管理系统”为案例的用例文档面向软件工程学习者、需求分析师及开发测试人员帮助理解如何将系统功能与非功能需求文档化。文档依次覆盖前言、编写目的、背景与内容概述、用例列表、用例图及用例描述在用例描述部分对店内顾客订餐、电话订餐、网上订餐、客户资料管理、账单处理、顾客反馈信息管理、连锁店管理等均给出前置条件、触发条件、基本流程、扩展流程与特殊要求等要素并以“店内顾客订餐”示例展示从选餐、服务员记录到订单确认的完整路径便于对照练习和团队需求评审。下载包共1个文件docx格式大小约2.9MB适合有基础的需求编写人员参考其结构模板也可直接用于课程设计或项目文档底稿。该文档已有615人浏览学习对于希望快速掌握用例文档规范写法、准备软件工程实训报告的读者具有直接借鉴价值。1. 一份写着“待确定问题”的用例文档为什么比“全写好了”的更可信很多项目组拿到的需求文档打开全是“已完成”“已确认”真正进入开发后才发现边界全是模糊的。好食上餐厅管理系统这份用例文档不太一样它把店内订餐、电话订餐、网上订餐拆成三组独立用例把“个性化菜单反馈时间必须控制在 1 秒内”写进特殊需求甚至老老实实标注了三个“待确定问题”。这份文档的读者是客户、需求分析团队和系统设计者但从开发与测试的视角看同样能从中榨出大量信息——用例粒度怎么控制、异常分支怎么补、性能约束怎么落进表结构都是可以直接复用的经验。适合准备写用例文档、或者正在从旧文档里抢救需求的人读。2. 从用例列表到用例图参与者识别与用例粒度控制一个好的用例列表不是把功能点平铺出来而是按角色、渠道、数据生命周期三个维度切出来的。好食上这份文档的 7 组用例恰好是这三刀切出来的结果。2.1 三个切口角色、渠道、数据生命周期先看角色切口。文档里的主参与者明确区分了营业员、接线员、送货员、系统管理员和顾客营业员管店内订单录入与账单核验接线员管电话订餐系统管理员管顾客资料数据库的维护与账单汇总顾客直接操作网上订餐平台。参与者不同同一个业务动作的权限、界面、异常处理方式都不同所以用例一定要按主参与者分开写。再看渠道切口。同样是“订餐”店内订餐1.1是营业员从服务员手里接过纸面订单再录入电话订餐2.1是接线员边与顾客通话边录入网上订餐3.1则是顾客自己录入、系统直接收单。三条链路的输入来源、校验方式、后续动作都不同如果合并成一个“订餐用例”后面做接口设计和测试用例时必然要反复拆开。最后看数据生命周期切口。顾客资料管理这组用例里4.1 分析账单维护顾客资料数据库、4.2 顾客分类提供优惠、4.3 制定个性化菜单对应数据的更新、打标、消费三个阶段账单处理里 5.2 设计产生顾客信息报表、5.3 设计产生食物信息报表则落在数据输出阶段。把同一份数据的不同生命周期阶段拆成独立用例后续做数据库表设计和定时任务时能直接对上。2.2 用例图里缺的 include 与 extend建模时要自己补文档里给出了 7 张用例图但都是参与者直接连用例的简单画法没有标 include 和 extend。这在早期文档里很常见实际按这份文档去做系统设计时我会在本体图上补两条关系把“订单信息写入账单信息数据库”抽成公共 include 用例让 1.1、2.1、3.1 都引用它把“查看顾客资料给予个性化服务”作为 1.1 的 extend因为只有结账场景才需要触发优惠判断。补上这两条关系后数据库写入逻辑变更时该改哪个用例、影响哪些链路一眼就能看出来。2.3 用例粒度自检从编号就能看出拆得是否均匀可以用一段简单脚本对转成 Markdown 的用例文档做编号提取快速核对粒度是否均匀import re text open(use_case.md, encodingutf-8).read() pattern re.compile(r^(?:ID\s*)?(\d\.\d)\s*名称\s*(.*)$, re.M) for case_id, name in pattern.findall(text): print(case_id, name)这段脚本按“ID x.x 名称 xxx”的格式把全部用例抽出来输出后你能立刻看出每个模块的用例密度。我一般会检查两类问题一是某个模块用例数异常少大概率是把多个业务动作揉进了同一份用例二是编号出现跳跃说明用例列表和用例描述对不上需要回头核对。文档中 1.x 有 5 个用例、2.x 有 3 个、3.x 有 3 个、4.x 有 3 个密度基本均匀粒度控制是合格的。下面这张表是我常用的粒度自检清单用例编号用例名称主参与者粒度判断理由1.1店内顾客订单录入营业员合适一次完整的录入交互含录入与存储1.2查看顾客资料给予个性化服务营业员合适依赖 1.1 的结果行为独立1.3顾客反馈信息收集服务员合适独立交互不依赖订单数据1.4顾客账单录入并验证营业员合适含核验流程值得单独建模3.3获取网上顾客的订单系统偏粗同时处理网银转账与订单入库事务边界要单独设计3. 用例描述字段拆解把正常流程和异常流程写成可执行规格用例描述是整份文档的正文主体。好食上这份文档里每个用例都保留了创建者、创建日期、参与者、目标、触发条件、前置条件、后置条件、正常流程、异常流程、相关用例、假设这一组字段。字段看着多其实每个都有明确用处下面挑最容易写歪的几个讲。3.1 触发条件、前置条件与后置条件三者的边界触发条件是引起用例开始的外部事件前置条件是用例开始前系统必须满足的状态后置条件是用例成功结束后系统保证成立的状态。以 2.3 获取最优外送路线为例触发条件是“订单积累到一定程度送货员得到送货任务”前置条件是“地图系统以及账单信息数据库运行正常”后置条件是“输出最佳外送路径”。三者互相独立触发条件说明什么时候调用前置条件说明调用前要巡检什么后置条件说明调用后怎么验证。很多团队写不清这一组字段常见错误是把“用户点击按钮”写在触发条件里、把“系统已登录”写在前置条件里后者其实是界面约束不是系统状态约束。3.2 正常流程编号与异常流程的扩展写法文档里店内顾客订单录入的正常流程是三步接收订单、录入订单信息、保存到数据库。异常流程写的是“2a 营业员发现订单信息不完备让服务员重新向顾客咨询完善订单信息。之后再重新从步骤 1 执行”。编号规则很实用异常分支用“步骤号 字母后缀”表示比如 2a 表示在第 2 步发生的分支如果异常发生后要回到某个步骤就直接写“重新从步骤 1 执行”。这套规则的优点是异常与步骤的对应关系一目了然测试设计时可以直接从编号反推分支覆盖率。有一点我要提醒单一异常分支对早期需求够用但落到开发阶段往往不够。以 1.4 顾客账单录入并验证为例原文只写了纸面账单与系统不符时重新获取实际运行时还会遇到“订单不存在”“餐费金额字段为空”“数据库写入冲突”三类情况。我的习惯是在文档评审阶段就把这些异常分支补齐每补一条测试用例就多一条可验收的场景。3.3 用固定模板规范用例描述脚本才能二次消费为了让用例描述能被后续工具二次消费我会把字段模板固化成这样的格式[ID] 1.1 [名称] 店内顾客订单录入 [主参与者] 营业员 [目标] 准确完整地将店内顾客的订单记录到账单信息数据库 [触发条件] 服务员向营业员提供顾客订单 [前置条件] 有空闲营业员账单信息数据库可用 [后置条件] 订单已保存到账单信息数据库 [正常流程] 1. 服务员提交订单营业员准备录入 2. 营业员将订单信息输入系统 3. 系统保存订单 [异常流程] 2a: 订单信息不完备 - 要求服务员补齐后重走步骤 1 [特殊需求] 无 [待确定问题] 无模板的好处是解析简单ID、前后置条件、异常分支都可以用正则或 split 直接提取喂给测试管理工具或生成接口用例都方便。像 2.2 电话订餐里的个性化菜单用例特殊需求那一行就会写成“从接线员输入订餐信息到反馈个性化菜单的时间控制在 1 秒内”。关键不是用什么格式而是全团队只保留一种格式否则脚本没法跨文档复用。3.4 用例描述质量自检清单字段常见问题自检要点触发条件和前置条件混淆是外部事件还是系统状态前置条件写成页面操作步骤换成“某某数据库/服务可用”这类状态描述正常流程只有操作没有系统反馈每步都要写“系统做了什么”异常流程只写错误提示不写恢复路径必须写明“回到第几步”特殊需求遗漏性能与安全约束补上时间上限、支付安全等级待确定问题隐藏不写写出来比假装确定要安全4. 店内、电话、网上三条订餐链路从用例推导业务规则这一章围绕三组订餐用例做对比包括主流程、参与者、异常分支和特殊需求。对比不是为了挑毛病而是为了提炼可复用的业务规则。4.1 三条链路的主流程与参与者差异对比项店内订餐1.x电话订餐2.x网上订餐3.x主参与者营业员接线员顾客自助信息采集方式纸面订单二次录入边通话边录入顾客直接录入数据校验时机录入时人工校核通话中即时确认提交时系统校验订单入库方式营业员保存到账单库接线员保存到账单库系统自动接收顾客网银预付附加服务查看顾客资料给优惠个性化菜单、最优外送路线个性化菜单、订单查询从这张表能读出一个关键差异店内和电话渠道先有服务人员做信息过滤网上渠道则把校验压力全部转移给了系统。网上订餐用例 3.1 的异常流程专门写了“顾客中途退出”和“网络异常中断”店内、电话渠道的用例则没有写这类中断分支这说明系统侧的容错重点是网络链路和支付环节。职责边界不同测试重点自然不同。4.2 特殊需求1 秒和 1.5 秒如何落地2.2 提供个性化菜单供参考的特殊需求是“从接线员输入订餐信息到反馈个性化菜单的时间必须控制在 1 秒内”3.2 的类似需求放宽到 1.5 秒。这两个数字不是拍脑袋而是渠道差异的体现电话场景下接线员在通话中等太久顾客体验断崖网上场景有页面加载缓冲容忍度略高。开发时这两个数字要落到两个地方一是接口的 P95 响应时间监控二是数据库查询的索引设计。常见的做法是把个性化菜单的匹配逻辑做成预计算结果定时批处理更新而不是每次请求实时跑全量规则。4.3 从用例反推数据模型以最优外送路线为例2.3 获取最优外送路线这个用例描述只有三行主流程落库时却需要不少数据订单的配送地址与时间窗口、送货员的当前位置与当日任务、地图系统的路径数据。仅凭用例文档不足以定表结构但至少能确定四个实体之间的关系-- 常见做法以外送任务为核心建表 CREATE TABLE delivery_task ( task_id BIGINT PRIMARY KEY, order_id BIGINT NOT NULL, courier_id BIGINT NOT NULL, address VARCHAR(255) NOT NULL, time_slot TIMESTAMP NOT NULL, route_snapshot JSONB, status VARCHAR(20) DEFAULT pending ); CREATE INDEX idx_task_courier_time ON delivery_task(courier_id, time_slot);这段建表语句把用例描述里的“订单积累到一定程度”落成 delivery_task 表里的多条 pending 记录“根据地图系统处理”落成 route_snapshot 字段存路径快照。索引选择 courier_id 与 time_slot 的联合索引是因为按送货员聚合当日任务是排序的常见入口。用例文档不会替你设计表但它能告诉你哪些字段必须存在。5. 待确定问题与假设用例文档里的风险清单怎么管理好食上这份文档在多个用例末尾保留了“待确定问题”字段如何从账单信息数据库提取顾客资料、如何对顾客分类并制定优惠策略、个性化菜单的具体内容如何定义。很多人觉得“待确定”是文档没写完其实这是需求获取阶段的诚实输出。真正有风险的是那些假装已经确定、实际没人说得清的地方。5.1 三个待确定问题分别卡在哪个环节第一个问题是 4.1 的“如何根据账单信息数据库提取出顾客资料”。它卡在数据口径账单表里可能只有顾客 ID、消费金额和菜品明细要不要统计消费频次、客单价、偏好的菜品类别没有业务方拍板数据库小组无法建字段。第二个问题是 4.2 的“顾客分类及优惠策略”卡在规则引擎是按累计消费金额分等级还是按最近消费时间标记活跃度这直接决定优惠计算模块的输入参数。第三个问题是 4.3 的个性化菜单内容卡在推荐范围是按顾客历史订单推荐同类菜品还是按季节和库存推荐新品。这三个问题不解决第 2、3 章的个性化菜单用例其实都无法真正落地。5.2 用脚本把“待确定问题”汇总成评审清单文档数量一多手工翻找“待确定问题”很容易漏。先把 docx 另存为纯文本或 Markdown然后用脚本批量抽取import re text open(use_case.md, encodingutf-8).read() blocks re.split(r\n(?ID\s*\d\.\d), text) for block in blocks: m re.search(rID\s*(\d\.\d), block) question re.search(r待确定问题\s*(.), block, re.M) if m and question: print(f{m.group(1)}\t{question.group(1).strip()})脚本按用例描述块切分只输出带“待确定问题”的条目及所属用例 ID生成的文件可以直接贴进评审会议记录。输出格式用制表符分隔是为了方便粘贴进表格或导入协作工具。每次需求评审前跑一遍比人工翻页可靠得多。提示正则里的.默认不匹配换行需要跨行匹配时把(.)换成([\s\S]?)否则只能抓到同一行内的短文本。5.3 风险登记表模板把这些条目汇总后我一般会按这样的结构跟进问题编号问题内容影响的用例当前状态处置时机TBD-01账单数据到顾客资料的提取口径4.1待业务方确认数据库设计前TBD-02顾客分类与优惠策略4.2待产品方案优惠模块开发前TBD-03个性化菜单推荐规则2.2、3.2、4.3待数据验证推荐服务排期前处置时机写的是“某个环节前”而不是某个日期因为需求澄清天然是阻塞式的问题不解决下游设计无法开展。把处置时机和研发阶段绑定评审时能直接判断哪些问题不解决会挡住当轮迭代。6. 把用例描述翻成测试场景与验收清单用例文档不是写完就归档的。我最常用的一招是把“正常流程 异常流程”直接改写成 Given-When-Then 场景每个场景就是一条测试用例。以 1.4 顾客账单录入并验证为例场景账单金额与系统订单一致 Given 服务员提供纸面账单金额 128 元 And 系统中存在对应订单 1024金额 128 元 When 营业员输入账单信息并请求验证 Then 系统返回完整订单信息 And 营业员确认后账单保存成功异常流程 3a餐费与系统账单不符也同理场景纸面账单与系统订单金额不符 Given 服务员提供纸面账单金额 120 元 And 系统中存在对应订单 1024金额 128 元 When 营业员输入账单信息并请求验证 Then 系统提示金额不一致 And 流程回到重新获取账单状态每条场景对应的通过标准就是用例文档里的后置条件。把后置条件写进自动化测试的断言层比手工验收表更可靠。我的做法是用例文档评审通过后直接把场景清单贴在迭代看板的“验收标准”列里开发提测时逐条勾选而不是等测试人员再写一遍用例。本文还有配套的精品资源点击获取