简介这是一份面向软件工程需求分析场景的用例文档资源以好食上餐厅管理系统为案例适合学习UML建模、撰写需求文档的学生或初入职场的软件工程师参考。文档完整覆盖前言、背景与内容概述、用例列表、用例图和用例描述等核心模块并对顾客资料管理、店内顾客订餐、电话订餐、网上订餐、账单结算、顾客反馈信息管理、连锁店管理等多个业务用例进行说明尤其给出店内顾客订餐用例的名称、前置条件、触发条件、基本流程与扩展流程等细节便于理解用例文档的规范写法。资源包仅含1个docx文件压缩包大小2.9MB打开即可直接阅读或修改复用。目前已有615人学习下载。对于正在开展课程设计或项目实习的同学可用它作为编写需求文档的模板快速掌握从系统背景到用例描述的完整结构提升文档编写效率。1. 用例文档.docx 到底卡在哪一步需求评审会上大家都能把功能讲得头头是道真到写测试用例的时候却发现每个人对“登录成功”的理解都不一样。做测试的等需求文档补充细节做研发的嫌用例写得像操作说明书做产品的觉得文档写完就过了保质期。这个场景走到最后所有人的目光都会落在同一个文件上用例文档.docx。用例文档不是需求文档的复述也不是测试用例的堆砌它以用例为单位描述“用户用系统完成一件事”的完整路径包括前置条件、正常流程、异常分支和验收结果。选择 docx 作为载体是因为它是团队协作和评审流程里兼容性最高的格式能批注、能留痕、能直接贴在缺陷单里。“用例文档.docx”这个标题本身就点出了两层意思内容上是用例组织方式形态上是 docx 的文档工程两件事都得处理这篇文章就围绕这两条线展开。2. 用例文档的内容骨架从用例编号到验收点2.1 用例文档里必须有的 6 个块一份能进入评审的用例文档至少要覆盖六个信息块。很多团队写不清楚不是因为不会写而是不知道每个字段到底承担什么职责最后把用例写成了需求条款。字段作用常见错误用例编号全局唯一标识关联需求和缺陷用 1、2、3 编号需求变更后全乱前置条件用例执行前的系统状态和数据准备写成“用户已登录”没写具体账号权限操作步骤可执行的动作序列一步一个动作把多个操作挤成一句话“点击提交并确认弹窗”输入数据各步骤的实际值或数据范围只写“合法数据”不写边界值预期结果每个步骤后系统可观测的响应写“页面正常”正常是什么样没人知道验收标准用例通过/失败的判定依据和预期结果混在一起写实际操作里我会在“操作步骤”和“预期结果”之间建立一一对应的编号关系步骤 3.1 对应结果 3.1。这样执行到第几步挂了直接定位到具体结果缺陷单里也能精确引用。文档结构上用例编号建议按“模块-场景-序号”组织比如US-LOGIN-001比纯数字可读性强而且在 docx 里用样式表管理也方便。2.2 用例粒度怎么定一条用例写多细用例粒度是整个文档最容易被挑战的点。写粗了执行的人还要猜写细了文档膨胀到没人维护。我一般用三个判断标准来控制粒度独立可执行、结果可验证、不跨角色和系统。独立可执行是指用例能从一个明确入口开始不需要依赖另一条用例的状态才能跑通比如“修改密码后重新登录”和“登录”就不应该合并成一条用例。结果可验证是指预期结果必须是可观察的明确状态不能是“系统处理完成”这种模糊描述。不跨角色和系统要求一条用例只描述一个角色在一个系统里的操作涉及管理员审批又涉及用户接收通知就得拆成两条。粒度还直接影响 docx 的表格结构。个人经验是一页放 3 到 5 条用例比较合适如果一条用例的操作步骤超过 15 步说明它已经接近流程测试而非用例测试应该拆成多条并补充关联关系。在文档模板里我会给“步骤区域”设置固定的行高和合并单元格规则避免每条用例长短不一带来的排版混乱。2.3 用模板约束“写得下去”的文档结构空白的 docx 是写不出好用例的团队需要的是带结构的模板。模板制作时我会重点锁住三类内容页面设置、样式表、表格结构。页面设置包括 A4 纸型、页边距、页眉页脚的文档编号和保密级别样式表定义“用例标题”“步骤描述”“预期结果”三种段落样式表格结构预置用例字段的行列比例步骤列占 40%预期结果列占 30%减少写完后的调整成本。w:style w:typeparagraph w:styleIdUseCaseTitle w:name w:valUseCaseTitle/ w:pPr w:keepNext/ w:keepLines/ /w:pPr w:rPr w:b/ w:sz w:val24/ /w:rPr /w:style上面这段是 Word 样式定义文件里一个自定义段落样式的核心片段keepNext让用例标题和下面的正文保持在同一页避免标题孤悬在页面底部。团队统一使用这样的模板文件每个成员新建文档的时候从模板进入所有用例的格式就保持一致评审时只需要关注内容本身不用在排版上花费精力。3. 用 python-docx 把用例文档生成成可追踪的 docx3.1 为什么选择 python-docx 而不是手写当用例数量超过 50 条的时候手工维护 docx 的表格和编号一定出错这里漏一条那里多一条是常态。我一般的做法是用 python-docx 写生成脚本把用例数据从源文件里读出来再按模板结构写入 docx 文档。这样做的收益有三个编号和标题自动生成不会有重复表格行数由数据决定不会出现空行或溢出文档内容和展示格式分离修改用例只改数据源不用碰 Word 文件本身。另一个很重要的原因是 docx 可以进版本管理。虽然 docx 是二进制压缩包但在 Git 里存一份配合脚本生成至少能追踪“哪次提交改动了哪条用例”。这比直接在 Word 里改然后到处传文件要可靠得多尤其是团队里面有人用 WPS 有人用 Office 的时候格式差异会掩盖真实的内容变更。3.2 最小生成脚本标题、段落、表格from docx import Document from docx.shared import Pt doc Document() # 写入文档主标题 doc.add_heading(用户登录模块用例文档, level0) # 写入需求概述段落 p doc.add_paragraph() run p.add_run(本文档覆盖用户登录模块的正常登录、密码错误、账号锁定三个场景。) run.font.size Pt(12) # 建立用例表格 table doc.add_table(rows1, cols5) table.style Table Grid hdr table.rows[0].cells hdr[0].text 用例编号 hdr[1].text 操作步骤 hdr[2].text 输入数据 hdr[3].text 预期结果 hdr[4].text 优先级 doc.save(用例文档.docx)这段代码完成了三个动作创建空白文档并加标题、写入一段需求概述、建立一张五列表格。这里的add_heading的level0生成的是文档标题样式level1才是章标题优先级的调整直接在生成脚本里修改数据即可。表头写完后后续往里添加数据行的操作全部由循环完成不会像手工操作那样破坏表格结构。3.3 让表格里的用例字段自动填充在实际项目里用例数据通常是多条记录我会把每条用例的数据组织成字典列表循环写入表格。cases [ {pid: US-LOGIN-001, steps: 输入正确账号密码点击登录, data: user001 / pass123, expect: 登录成功跳转首页, pri: 高}, {pid: US-LOGIN-002, steps: 输入错误密码点击登录, data: user001 / wrong, expect: 提示密码错误停留在登录页, pri: 高}, ] for case in cases: row table.add_row().cells row[0].text case[pid] row[1].text case[steps] row[2].text case[data] row[3].text case[expect] row[4].text case[pri] # 设置表格列宽避免自动换行导致排版错乱 for row in table.rows: row.cells[1].width cm(6) row.cells[3].width cm(6)table.add_row()返回新行cells是按列索引访问单元格的入口顺序必须和表头一致。列宽设置这里用cm(6)限定步骤列和结果列的宽度这是从实际使用里踩出来的坑不设列宽的话Word 会根据内容自动分配长文本列会挤占其他列的宽度打印出来完全没法看。生成之后的 docx 和手工写出来的文件从打开方式到打印效果都完全一致唯一的区别是就算一口气写入 200 条用例脚本运行时间也只在秒级而且不会出现第 137 条忘记写预期结果这种低级问题。4. docx 的真实痛点WPS 默认新建、预览失败与样式漂移4.1 wps 不能默认新建 docx 的来龙去脉用 WPS 的同事常常遇到一个问题新建文档默认出来的扩展名是.wps发给别人之后对方怎么都打不开。这个问题的根源不在 WPS 本身而在安装时的文件关联设置WPS 默认使用自家格式作为新建文档的默认格式docx 是兼容选项而不是默认选项。处理方式是到 WPS 的“设置中心-文件关联”里把 docx、xlsx、pptx 这三个格式的关联全部勾选到 WPS再把“默认打开方式”切换为 “Microsoft Office 兼容模式”。如果公司有统一的终端管理可以直接下发注册表配置来统一修改避免每个员工手动设置。检查是否生效的办法很简单右键新建菜单如果“新建 DOCX 文档”出现就说明关联正常。这里还有个容易忽略的细节wps 自动备份文件的后缀也是.wps这会让用户在文件管理器里看到两种相似后缀误以为备份文件就是正式文档。团队协作时应明确约定交付物只能是 docx并在文档首页的版本记录表里登记最近一次修改人的 Office 版本减少格式混乱带来的不必要沟通成本。4.2 无法预览 doc 或 docx 的排错顺序企业网盘、邮件附件和飞书文档这类场景里docx 无法预览是很常见的问题表现为缩略图空白、提示文件损坏或直接显示“不支持预览”。按下面的顺序排查大多数情况十分钟内能定位。# 检查文件头是否为 PK 开头docx 本质是 zip 压缩包 xxd -l 4 用例文档.docx # 正确输出: 504b0304 (PK\x03\x04) # 如果是旧版 .doc 格式, 文件头是 D0 CF 11 E0不能直接当 zip 解压 xxd -l 4 旧版用例.docxxd -l 4读出文件前四个字节504b0304是标准 zip 文件头docx 一定能看到这个值。看到d0cf11e0则说明这是旧版二进制格式的 doc 文件预览服务和在线编辑器对它的支持都不如 docx需要另存为 docx 再传上去。文件头正常但预览仍然失败时再查文件大小和权限0 字节文件直接重建有加密标记的文档预览服务默认拒绝渲染需要在 Word 里清除文档保护后再上传。4.3 版本漂移同一个文档在不同客户端里表现不一样docx 在 Office、WPS 和在线预览里的渲染结果并不完全一致最典型的表现是三处字体回退、分页变化、表格列宽微移。同一份用例文档在公司电脑上是 12 页客户电脑上打开变成了 13 页评审时页码都对不上。这个问题来自字体渲染引擎和默认字体集合的差异Word 用微软雅黑WPS 是思源黑体预览服务可能直接回退到系统默认宋体。规避的方法是在生成脚本里做两件事指定常用字体并设置嵌入字体或者把关键字体转成图片。第一种方法会让 docx 体积变大但能保证换电脑后字体不丢第二种方法只适用于最终交付版因为转成图片之后用例文本就不能复制了不太适合需要继续编辑的文档。我的折中做法是在模板里统一使用“等线”或者“宋体”避免使用特殊字体每次正式发出版本前用脚本生成一份 PDF 作为评审基准用例文档.docx 给需要编辑的人PDF 给需要看的人。5. 让用例文档从“写完就废”变成可持续更新的资产用例文档最容易翻车的地方不是第一次写不出来而是没人更新。产品改了一个按钮文案用例文档还是旧版本几个月之后文档就变成了一堆不可信的历史文件。要解决这个问题得把文档当成代码来管而 docx 恰好支持文档属性里的自定义字段。在 Word 的“文件-信息-属性-高级属性”里可以维护一组自定义字段我用这组字段做版本状态机并在文档开头加一个版本记录表版本号日期修改人状态变更内容摘要v1.02024-03-10张三已评审初始版本v1.12024-03-18李四待评审增加异常登录分支v1.22024-03-25王五已归档合并评审意见状态机只有三态编写中、待评审、已归档。只要文档状态不是“已归档”任何变更都在文档上直接改并递增版本号一旦归档必须另起新版本不在旧版上覆盖。和研发团队约定这条规则之后文档才谈得上可信。更进一步docx 里的用例表格是可以被程序当作数据源读取的。用 python-docx 遍历表格把每行数据抽取成结构化字典再导出成 Excel 或者 JSON就能接到测试管理工具里做自动化用例导入文档和测试执行之间有了数据通路用例文档的维护成本才能真正降下来。这也是我在文档模板里坚持给每个单元格加固定列宽和统一格式的原因机器解析表格时依赖的是稳定的结构和准确的文本值。任何时候拿到一份用例文档.docx 都记得先打开文档属性看一眼版本状态这比看第一页的标题靠谱得多。本文还有配套的精品资源点击获取