文本分析辅助UML建模：从需求文档到类图候选的工程实践

1. 先把预期摆正文本分析到底在解决什么问题如果你做过一段时间的 UML 建模一定有过这样的体验手上拿着一份三四十页的需求文档逐句读、逐句划把名词圈出来当类把动词圈出来当操作读到第八页的时候已经忘了第三页圈过什么最后画出来的类图里“用户”这个类出现了三次名字分别是“用户”“客户”“使用者”。文本分析Textual Analysis这个功能就是冲着这个痛点来的——它把需求文档这种自然语言材料丢进一个词性分析和候选元素提取的流水线里机器先把可疑的名词、动词、短语挑出来列成一张候选清单你再从这张清单里挑、改、合并最后生成 UML 类图或用例图的草稿。我用这个功能的时间不算短从最开始抱着“能不能一键出图”的幻想到后来把它当成一个“高级一点的荧光笔”中间踩的坑基本都集中在预期管理上。所以这篇东西不想写成操作手册的复述而是想把这套流程里真正决定成败的几个环节拆开讲它的原理边界在哪、参数怎么调、中文文本为什么容易翻车、生成之后必须做哪些重构。看完你应该能判断什么材料值得丢进去跑一遍什么材料丢进去纯属浪费时间。先说清楚它适合谁。第一类是需求分析岗或者系统分析岗的同学手上有一堆用户故事、需求规格说明、会议纪要需要快速把里面的业务实体捞出来形成领域词汇表。第二类是学生或者刚转建模的同学做课程设计时对着一段需求描述发愁“这到底该画几个类”用它起个草稿比自己空想快得多。第三类是已经在维护一套模型的老手文档改版了想快速定位哪些新出现的名词还没进模型。这三类人的共同点都是需要的是候选不是结论。反过来说如果你期待的是“导入 PDF点一下按钮一张可以直接交付的类图就出来了”那我劝你别在这上面花时间。自然语言里的歧义、省略、隐性关系是目前任何词性分析流水线都处理不了的部分。文本分析给你的是原材料成品的味道还得靠人调。这个认知必须先立住后面所有操作才不至于跑偏。1.1 从“人读文档画图”到“机器先给候选”传统路径是串行的读文档 → 理解 → 提取概念 → 建模 → 回头核对。这条路径最脆弱的环节是“提取概念”因为它完全依赖人的记忆和注意力文档一长一致性就崩。文本分析把这条路径改成了并行加交叉验证机器用一套机械规则把所有名词动词扫一遍得到一张全量候选表人用理解力去判断哪些该留、哪些该合并、哪些该拆。两边的结果叠在一起看漏掉的东西会明显变少。这个变化的价值不在于“快”而在于“全”。人读文档是带着先验假设读的你脑子里已经有一个“订单、商品、用户”的框架读到不符合框架的描述会自动忽略。机器没有这个偏见它会把“对账日”“滞纳金”“结算周期”这些你压根没打算建模的词也一起捞出来——这些词里往往藏着真正被遗漏的业务概念。我做过一个对账相关的模块第一版模型完全漏掉了“账期”这个概念就是靠文本分析把“每月五日为对账基准日”这句话里的名词捞出来才发现的。1.2 这台机器做了什么、没做什么简单说它的工作分四步把长文本切成句子把句子切成词给每个词标上词性再按词性把词分派到不同的候选桶里。名词和名词短语进“类候选”桶动词进“操作候选”桶某些特定结构比如“某某负责某某”“某某提交某某”会被识别成参与者与用例的候选。有些实现还会做词频统计把出现次数多的词排在前面——这个排序很关键因为高频词大概率是核心领域概念。它没做的事情同样清楚。第一它不判断语义重要性“系统”“数据”“信息”这类词在文档里频率最高但它们几乎从来不是类。第二它不处理同义合并“客户”和“用户”在它眼里是两个独立的词。第三它识别不了关系两个类之间是关联、聚合还是泛化它一概不管——这是模型里信息量最大的部分也是最没法自动化的部分。第四它不处理中文的复合词边界“设备巡检记录表”到底是三个类还是一个类它给不出答案。理解这四条边界你就知道后面的人工环节该往哪使劲了。1.3 什么材料值得跑一遍什么材料别浪费我的判断标准很粗暴看文本里“实体密度”。一段文字里如果每两三句就能拎出一个业务概念那这段材料就值得跑如果通篇是“系统应具备良好的可扩展性”“界面应简洁友好”这种非功能性描述跑出来全是噪音。比较理想的输入是这几类用户故事“作为仓库管理员我希望在入库时扫描批次码”、业务规则清单“单个订单金额超过五万元需二级审批”、领域术语表、会议纪要里记录的业务流程描述。这几类材料的共同点是主语、宾语、动作都比较明确词性标注的准确率会高很多。不太理想的输入是架构设计文档通篇技术名词跑出来全是框架名、接口文档字段名不是自然语言、宣传材料、以及那种一句话写三行的“诗意需求”。还有一类特别坑——带大量表格和流程图的文档转成纯文本后结构全丢分析结果会乱成一团后面会专门讲怎么处理。2. 底层的逻辑一句话是怎么被拆成候选类的不去理解这一层调参就是瞎调。我用一个具体句子走一遍你就能明白为什么有些词被识别成类、有些被漏掉。原句“仓库管理员在入库单确认后系统自动生成对应的库存变动记录并把异常批次标记为待复检。”这句话进流水线之后大致经历这样的处理先按标点和连接词切分成两个子句每个子句做分词得到“仓库”“管理员”“入库单”“确认”“系统”“自动”“生成”“对应”“库存”“变动”“记录”“异常”“批次”“标记”“待”“复检”这样一串词然后做词性标注名词性的是“仓库、管理员、入库单、系统、库存、变动、记录、异常、批次、复检”动词性的是“确认、生成、标记”。最后按规则分派“仓库管理员”作为一个名词短语进类候选“入库单”进类候选“库存变动记录”很可能被切成“库存”“变动”“记录”三个独立候选——这就是后面要处理的问题。2.1 分句、分词、词性标注这条流水线分句看起来最简单其实坑不少。中文里逗号连接的长句很常见一个句子里塞了三层逻辑切分粒度如果设得粗整句会被当成一个分析单元词性标注的上下文窗口就被稀释了。分句粒度设得细又会把“入库单确认后”和“生成库存变动记录”拆成两个互不相关的片段主谓宾关系断了。我的经验是把分句粒度调细一些宁可多切因为候选元素是按词来的句子层面的语义关系反正也保留不下来不如让每个词都落在更干净的上下文里。工具里如果有“最小句长”之类的参数可以设一个下限比如短于六个字的片段直接合并到相邻句避免出现“确认后”这种半截句子导致的误判。词性标注的准确率直接决定候选质量。主流实现都是基于统计模型的标注质量取决于训练语料的领域匹配度。这就解释了一个常见现象同一段文字写“用户提交申请”标注得挺准写“报文经网关透传至下游服务”就开始乱标——“透传”这种技术动词在通用语料里出现频率极低模型可能把它标成名词于是它就被塞进类候选桶里了。这不是工具的错是训练数据的覆盖问题只能靠后面的领域词表去纠。提示先用一段自己最熟悉的业务文本试跑把明显标错的词记下来这批词就是你后面要加进自定义词表的种子。2.2 名词进类桶、动词进操作桶规则和它的失效边界这套映射规则的出发点是语言学里一个很朴素的观察在需求描述里被操作的对象通常是名词操作本身通常是动词。这个观察在简单句上非常有效但一遇到复杂结构就失效主要有三种典型情况。第一种动词名物化。“系统对订单进行校验”里“校验”是动词但在“校验规则需要配置”里它变成了名词而且它确实应该是一个类校验规则。词形还原做得好的实现能部分处理但中文没有形态变化全靠上下文所以经常两种判断打架同一个词在两个句子里被分到不同的桶里。这种时候我一般不纠结先把两个桶里的都留着人工合并阶段再定。第二种动宾短语被整体识别为类。比如“提交报销申请”分词后可能产出“提交”“报销”“申请”三个候选“报销申请”其实才是一个完整的类。这属于复合词边界问题下一章细讲。第三种形容词性名词。像“异常批次”“可用库存”“有效订单”这些带定语的名词短语在业务模型里往往是独立的概念异常批次和正常批次的处理流程完全不同但分词可能把定语和中心词分开变成“异常”和“批次”两个候选前者词性不明直接被丢弃。2.3 三个关键开关停用词、同义词、词形还原这三个配置项决定了候选清单的“信噪比”值得逐个说。停用词表是最直接的手段。默认词表里一般已经内置了“系统”“用户”“数据”“信息”“功能”“进行”“可以”“需要”“支持”这类高频低信息量的词但远远不够。我的做法是第一次跑完之后按词频从高到低看前三十个词把其中“作为类没有意义”的全部加进自定义停用词表。比如做物流系统“单号”“状态”“时间”这些词可能在文档里出现上百次但它们更可能是属性而不是类先停掉让真正的业务实体浮上来。停用词表是可以随时改的改完重跑一次分析成本很低。同义词词典解决的是合并问题。文档里“客户”“用户”“会员”混用是常态如果不做归一化候选清单里会同时出现三个词你生成图之后要手工合并三次。配置方式一般是一行写一组用分隔符隔开把想合并的词写在同一行指定一个“标准词”。这里有个经验别在第一次分析时就急着配同义词。先让它们各自出现你才有机会判断它们到底该不该合并——“客户”和“用户”在电商场景里可能是一回事在 B 端场景里可能是两个完全不同的实体一个是签约主体一个是操作账号。词形还原在英文材料里效果明显单复数、时态、派生词都能归并“orders”“ordering”“ordered”会合并到“order”。中文场景下这个开关基本不起作用因为中文没有词形变化真正需要的是分词粒度控制那是另一套东西。所以如果你的文本是中文不要太指望这一项能带来多大改善。3. 完整实操走一遍从一份需求文本到一张能用的类图下面这段流程我按实际顺序走一遍中间夹着参数取值和判断依据。为了避免涉及具体业务我用一个虚构的“设备巡检管理”场景材料是四条需求描述原文不长但足够把流程跑通。先准备输入文本。理想的输入是纯文本一行一条需求或者一段一段自然描述不要带序号嵌套、不要带表格、不要带图片占位符。如果你手上的材料是 Word 或 PDF我的建议是先另存为纯文本人工过一遍把页眉页脚、目录、图表标题全部删掉。这一步看着琐碎但它对结果的影响比后面任何参数都大——图表标题和页眉往往包含“图 3-1”“表 2 设备清单”这种内容分词之后会产出一堆无意义的候选把真正有用的词挤出视野。3.1 第一步把输入文本洗干净清洗的标准我总结成三条只留完整陈述句、一句话只说一件事、术语统一。“只留完整陈述句”是说把“如果……则……”这种条件句、疑问句、感叹句都尽量改写成陈述句。“巡检人员是否需要拍照上传”这种句子分词之后“是否”“需要”会干扰词性判断改写成“巡检人员拍照上传巡检结果”就干净多了。“一句话只说一件事”是针对长句的。像“巡检人员在到达巡检点后扫描设备二维码系统记录到达时间并根据预设的巡检项逐项录入结果如发现异常需上传照片并填写说明”这种句子里面塞了四个动作、三个实体直接丢进去分析词性标注的上下文窗口会被拉得很长误判率明显上升。拆成四句每句一个动作识别质量立刻不一样。“术语统一”是最费力但收益最高的一步。文档里“巡检点”“巡检位置”“点位”如果混用分析结果就是三个候选类你事后要合并三次。在清洗阶段就用查找替换统一成一个词后面的工作量直接减半。我一般的做法是先通读一遍把所有指代同一事物的不同说法列出来定一个标准词然后全文替换。注意统一术语的时候要小心过度合并。有些词看着像同义实际是不同粒度比如“设备”和“设备类型”前者是实例后者是分类合并了模型就错了。拿不准的先保留等在候选清单里看到它们各自的出现上下文再决定。3.2 第二步先跑一次“只看不动”的分析第一次运行的目的不是产出是摸底。我一般会把筛选条件全部放开不加停用词、不做同义词合并就看机器把什么东西捞出来了以及它们的频次分布。观察的重点有三个。第一是高频候选词的前十个这些基本就是核心业务实体如果里面有明显不该是类的东西比如“系统”“操作”说明默认停用词表需要补充。第二是那些“一眼看起来是动词却被放进类桶”的词这通常意味着分词或词性标注出了问题需要回头看看原文那句话是不是太长或结构太怪。第三是频次极低的候选词只出现一次的那些这批词里混着两类东西一类是真正的边缘概念一类是分词错误产生的碎片。判断方法很简单切回原文搜一下这个词看它所在的句子是不是描述了一个独立的业务概念。这一步还有个小技巧把候选清单按字母或者拼音排序看一遍。按频次排序容易只关注头部排序方式一换你会发现一堆中等频次但语义很重要的词——它们可能只在文档里出现两次但每次都是关键业务规则的主语。3.3 第三步候选元素的分类筛选这一步最花时间候选清单出来之后界面上通常会把候选元素按类型分栏摆着类候选、属性候选、操作候选、参与者候选、用例候选。你要做的就是把每个词拖到它该去的位置或者直接删除。这里有一套我自己的判断顺序分享出来先判断“它是不是一个需要独立管理生命周期的东西”是的话进类候选再判断“它是不是只作为某个类的描述性信息存在”是的话进属性候选如果它是“某个动作的结果”比如“巡检记录”那它既可能是类也可能是关联类先放类候选生成图的时候再决定。动词类的候选如果它的主语是一个角色、宾语是一个业务实体那它大概率是一个用例或者一个操作如果它只是修饰性的“进行”“完成”“实现”直接删。这个环节耗时最长的不是判断是重复项合并。因为词形和分词的原因同一个概念常常以“设备”“设备信息”“设备基本信息”三种形式出现。合并的时候不要只看字面要看它在原文里出现的位置——如果三种说法出现在同一段落的相邻句子里那基本可以确定是同一概念的不同表述如果出现在不同章节而且各自有独立的属性描述那可能是不同粒度的概念该拆就拆。我做过一个统计一份两千字左右的需求文本跑出来的原始候选大概在八十到一百二十个之间经过停用、合并、删除之后真正进入模型的类通常在八到十五个。这个压缩比心里有数你就不会觉得这步“怎么这么慢”。3.4 第四步一键生成图然后立刻动手重构候选元素确定之后生成图基本是一键操作工具会把类候选画成类框把属性填进类框的下半部分操作填进更下面一栏关系则按你指定的规则连大部分实现支持“同句共现则连线”这种粗糙规则。我要强调的是生成出来的图只是草稿不要试图去“修”它要重构它。草稿的问题集中在三处一是布局混乱类框挤在一起或者拉得极开连线交叉成蜘蛛网二是关系全是无向关联没有方向、没有多重性、没有聚合三是类里塞了大量本该是属性的东西或者反过来本该独立的类被压成了一个属性。重构的顺序我固定为三步。第一步重新布局先按业务域分包或分簇把同一业务环节的类放一起自动布局之后手工微调让主干流程从左到右走。布局这件事看着是美观问题实际上它直接影响你后面找问题的效率图一乱你连“这个类为什么跟那个类有关联”都看不出来。第二步补关系和多重性这是草稿里最缺的部分需要回原文逐句读把“一个巡检点对应多台设备”“一条巡检记录只属于一次巡检任务”这类约束翻译成多重性标注。第三步提炼抽象把几个类里重复出现的属性往上提抽成父类把只有一两个属性且完全依附于主类的降级成属性或值对象。这三步做完图才从“词汇表可视化”变成“模型”。3.5 第五步文本变了怎么办同步策略要提前定实际项目里需求文档很少一次定稿。文本改了之后重新跑分析会遇到一个具体问题机器不认识你上次已经建好的模型元素它会把“巡检点位”当成一个全新的候选而你的模型里已经有“巡检点”这个类了。处理这个问题的关键在于建立文本与模型元素之间的对应关系。有些工具支持把候选元素直接映射到已有模型元素上映射之后重新分析时如果文本里出现同样的词它会关联到你已有的元素而不是新建。如果你的工具不支持这层映射那就退一步维护一张手工的对照表左边是文本里的术语包括所有变体右边是模型里的元素名。这张表本身就是有价值的产出它相当于一份轻量级的领域词汇表新人接手时看这张表比看模型快。还有一个更省事的做法每次重新分析之前先只跑“新增部分”的文本。把文档按章节切开只把改动过的章节丢进去分析输出的是增量候选你手工往已有模型上挂。这样既避免了全量重跑的噪音也避免了重复创建。4. 中文文本的三个硬伤以及各自的绕法前面反复提到中文场景效果打折这一章集中说清楚原因和对策。这三点是我在实际项目里反复撞墙撞出来的理解了能省不少时间。4.1 分词边界中文没有空格工具靠猜英文一个词一个空格分词是天然完成的中文连着写词边界全靠模型判断。“库存变动记录表”这七个字可以有至少四种切法库存/变动/记录表、库存/变动记录/表、库存变动/记录/表、库存/变动/记录/表。切法不同候选元素就完全不同。没有任何工具能在这上面做到 100% 准确因为切分本身依赖语义理解而语义理解恰恰是它想做的事。实际应对的办法是在输入阶段就人为划定边界。具体做法是把你在业务上认定的复合术语在文本里用统一写法固定下来必要时可以加一个特殊标记比如统一写成“库存变动记录”这个词组不加“表”字或者固定写成“库存变动记录单”。这样分词结果的方差会小很多。另一个做法是把领域复合词加进分词词典。部分工具支持自定义词典加进去之后这些词会被当成一个整体不再被切开。这个配置项很容易被忽略但对中文材料的改善幅度是所有参数里最大的值得优先花时间配置。4.2 复合名词与“的”字结构定语和中心词的纠缠“待复检的异常批次”“超过阈值的温度记录”这类结构分词之后容易产出“待复检”“异常批次”“超过”“阈值”“温度记录”一堆碎片其中“待复检”这种词根本没地方放。而实际建模时“待复检批次”很可能是一个有独立状态和独立处理流程的类。我的处理原则是“的”字结构一律在清洗阶段改写。“待复检的异常批次”改写成“待复检批次”“超过阈值的温度记录”改写成“超阈值温度记录”或者拆成两个概念“阈值”和“温度记录”分别描述。改写之后定语要么变成中心词的一部分复合词要么独立成一个概念不再处于悬空状态。复合名词的百勇判断我有个很土的办法问自己“这个概念有没有自己的属性”。有就是类没有就是属性或者复合词的一部分。“异常批次”有自己的状态、处理人、复检时间是类“批次编号”没有自己的属性是属性。这个判断标准简单粗暴但基本不出错。4.3 隐性关系机器永远给不出的那部分文本分析能给出候选元素给不出关系。而一个模型里信息密度最高的恰恰是关系。举几个例子你就明白为什么机器做不了这件事。文档写“每个巡检点配置若干巡检项”机器能识别出“巡检点”“巡检项”两个类但“配置”这个动作背后的是一对多关联还带“巡检点删除时巡检项是否级联”这样的约束这层信息它捕不到。文档写“巡检任务由班长指派给巡检人员”机器能识别出三个名词但“指派”是关联类还是操作取决于它在系统里是否需要记录指派时间、指派理由这些信息这种判断只有懂业务的人能做。剩下这部分工作我的做法是回到原文逐句找“动词”把每个动词都当成一个关系线索。动词的主语和宾语各对应一个类然后判断这个动词描述的是瞬时行为操作、持续关系关联、还是归属关系聚合/组合。这一步做完模型才真正立起来。这也是为什么我一直说文本分析省的是“找词”的时间不是“建模”的时间找词大概占整个建模工作量的三成剩下七成的关系判断、抽象提炼、约束补充一步都省不掉。5. 常见问题速查与几条踩坑经验把我在用这个功能时遇到的典型问题整理成表遇到直接对照查。5.1 问题速查表现象大概率原因处理办法候选清单里全是“系统”“数据”“信息”默认停用词表未覆盖业务场景按词频排序取前三十把无信息量的词批量加进自定义停用词表后重跑中文文本识别出的类别明显偏少分词边界错误复合词被切碎配置自定义分词词典把领域术语作为整体加入同一个概念出现多个候选术语在文档中未统一回到原文做查找替换统一术语或在同义词配置中归并到标准词动词被识别成类动词名物化或分词把动宾结构切开人工在分类阶段改桶同时在停用词表里处理掉无意义动词生成的图连成蜘蛛网工具按“同句共现”自动连线生成后先删掉全部自动关联按原文逐句重建类里塞满了本该独立的类复合概念被压成单个名词检查该名词是否有独立属性和生命周期有则拆成独立类文档改版后重复创建元素未建立文本术语与模型元素的映射维护术语对照表或只对改动章节做增量分析PDF 导入后结果错乱页眉页脚、表格结构被转成散乱文本先转纯文本人工删除非正文内容再做分析属性候选几乎为空文本里缺少对实体特征的描述补充“某某包含某某信息”这类描述性语句或直接手工补属性5.2 三条踩过坑才记住的经验第一条一次只分析一个业务域。我最开始图省事把整份需求规格说明书一次性丢进去结果候选清单里两百多个词跨了三四个业务模块判断起来脑子完全转不过来。后来改成按模块切开一次只跑一个模块的文本候选量控制在几十个判断效率高得多而且模块内的术语天然一致。这个习惯保持到现在哪怕文本只有三千字只要跨域我也拆开跑。第二条停用词表是活的要跟着项目走。每个业务域的高频噪音词都不一样物流域是“单号”“状态”财务域是“金额”“科目”不要指望一份通用停用词表打天下。我的做法是每个项目建一份自己的停用词表项目结束时归档下个同类项目可以直接复用改改比从零开始省事。第三条把候选清单当成资产留下来。候选清单不只是一次性中间产物它是这个项目最原始的领域词汇表。我现在的习惯是把清洗后的文本、配置好的停用词表和同义词表、最终的候选清单一起归档。后面做详细设计、写接口文档、甚至和业务方对齐术语这份清单都能直接拿来用。有次一个新同事问我某个业务概念的正确定义我翻出半年前的候选清单上面记录着这个词在哪几条需求里出现过、当时判断成了类还是属性、为什么这么判断比翻文档快得多。最后分享一个小技巧。如果你用的是支持多文档合并分析的实现可以把同一业务域的几份材料需求、纪要、术语表一起加载合并跑一次。同一个概念在不同材料里反复出现词频会被拉高排序自然靠前而那些只在一份材料里出现的偶发词会被稀释下去。这个做法对提升候选清单的排序质量效果明显代价是文本清洗的工作量翻倍值不值得看你手上有多少时间。