简介Word文档的自动化处理是工程文档管理的基础技术而技术规范书作为招投标与项目验收的重要载体往往以 .docx 格式存在。docx 本质上是一个包含多个XML文件的压缩包段落文本、标题样式、大纲级别和多级列表编号分别存储在不同节点中机器无法仅凭视觉特征判断章节边界。通过 Java 语言结合 Apache POI 库可以逐段读取文本与样式ID并基于大纲级别、标题样式和编号模板的优先级规则准确还原文档的章节结构。这一能力在文档结构校验、验收条款抽取、目录生成等场景中具有直接的工程价值。将规范书解析为可校验资产不仅能自动检查章节连续性和条款完整性还能显著减少人工复核成本。以技术规范书为切入点掌握 docx 的解析原理与避坑要点是构建文档自动化流程的关键一步。1. 技术规范书.docx不是一份普通 Word它是项目的边界面技术规范书.docx 这个文件名在项目交付里出现的频率远超想象。招投标的应标文件、系统建设时的需求边界、验收阶段唯一能对照的测试依据最后都是落到这样一份 Word 文档里。它不是产品说明书更不是合同范本而是甲方、设计、开发、测试四方共同认下的“边界面”系统要建成什么样、用什么标准验收、交付物包含哪些都在这份文件里。对一线工程师来说真正的门槛从来不是打字是怎么让每一个条款都能被量化验收以及怎么让机器读懂这份 docx 的章节结构。这篇笔记就从这两个问题讲起。2. 技术规范书写什么先把章节骨架立住再谈语法2.1 一份能进评审会的规范书至少要有这 12 个标准部分写技术规范书最容易犯的错是一上来就写“系统简介”然后想到哪写到哪。经手过评审通过率比较高的规范书骨架基本固定评审专家翻到某一章就知道该看什么、该挑什么毛病。这个骨架不是某个标准委员会定的而是多年评审实践里长出来的共识。一份完整的技术规范书可以拆成 12 个部分每个部分对应一类评审关注点章节核心内容评审关注点封面项目名称、文档编号、密级、版本编号规则和密级是否走公司流程修订记录版本号、日期、修订摘要、编制人上一轮意见有没有闭环概述建设背景、目标、范围、术语范围边界是否明确避免后期扯皮总体方案逻辑架构、技术选型、部署架构选型理由站不站得住脚功能规范功能清单、业务流程、权限模型每项功能是否可测非功能规范性能、安全、可用性、兼容性指标指标有没有量化接口规范内部/外部接口、数据字典字段级定义到不到位资源要求服务器配置、网络带宽、容量估算预算是否合理验收标准验收项目、测试方法、通过条件是否一条一验收实施交付工期里程碑、交付物清单、培训计划责任边界是否清晰风险与合规主要风险、应对措施、引用标准号有哪些无法承诺的边界条款附录术语表、参考文档、会议纪要清单可追溯性第 9 章“验收标准”是最容易敷衍的。很多规范书把功能清单复制一遍改成“系统应实现 XXX 功能”就当验收标准评审专家一眼就能看穿。验收标准的写法应该是“给定输入、预设环境、判定条件、测量方法”四个要素齐全否则无法执行。2.2 条款必须三段式需求描述、技术指标、验收方法技术规范书正文里最常出现的翻车句是“系统应具备良好的性能”和“系统应保证数据安全”。这种句子没法验收因为“良好”和“保证”是不可测量的形容词。可以给自己定一条死规矩规范书里每一条功能要求都必须写成“需求描述 技术指标 验收方法”的三段式结构。举个例子。反例是“登录功能响应快用户体验好”。正例是“在 500 并发用户、90% 请求走加密通道的压测场景下登录接口平均响应时间不超过 3 秒TP99 不超过 5 秒验收方法使用 JMeter 按上述参数执行 30 分钟压测记录聚合报告中的平均值与 99th 百分位。”信息项拆开看需求描述说了功能与场景技术指标给了并发数、响应时间、成功率三个可量化值验收方法交代了工具、参数和判定口径。评审专家想质疑也得摆数据而不是一句“用户体验”就能糊弄过去。这种三段式对写文档的人也是保护。有次做一个数据交换项目因为没写验收方法交付时甲方对“响应快”的理解从 3 秒变成了 1 秒扯了半个月。后来所有规范条款都带验收方法这类争执才算停止。2.3 章节号别手打用多级列表和标题样式把结构锁死写技术规范书的人九成以上的痛都来自同一个动作手打章节号。今天在第二章前面插入一段后面的“2.1”“2.2”全部错位目录也要手动改一遍改完之后引用它的地方又全乱。要根治这个问题必须把编号交给 Word 的多级列表把章节格式交给样式。具体做法是在 Word 里为“标题 1”“标题 2”“标题 3”配置一套多级列表规则让编号格式等于该级标题的自动编号。这样任何插入、删除、移动章节的操作Word 会自动重排编号和目录。样式方面不要用正文加粗冒充标题必须用标题样式因为标题样式自带大纲级别这个级别就是后面 Java 解析时要依靠的机器可读标记。在这个阶段就顺手把样式表定成模板比写完全文再统一样式省力得多。样式名最好是英文 ID 而不是中文别名因为不同 Word/WPS 本地化之后中文样式名可能变英文样式 IDHeading1、Heading2通常是稳定的。这一点到解析 docx 时就是决定成败的分水岭。3. 用 Java 读取 docx 中的段落和对应章节先把这个 zip 拆开3.1 docx 的物理结构document.xml、styles.xml、numbering.xml 三件套docx 不是一个无法窥探的黑匣子它本质是一个 zip 压缩包。把“技术规范书.docx”的后缀改成 .zip 解压开会看到 word/ 目录下躺着几个关键的 xml。正文在 word/document.xml 里按出现顺序记录段落和表格样式定义在 word/styles.xml 里包括标题样式、正文样式以及每个样式绑定的默认大纲级别多级列表编号规则在 word/numbering.xml 里也就是“1.1”“1.1.1”这种自动编号的数字是怎么算出来的。理解这个结构对后面写代码很重要因为 Apache POI 读取 docx 时本质上就是在这几份 xml 之间做映射。段落文本在 document.xml 的 w:p 下样式名指向 styles.xml 里的 w:styleId编号信息指向 numbering.xml 里的 w:abstractNum。在 Java 里拿到的 XWPFParagraph 对象就是一层对 w:p 的封装而 getStyle()、getNumFmt() 这些方法内部都在向 styles.xml、numbering.xml 查表。常见做法是用 Apache POI 的 poi-ooxml 模块它同时覆盖段落、表格、样式和编号的读写。对于只读解析稳定性足够不需要引入 docx4j 那种重型库。3.2 搭好依赖poi-ooxml 的 Maven 坐标如果项目是 Maven 工程在 pom.xml 里加这一段dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency这里用 5.2.5 这个版本号是这个系列里比较稳定的一个。POI 5.x 依赖的 ooxml-schemas 会自动带进来不需要手动加 schemas 的 jar。如果工程里同时有旧版本的 POI 3.x记得先排除掉否则运行时会出现类冲突最典型的报错是 NoClassDefFoundError 指向 org/apache/poi/xwpf/usermodel/XWPFDocument先升级到统一版本再排查别的。3.3 第一条可运行代码读段落文本和样式名先写一个最小可运行的解析器目标是把文档里每一个段落的文本和样式名打印出来import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.usermodel.XWPFParagraph; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Paths; public class DocxSectionParser { public static void main(String[] args) throws IOException { try (XWPFDocument document new XWPFDocument( Files.newInputStream(Paths.get(技术规范书.docx)))) { for (int i 0; i document.getParagraphs().size(); i) { XWPFParagraph paragraph document.getParagraphs().get(i); String text paragraph.getText(); if (text null || text.isBlank()) { continue; } String style paragraph.getStyle(); System.out.printf(第 %4d 段 | style%-12s | %s%n, i, style null ? (null) : style, text); } } } }这段代码做三件事打开指定路径下的 docx、遍历文档流里的每个段落、过滤空段落后打印样式名和文本。XWPFDocument 实现了 AutoCloseable所以用 try-with-resources 保证文件句柄释放。getStyle() 返回的是样式 ID不是样式显示名——这句话要记牢因为它在中文环境下容易骗人。具体说Word 内置标题样式“标题 1”的显示名是中文但 styles.xml 里的 styleId 是“1”或者“Heading1”取决于文档来自中文模板还是英文模板。getStyle() 返回的是后者。拿“1”去和“Heading1”做 equals 比较必然为空这是新手判断标题段落最常掉进去的坑。后面 4.2 会说怎么同时兼容这两种取值。3.4 读大纲级别段落属性里的结构标记文本和样式名都有了还差最关键的一步判断这个段落是不是标题、是第几级标题。在 Word 中标题的真正身份不是字体大小而是段落属性里的大纲级别outlineLvl。标题 1 到标题 9 对应大纲级别 0 到 8。用代码读它的方式是直接挖到段落属性对象import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTPPr; public static int getOutlineLevel(XWPFParagraph paragraph) { if (paragraph.getCTP() ! null paragraph.getCTP().getPPr() ! null) { CTPPr ppr paragraph.getCTP().getPPr(); if (ppr.isSetOutlineLvl()) { return ppr.getOutlineLvl().getVal().intValue(); } } return -1; }getOutlineLvl() 返回 -1 表示没有设置大纲级别这个段落在结构上不是标题。返回 0 到 8 对应标题 1 到标题 9。在实际文档里标题样式通常会绑定大纲级别所以绝大多数情况下读了样式也就等于读了大纲级别但样式和段落属性是两套独立的机制某些人为了省事把标题样式改成了“正文 加粗”此时 outlineLvl 就是唯一可靠的机器可读信号。4. 章节边界怎么判大纲级别、标题样式与多级编号的识别优先级4.1 为什么不能只靠看文字样子判断章节人工阅读时看到加粗、字号大的“2.1 系统架构”就认为是章节标题但机器不能这么读。一是字体大小不是结构信息同一个文档里出现大号黑体字的地方可能只是警示框二是自动编号的数字不是静态文本读取到的文本里甚至没有“2.1”这几个字符三是不同模板的标题样式 ID 千奇百怪。所以判断章节边界必须按“结构化优先级”依次检查而不是靠一两个视觉特征拍脑袋。4.2 优先级第一大纲级别大纲级别是 Word 里最接近真实文档结构的属性。判断逻辑简单得到 outlineLvl 0 到 8 的段落就是标题值越小层级越高。但要注意outlineLvl 是段落属性而不是样式属性所以要在 ppr 上取方法见 3.4 节。如果一个段落用了很漂亮的“标题样式”但样式没有绑定大纲级别读出来的 outlineLvl 依然是 -1。这就是为什么要强调“样式 大纲级别双重校验”。折中的做法是outlineLvl 0 直接认定标题outlineLvl 为 -1 但样式名命中了 Heading1/Heading2/标题 1/标题 2 前缀时当作标题处理但同时记一条告警提示文档结构不规范。最理想的情况还是回到源文档把样式修好解析代码只能兜底不能背锅。4.3 优先级第二标题样式 ID样式名判断没有统一标准所以只能写一个兼容性较强的匹配函数处理下面几种情况英文内置样式 Heading1、中文内置样式“标题 1”、中文模板里的自定义样式“rdt-xx”这类带前缀的样式以及部分国内模板把标题样式 id 直接存成“1”“2”“3”。public static boolean isHeadingStyle(String styleId) { if (styleId null) { return false; } return styleId.matches((?i)(heading|标题|h)[1-9].*) || styleId.matches([1-9]) || styleId.matches(.*(标题|heading)[1-9].*); }这个正则会把 Heading1、heading_1、标题 2、h3 都视为标题样式。注意它不会匹配“正文 1”因为正文样式不会命中上面的模式。实际工程里模板更乱经常出现“WD-Header-1”“f_Heading2”这种带项目前缀的样式名做法是在项目启动时先扫一遍全部样式打印出来人工确认之后把规则写进配置文件而不是在代码里不停改正则。4.4 优先级第三多级列表编号的解析路径有些文档没有用标题样式章节号是 Word 自动编号的多级列表。此时段落文本里没有“2.1”这个静态数字数字是渲染时算出来的。读取编号需要走两条路先从段落的 numPr 拿到 numId 和 ilvl再拿 numId 去 numbering.xml 查抽象编号定义和级数格式模板。POI 的 XWPFParagraph 提供了更省事的方法getNumFmt() 返回当前段落的编号格式decimal 表示阿拉伯数字lowerLetter 表示小写字母getNumLevelText() 返回编号模板比如“%1.%2.”其中 %1、%2 分别代表第 1 级、第 2 级编号的占位符。拿到模板和格式之后需要自己在解析器里维护一个同级计数器才能在输出时还原“2.1”“2.1.1”这样的完整章节号。但 getNumLevelText() 返回的是模板而不是真实数字。真实数字的还原需要遍历所有同级段落每次编号格式为 decimal 时自增计数。这个逻辑看起来简单实际上有个容易忽略的细节计数器的自增只发生在段落实际出现的位置而不能在抽象编号定义里静态推演因为文档可能从第 3 章开始编号起始值被修改过也可能中间跳级。所以解析时要维护一个“当前层级计数栈”段落每进入一级对应计数加一退出时清零。这块代码建议单独封装成一个类后面所有章节号生成都走它。4.5 综合判定四条规则按顺序走把前面三条策略合并成一条判断链优先级从高到低是大纲级别 → 标题样式 → 多级编号模板 → 正则兜底。public static boolean isHeading(XWPFParagraph paragraph) { // 规则一大纲级别是最可靠的结构信号 int outlineLvl getOutlineLevel(paragraph); if (outlineLvl 0 outlineLvl 8) { return true; } // 规则二样式名判定兼容中英文模板 if (isHeadingStyle(paragraph.getStyle())) { return true; } // 规则三多级编号模板命中的段落通常是标题行 String levelText paragraph.getNumLevelText(); if (levelText ! null levelText.contains(%)) { return true; } // 规则四兜底——文本以“1.” “1.2” 这类开头且行内没有句号 String text paragraph.getText(); return text.matches(^\\d(\\.\\d)*\\s\\S.*$) !text.contains(。) text.length() 80; }四条规则串起来之后解析的正确率会明显上升。但规则四永远只是兜底因为它会把“1. 项目概述”这种正文列表项也误判成标题。我建议把正则兜底的结果单独打标记让后处理脚本去人工复核不要让机器自作主张。5. 避坑docx 解析常见的五个翻车现场5.1 现象Word 里明明是标题读出来样式却是 Normal这是一个非常经典的翻车现场。文档在 Word 里显示加粗大号字并且目录也正常出现但用 POI 读出来 style 是 NormaloutlineLvl 是 -1。原因是撰写人没有用标题样式而是用“正文样式 手动加粗 手动加大字号”做的视觉标题目录则是靠人工截图或域代码硬凑的。对机器而言这个段落就是一段普通正文没有任何结构标记。解决先跑 3.3 节的打印程序把文档全部段落的样式刷一遍找出哪些“视觉标题”命中不了 isHeadingStyle。这种文档不能靠代码硬猜最省事的办法是以大纲级别为准在源文档里批量套用标题样式后重新导出。如果文档已经定稿且不能改只能用正则兜底但必须接受误判风险。5.2 现象段落读出来缺少原文里的“2.1”规范书里明明有“2.1 系统架构”打印出来的文本却只有“系统架构”四个字。原因在于章节号是 Word 自动编号数字不在文档 XML 的文本节点里而是渲染时根据多级列表规则现场计算出来的。getText() 拿不到数字很正常。解决不要试图从文本里找回章节号。用 4.4 节的方案读 numId、ilvl、getNumLevelText()配合计数器栈还原完整章节号。注意起始值如果文档里第一章从“第 3 章”开始编号检查 numbering.xml 的 lvl 节点里有没有 w:start这个值决定计数器从几开始。5.3 现象表格里的章节段落全被跳过了规范书的接口规范、性能指标特别喜欢用表格列数据表格里也有段落。如果只遍历 document.getParagraphs()表格内部的段落一个都读不到——XWPFDocument.getParagraphs() 只覆盖文档流不覆盖表格行和单元格内部的段落。解决把表格遍历纳入解析路径for (XWPFTable table : document.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { for (XWPFParagraph para : cell.getParagraphs()) { processParagraph(para); } } } }代码逻辑按嵌套三层往下走表 → 行 → 单元格 → 段落。注意合并单元格会重复访问同一个 cell建议用 cell 的引用 ID 做去重否则同一段内容会解析出多份。5.4 现象文本框和内容控件里的文字读出来是空的有些规范书会在封面和附注里用文本框写“文档编号”“密级”或者用内容控件SDT做可填写区域。段落遍历经过这些位置时getText() 返回空串但屏幕上明明有字。原因是这些文本被放在 w:txbxContent 或 w:sdt 节点里不属于普通 w:p 的文本 run 序列。解决遍历 body 元素时单独处理 XWPFSDT 类型for (IBodyElement element : document.getBodyElements()) { if (element instanceof XWPFParagraph) { processParagraph((XWPFParagraph) element); } else if (element instanceof XWPFSDT) { String sdtText ((XWPFSDT) element).getContent().getText(); System.out.println(sdt: sdtText); } else if (element instanceof XWPFTable) { // 复用 5.3 的表格遍历 } }这样内容控件的文本不会丢。但文本框w:txbxContentPOI 没有直接 API需要手动挖底层 XML 才读得到通常只有封面会用到。正文里出现文本框本身就不利于机器解析建议从模板层面禁止正文文本框。5.5 现象“1.10”被当成“1.1”的子章节这是比较隐蔽的逻辑坑。假设解析结果用字符串比对排序章节“1.9”之后出来“1.10”字典序比较会判定“1.10” “1.9”导致章节树错乱。表现是生成目录时“1.10 数据库设计”被塞到“1.1 需求分析”下面。解决章节号比较必须按数值分段不能按字符串。把“1.10”拆成 [1, 10]把“1.1”拆成 [1, 1]再逐个比较数值。同时章节树的构建也建议用“级数数组”结构而不是 String 级联避免反复拼接和截断。这行逻辑写起来很简单但一旦忘记数据量一大必翻车属于那种只有在目录生成时才会暴露的隐藏 bug。6. 把技术规范书变成可校验资产模板化与自动章节检查先讲一个技巧。规范书如果只是给人看写完之后价值就结束了但如果要长期用于招投标复用和验收追踪它应该是一个可校验的资产。可校验的前提是模板足够硬定义一套固定样式“规范-标题1”“规范-标题2”“规范-条款”所有新项目只能在这套模板上改内容不能改结构。这样解析脚本不用每次适配。配套校验脚本检查三件事。第一章节连续性。用 4.5 的判定逻辑拿到每个标题的级数数组校验顺序必须是严格递增且同一父级下不允许跳过数字发现缺失就输出告警。public static boolean isSequential(Listint[] levels) { for (int i 1; i levels.size(); i) { int[] prev levels.get(i - 1); int[] curr levels.get(i); if (curr.length prev.length) { // 上升到父级章节时允许检查父级是否相同 continue; } if (curr.length prev.length curr[curr.length - 1] ! prev[prev.length - 1] 1) { return false; } } return true; }第二验收条款完整性。对“规范-条款”样式的段落做正则检查是否包含量化单位词“秒、毫秒、%、Mbps、台、年”中的任意一个同时要求句尾有“验收”字样。命中不了就列入不合规范条款列表人工复核。第三修订记录与封面版本一致性。从封面区域提取版本字符串与修订记录表格第一行对比不一致说明文档改完没更新修订记录禁止对外发布。这是吃了两次亏之后才养成的习惯。第一次是评审会在即发现“1.0”版封面下修订记录最高版本是“0.3”被甲方当场质疑版本管理混乱第二次是自动生成目录时“1.10”被拼进“1.1”的子树白花了一天排查。后来把校验脚本挂在保存动作后面每次导出的 docx 都自动跑一遍这三类低级事故再没出现过。自动化不是要把工程师的文档能力取代掉而是把机器能查的机械错误挡在提交之前让人力只处理真正需要判断的内容。希望这份 docx 的解析与校验思路能帮到你下次拿到一份“技术规范书.docx”至少知道第一步该做什么以及哪些坑值得绕开。本文还有配套的精品资源点击获取