UML用例图实战指南：从边界谈判到评审避坑

做需求评审的时候最怕遇到那种一上来就画一堆框框线线、结果谁也看不懂的用例图。我见过不少团队需求文档里塞了一张密密麻麻的图椭圆、小人、箭头挤成一团开发看完一头雾水测试拿着图也写不出用例最后这张图就成了摆设。问题往往不在于工具用得熟不熟而在于画之前没想清楚这张图到底要表达什么。UML用例图看着简单几个元素而已但它是软件工程里少数几个画错比不画还糟的图种——因为它直接决定了需求边界和系统职责的划分。这篇内容我想把用例图这件事从头到尾讲透。从它到底解决什么问题、几个核心元素各自的准确含义到实际动手画的完整流程、参数级的取舍判断再到评审时最常被挑出来的毛病和排查方法。适合刚接触软件工程的学生对照着做课程设计也适合工作几年但一直没把用例图画明白的开发者重新梳理一遍。我不会只告诉你椭圆代表用例、小人代表参与者这种谁都能查到的定义而是把每个元素背后为什么这么设计什么时候该拆什么时候该合的判断逻辑讲清楚让你画出来的图能真正拿去跟产品、测试、开发对齐而不是交作业式的应付。1. 先搞清楚用例图到底在解决什么问题1.1 用例图的本质是系统边界谈判工具很多人把用例图当成需求列表的图形化版本觉得把功能一个个列成椭圆就完事了。这个理解偏差是后面所有问题的根源。用例图真正的作用是在项目早期把系统做什么和系统不做什么这条边界线画出来并且明确谁从系统这里拿走价值。它是一张谈判桌参与者是坐在桌子两边的人用例是双方达成的交易内容。我习惯在动手画之前先问三个问题这个系统对外提供的价值是什么谁在消费这些价值哪些事情是系统内部处理、外部根本不需要知道的这三个问题的答案基本就决定了图的骨架。举个常见的场景一个图书借阅系统读者要借书、还书、查书管理员要维护书目、处理逾期这些是系统边界内的用例而读者决定借哪本书这种纯人类决策行为就不该出现在图里因为它不是系统提供的价值。理解这一点之后你会发现用例图其实不需要画得很细。它回答的是有哪些价值交换而不是这些价值怎么实现。实现细节是后面类图、时序图、活动图要干的事。把用例图画得过细反而模糊了边界让读者抓不住重点。这也是为什么很多资深工程师画用例图时反而画得很粗——粗到刚好能说清楚边界多一笔都是浪费。1.2 用例图和功能列表的根本区别有人会问既然都是列功能我写个需求清单不就行了何必画图区别在于功能列表是线性的、平铺的它不表达谁和什么关系用例图是结构化的它强制你把参与者、用例、它们之间的关联、包含与扩展关系都摆到台面上。一张合格的用例图能让人一眼看出系统的服务对象有哪几类、每类对象能触发哪些行为、哪些行为是多个用例共用的。更关键的是用例图逼着你在早期就做角色划分这件事。功能列表里你可以写支持借书、还书、续借但用例图会追问借书和还书是同一类人做的吗续借是不是借书的一个变体这些追问在功能列表里是隐形的在用例图里是显性的。我做过一个内部工具的项目最初功能列表列了三十多条画成用例图之后发现参与者其实只有两类用例合并同类项之后只剩十一个一下子就把范围收敛了。这种收敛价值是纯文字列表给不了的。1.3 什么阶段该画、什么阶段不该画用例图不是万能的它有明确的最佳使用窗口。我的经验是它最适合用在需求分析的中前期——业务方刚把想法抛出来、还没形成正式需求文档的时候。这个阶段画用例图成本低、调整快能快速跟业务方对齐我们理解的是不是同一件事。到了详细设计阶段用例图的价值就下降了。这时候你更需要的是时序图来表达交互顺序、类图来表达静态结构。我见过有团队在编码阶段还在反复改用例图这其实是把用例图当成了需求变更的载体方向就偏了。用例图应该相对稳定如果它频繁变动说明前期的边界谈判没谈透或者项目范围本身就在剧烈摇摆这时候该做的是回到需求源头而不是在图上来回改。还有一种情况也不适合画用例图纯技术性的内部重构、性能优化这类没有明确外部参与者的工作。这类工作的价值不体现在对外服务上硬画用例图只会画出一堆没有参与者的孤立椭圆毫无意义。2. 四个核心元素每个都有讲究2.1 参与者不是人是角色参与者Actor最容易被误解成具体的人。实际上它代表的是一个角色是一组使用系统时具有相同目标的行为集合。同一个真人可以扮演多个参与者比如一个员工既可以是普通用户也可以是审批人同一个参与者也可以对应多个真人比如读者这个角色对应成千上万个具体读者。画参与者时我踩过最多的坑是把组织架构直接搬进来。曾经有个项目业务方要求把部门、岗位全画成参与者结果图上出现了十几个小人每个小人连出去的线乱成一团。后来我们做了归并凡是使用系统时目标一致的就合并成一个参与者。部门经理和总监在系统里都是审批人那就只画一个。参与者画的是系统眼里的角色不是公司眼里的职位。还有一个判断技巧参与者一定是系统外部的东西。如果某个角色其实是系统内部的一个模块那它不该是参与者而应该是系统内部的处理逻辑。比如订单系统调用库存系统如果这两个系统都在你的边界内那它们之间的交互是内部协作不该画成参与者只有当库存系统是外部依赖时它才作为参与者出现。这条边界判断直接决定了图的正确性。2.2 用例动词开头代表完整价值用例Use Case的命名规范是从参与者视角出发的动宾短语比如借阅图书提交订单查询余额。它代表的是一次完整的、对参与者产生可观察价值的交互而不是一个步骤或一个函数。这是区分用例和功能点的关键一个用例内部可能包含很多步骤但只要它对外交付的价值是完整的它就是一个用例。我见过太多把用例画成点击保存按钮填写表单这种操作级粒度的图这是典型的粒度失控。判断粒度是否合适有个简单的方法问自己参与者做完这件事是不是得到了一个完整的结果如果答案是是那它就是一个用例如果只是中间过程那就该收进用例的内部描述里而不是单独画一个椭圆。用例的数量也要控制。一个中等规模的系统用例图上的椭圆通常在十个到二十几个之间。如果超过三十个要么是系统真的很大那就该拆成多张图按子系统或按参与者分组要么是粒度太细需要合并。我个人的习惯是一张图上的用例尽量控制在十五个以内超过就分图保证每张图都能在一屏内看清楚。2.3 关联关系实线连接别乱加箭头参与者和用例之间的关联Association用实线表示表示这个参与者能触发这个用例。这里有个细节很多人搞错关联线到底要不要箭头在UML规范里参与者与用例之间的关联箭头方向表示谁发起但实践中大量团队直接用无箭头实线因为发起方向在大多数场景下是显而易见的。我的建议是如果发起方向明确且单一用无箭头实线即可图更干净如果存在双向触发或者方向容易混淆的情况才加箭头。不要为了规范而给每条线都加箭头那会让图变得很吵。另外一条关联线只能连接一个参与者和一个用例不要试图用一条线连多个那在语义上是错误的。2.4 包含与扩展两个最容易用反的关系包含Include和扩展Extend是用例图里最容易被滥用、也最容易被用反的两个关系。我用一句话概括它们的区别包含是必须做的公共部分扩展是可选发生的分支。包含关系表示基础用例在执行过程中一定会用到被包含的用例。典型场景是多个用例共有一段逻辑比如借书还书续借都需要验证读者身份那验证读者身份就作为被包含用例用带箭头的虚线箭头指向被包含用例连过去标注include。注意箭头方向从基础用例指向被包含用例因为基础用例依赖被包含用例。扩展关系表示在特定条件下基础用例会额外触发扩展用例。典型场景是借书过程中如果读者有逾期未还会触发处理逾期这个扩展行为。扩展用带箭头的虚线表示箭头从扩展用例指向基础用例标注extend方向跟包含正好相反。这个方向搞反是新手最常见的错误记住一句话包含是我要用你箭头指向被用者扩展是我补充你箭头指向被补充者。还有一个判断技巧包含关系里被包含的用例不能单独存在它没有独立的价值扩展关系里扩展用例在特定场景下可以独立理解它只是选择性地附加到基础用例上。用这个标准去检验基本不会用反。3. 从零画一张用例图的完整流程3.1 第一步圈定系统边界和参与者清单动手画之前先在一张白纸或白板上做两件事画一个大方框代表系统边界然后在方框外面列出所有可能的参与者。这一步不要急着画用例先把谁搞清楚。列参与者的方法是找外部交互方谁会主动使用系统谁会接收系统的输出有没有外部系统需要对接列完之后做归并把目标一致的合并。我通常会用一个小表格来管理这个过程左边列候选参与者右边写它在系统里的目标是什么目标相同的合并成一行。这个表格虽然最后不会出现在图里但它是保证参与者不重不漏的关键。候选参与者在系统中的目标归并结果普通读者借书、还书、查书读者学生读者借书、还书、查书读者教师读者借书、还书、查书、预约读者预约单独处理前台管理员办理借还、维护读者信息管理员后台管理员维护书目、处理逾期管理员这张表做完参与者基本就定了。注意教师读者的预约目标跟普通读者不同这时候有两种处理要么把预约作为读者的一个用例要么单独拆一个预约者参与者。我的判断标准是看这个差异是否足够大——如果预约涉及完全不同的流程和权限拆参与者更清晰如果只是多一个功能就放在读者下面。3.2 第二步按参与者逐个梳理用例参与者定好之后逐个参与者去问这个角色用系统做哪些事把每件事写成一个动宾短语。这一步先求全不求精把所有能想到的都列出来不要急着判断粒度。列完之后再做两件事合并同义用例、剔除不属于系统边界内的用例。合并同义用例时注意区分同义和相似。比如查询图书和检索图书是同义合并借书和续借是相似但不同续借是借书的一种特殊形式可以考虑用扩展关系表达也可以独立成用例取决于业务复杂度。我倾向于业务规则简单时独立成用例规则复杂比如续借有次数限制、有罚金计算时用扩展把复杂逻辑收进扩展用例里。剔除边界外用例的标准前面提过纯人类决策、纯外部行为不进图。还有一个容易忽略的点系统自动执行的定时任务比如每天凌晨清理过期预约它没有外部参与者触发严格来说不该作为用例出现在用例图里而应该在需求文档里单独说明。如果非要表达可以画一个时间作为参与者但这属于比较边缘的用法我一般不建议容易让图变复杂。3.3 第三步确定用例之间的关系用例列全之后开始找关系。先找包含关系哪些用例有共同的、必须执行的子流程把这些公共部分抽出来做成被包含用例。再找扩展关系哪些用例在特定条件下会有额外分支把这些分支做成扩展用例。这里有个实操心得包含关系不要抽得太碎。我见过有人把验证身份检查权限记录日志全抽成被包含用例结果图上多出一堆小椭圆主线反而看不清了。包含关系应该只抽那些多个用例真正共用、且逻辑足够复杂值得单独说明的部分。像记录日志这种每个用例都做、但逻辑极简的抽出来纯属添乱写在用例描述里一句话就够了。扩展关系则要注意条件明确。每个扩展用例都应该能回答在什么条件下触发。如果说不清触发条件那这个扩展关系很可能是硬凑的应该考虑合并回基础用例。比如借书扩展出处理逾期触发条件很明确——读者有逾期未还。这种扩展就是有价值的它把异常分支从主流程里分离出来让主流程保持清爽。3.4 第四步布局与绘制让图能一屏看懂布局这件事工具帮不了你得靠人。我的布局原则是参与者放在系统边界框的外面主动发起方放左边被动接收方放右边用例放在框内按参与者分组同一参与者触发的用例纵向排列关系线尽量少交叉交叉不可避免时用弧线绕开。工具选择上其实没有标准答案。轻量场景我用在线绘图工具拖拽方便、协作快需要版本管理、要跟代码一起提交的我用文本化的绘图方式比如用纯文本描述生成图好处是能进 Git、能 diff。不管用什么工具有一条铁律图上的文字必须清晰可读字号不能为了塞下更多内容而缩到看不清。一张需要放大才能读的用例图等于没画。绘制顺序上我习惯先放参与者和系统边界框再放用例最后连线。连线时先连关联再连包含扩展。每连完一类关系就检查一遍方向尤其是包含和扩展的箭头方向画完立刻核对别等全画完再回头查那时候眼睛已经花了。4. 评审现场最常被挑出的毛病与排查方法4.1 粒度失控一张图塞了四十个椭圆这是评审时最高频的问题。症状是图上椭圆密密麻麻参与者连线像蜘蛛网。根因通常是画图的人把功能点当成了用例。排查方法是逐个椭圆问这是一个完整价值交付吗不是的就往下沉到用例描述里。处理这类问题的标准动作是分层先按参与者分组每组一张子图组内再按业务模块细分。分图之后每张图只保留一个参与者或一组紧密相关的参与者图立刻清爽。我一般会在总图上只放参与者和最顶层的用例分组用包或子系统表示细节放到子图里形成总—分结构。4.2 关系用反包含和扩展傻傻分不清前面讲过方向问题这里补充排查方法。评审时拿到一张图先看所有include的箭头是不是都指向被包含用例再看所有extend的箭头是不是都指向基础用例。方向对了再检查语义包含的被包含用例是不是真的必须执行扩展的扩展用例是不是真的条件触发。有个快速自检法把包含关系读成基础用例执行时一定会做被包含用例把扩展关系读成基础用例在特定条件下会做扩展用例。两句话读下来通顺关系就用对了读着别扭多半是反了或者用错了类型。4.3 参与者冗余把组织架构搬进了图里症状是参与者数量远超实际角色数且很多参与者连出的线高度重复。排查方法是做目标归并把目标相同的参与者合并。归并时注意保留那些目标确实不同的角色不要为了图好看而强行合并导致语义丢失。还有一种隐蔽的冗余把外部系统和人类角色混在一起画但没做区分。规范做法是用不同的图形区分人类参与者和系统参与者比如系统参与者用矩形加system标注这样读者一眼能分清哪些是人触发的、哪些是系统间对接。4.4 常见问题速查表问题现象可能原因排查动作处理方式椭圆过多、连线混乱粒度太细功能点当用例逐个问是否完整价值交付下沉细节按参与者分图包含箭头方向反了混淆依赖与被依赖检查箭头是否指向被包含用例调整为指向被包含用例扩展箭头方向反了混淆扩展与包含方向检查箭头是否指向基础用例调整为指向基础用例参与者过多且重复直接搬组织架构按系统内目标归并合并同目标角色图上有孤立用例用例无参与者触发检查是否有外部触发方补参与者或删除该用例定时任务画成用例误把内部行为当外部价值确认是否有外部参与者移出用例图写入需求文档4.5 几个只有踩过才知道的细节第一个细节用例名称不要带技术词汇。查询数据库调用接口这种命名暴露的是实现而不是价值评审时一定会被挑。改成查询图书信息获取订单状态从参与者视角描述才是用例该有的样子。第二个细节系统边界框不是必须画但画了就要画准。边界框代表系统职责范围框内的用例是系统要实现的框外的参与者是系统要交互的。如果边界框画得含糊读者会搞不清某个用例到底是不是本系统负责。我建议只要图上有外部系统参与者就一定画边界框把内外分清楚。第三个细节别在用例图上标注流程。有人喜欢在用例之间画箭头表示先做A再做B这是把用例图当时序图用了。用例图表达的是静态的谁能做什么流程顺序是时序图和活动图的职责。混在一起画图会变得既不像用例图也不像流程图两头不讨好。5. 工具选型与团队协作中的实际取舍5.1 图形工具和文本工具怎么选图形化工具上手快拖拽即所得适合需求评审现场快速出图、跟业务方即时对齐。缺点是版本管理弱多人同时改容易冲突图跟代码分离时间一长容易过期。文本化工具用纯文本描述图形结构再渲染学习曲线陡一点但胜在能进版本库、能 diff、能跟代码一起演进适合长期维护的项目。我的实际做法是两者结合需求探索阶段用图形工具快速迭代定稿之后转成文本化描述纳入版本管理。转换过程本身也是一次复查经常能在转换时发现之前没注意到的关系错误。团队协作时我会把用例图的源文件跟需求文档放在一起约定图改了必须同步改文档避免图和文档两张皮。5.2 一张图还是多张图拆分策略系统一大单张用例图必然失控。拆分策略有三种按参与者拆、按子系统拆、按业务场景拆。按参与者拆最直观每个参与者一张图适合参与者类型清晰的系统按子系统拆适合大型系统每个子系统一张图图之间用子系统间的依赖关系连接按业务场景拆适合流程性强的系统一个端到端场景一张图。我通常优先按参与者拆因为用例图的核心就是谁做什么按参与者拆最贴合这个语义。拆完之后如果某张图还是太大再在参与者内部按业务模块二次拆分。拆分的底线是每张图都能独立说清楚一件事读者不需要来回翻图才能理解。5.3 评审时的沟通技巧用例图评审最容易变成挑刺大会因为每个人对边界的理解不同。我的经验是评审时先讲清楚这张图要回答的问题比如这次评审只确认参与者划分和用例范围不讨论实现把讨论框定在范围内。遇到争议不要在图上来回改先记下来会后单独对齐避免评审现场陷入细节泥潭。还有一个技巧评审时让测试同学先发言。测试是用例图最直接的消费者他们能不能从图上直接推导出测试场景是检验图质量的硬标准。如果测试看完图说我不知道该怎么测那这张图大概率有问题要么粒度不对要么关系没表达清楚。6. 一个完整小案例的拆解复盘6.1 案例背景与初始草图假设要做一个会议室预约系统初始需求是员工能预约会议室、取消预约、查看预约情况管理员能管理会议室信息、处理冲突。第一版草图很粗糙画了员工和管理员两个参与者连了五六个用例包含扩展一个没画。这版图的问题很明显用例粒度不齐查看预约情况太笼统处理冲突又太具体没有表达预约和取消之间的共性管理员和员工对会议室信息的操作权限没区分。评审时被挑了一堆但方向是对的参与者划分没问题。6.2 迭代后的定稿结构第二版做了几件事把查看预约情况拆成查看我的预约和查看会议室占用因为这两个目标不同把预约和取消的公共部分校验时间段可用性抽成被包含用例把处理冲突改成预约的扩展用例触发条件是时间段冲突管理员增加维护会议室信息用例与员工的用例用参与者区分开。定稿之后图上参与者两个、用例七个、包含关系一条、扩展关系一条一屏能看清测试同学看完直接列出了对应的测试场景。这个案例说明用例图的价值不在于画得多全而在于每个元素都经得起为什么在这的追问。6.3 从这个案例里提炼的三条经验第一条先粗后细别一上来就追求完美。第一版草图的价值是暴露问题不是交付成果。快速画、快速评审、快速改比憋一张完美的图效率高得多。第二条包含和扩展是事后提炼出来的不是一开始就能想全的。先把用例列全再回头找共性抽包含、找分支抽扩展顺序反了容易为了用关系而用关系。第三条用例图定稿的标志不是画完了而是测试能据此写用例、开发能据此估工作量。达不到这个标准图就还没画到位。7. 我个人在实际操作中的几点体会画了这么多年用例图最大的体会是这张图的价值八成在画之前的思考两成在画出来的结果。真正花时间的应该是跟业务方对齐边界、跟团队确认角色划分而不是在工具里调线条位置。我见过有人为了图的美观反复调整布局花掉半天但参与者划分错了图再好看也是废的。另一个体会是用例图要敢于留白。不是所有系统行为都值得画进图里那些显而易见的、没有争议的功能写进需求文档就够了。用例图应该聚焦在有争议、需要对齐的地方把有限的图面留给真正需要讨论的内容。一张什么都想表达的用例图最后往往什么都表达不清。最后一个实用建议每次画完用例图隔一天再回来看一遍。隔夜之后你对细节的记忆会淡化这时候看图如果还能一眼看懂说明图是清楚的如果自己都要琢磨半天那读者只会更懵。这个简单的自检动作帮我避开了很多次评审翻车。