农业系统做久了，就会碰上一个绕不开的环节：客户交上来的项目申报书、检测报告、补贴申请表，全是Word文档。系统要自动归档和抽取信息，第一步就得集成Word文档样式解析组件——把标题层级、段落格式、表格结构、图片位置这些“排版元数据”完整拆出来，后面才能接格式校验、内容入库、网页预览、语义抽取这些正经业务。

这篇东西适合两类人：一类是Java技术栈的后端开发，正在做农业申报系统、追溯平台、数字乡村文档库，需要给系统加上Word解析能力；另一类是信息化项目负责人，想评估“文档自动解析”模块到底该自己写还是买组件，以及这套东西的踩坑边界在哪里。我会从业务场景、组件选型、核心实现、Spring Boot集成到排错经验，完整讲一遍我的做法。

1. 农业系统里的“样式解析”，到底在拆什么

在动手写代码之前，先把业务场景想清楚。农业系统的Word文档远不止“把字读出来”这么简单，不同业务环节对样式解析的诉求差异很大。我经手过的项目里，至少有三类典型场景，分别对应不同的解析侧重点。

1.1 项目申报书：先把排版结构还原出来

农业产业化项目申报、示范合作社申报这类场景，系统收到的申报书往往是几十页的Word。页面结构大致是封面、目录、正文标题、投资估算表、绩效目标表。传统做法是让农户或企业上传PDF，再由人工录入结构化字段，效率低、容易错，而且申报单位还经常匿名评审，格式五花八门。

我接到的需求是：系统自动识别申报书里的标题层级（一级标题、二级标题、正文段落），提取各级标题的文本和页码，生成可点击的在线目录；同时校验必填章节（比如“项目实施方案”）是否存在，格式是否合规。要做到这些，解析组件必须以“样式”为线索，不能只做纯文本提取。

具体拆解下来，样式解析要回答这样几个问题：哪些段落是标题？它们分别在第几级？依据是样式名、大纲级别，还是字体字号加粗这些外观特征；段落属于哪个样式族，字体、字号、行距、对齐方式各是什么，这决定后续格式校验的阈值；表格的单元格有没有合并，哪些列是表头，数据行的边界在哪里。

1.2 检测报告：表格里的数据密度最高

农产品质量安全检测报告是另一个高频场景。这类文档的核心信息几乎全部落在表格里：样品编号、受检单位、检验项目、限量值、实测值、单项判定。表格还经常跨页、带合并单元格、表头重复。解析组件要把这类二维表结构转成能落库的关系型数据，难点不在“读文本”，而在“读结构”。

图片部分也不能忽视。质谱图、色谱图、标准曲线图往往以嵌入图片的形式放在检测结果后面。如果系统要做报告追溯、图谱归档，就需要把图片按位置抽取出来，和检测项目建立关联。

农业补贴、涉农资金申请也是同样的逻辑：申请表中身份证号、银行卡号、种植面积这些关键字段散落在表格里，只有把表格结构拆清楚，字段提取才有抓手。我在实际项目里见过不少团队把整篇文档当成一段长文本处理，结果表格跨页后字段错位，这是典型的“没做样式解析”踩坑。

1.3 政策文件批量入库：样式归一化是检索的基础

数字乡村知识库、政策检索平台这类项目，会把历年农业政策、标准规范文档批量转成Markdown或结构化文本入库。原始文件来源不一，有网上下载的docx、有扫描后的PDF、有WPS生成的doc，样式命名千差万别。

样式解析在这里的作用是“归一化”：把不同文档的“标题1”、“Heading 1”、“标题 1”统一映射成标准的一级标题，把首行缩进、项目符号等干扰性样式信息规整掉，只保留对知识组织有意义的层级和属性。这一步做不好，后续全文检索的段落切分、标题层级树形展示都会出问题。我在做政策库时，曾经因为样式名不统一，导致同一篇文章的目录树断成好几截，最后追查了两天才发现是“标题1”和“Heading 1”两种样式名混用。

2. 组件选型：POI、Docx4j、Spire.Doc还是Aspose.Words

很多农业系统跑在政务内网、国产化环境，组件选型必须考虑开源协议、内网可维护性、授权费用和解析保真度。市面上的Word解析组件大致分四类，我基于实际项目经验做了对比。

2.1 为什么Apache POI是默认选择

对Java技术栈的农业系统来说，Apache POI基本是默认解。原因很朴素：Apache 2.0协议，商用无风险；POI对OOXML（docx）的读写能力覆盖很全，XWPF模块能处理段落、表格、图片、图表、页眉页脚；社区活跃，踩坑资料多；完全离线可用，适合内网环境。

POI的不足也要说清楚：它对老版.doc（OLE复合文档）只提供HWPF模块，文本读取可以，但完整还原复杂样式（比如文本框、艺术字、复杂表格）力不从心。所以我在项目中会要求用户上传docx，如果是.doc会先在系统后台用转换服务转成docx再解析。这个约束要在需求阶段就跟业务方说清楚，否则上线后会被基层用户用一堆.doc文档打回来。

2.2 四款引擎的能力矩阵

我的建议是：如果系统只是做样式解析、文本抽取、表格结构化，POI完全够用，而且出了问题自己能修；如果业务涉及Word转PDF、复杂排版还原、公式深度处理等高保真场景，再考虑Aspose或Spire，但要在立项时把授权费算进预算。Docx4j虽然也能做，但它的API更贴近OOXML底层，写起来比POI繁琐，团队维护成本高。

2.3 要不要自研“解析组件”？

很多农业信息化项目会犹豫是否自研解析组件。我的经验是，Word解析这个领域非常深，光是字体配置（ASCII字体和东亚字体的区别）、合并单元格语义、公式域、修订模式就够写好几个月的轮子。已经有成熟的第三方库，没必要重复造。

真正值得自研的是上层业务层，比如样式名映射、表格语义识别、字段匹配规则，这些才和农业业务强相关，也是组件的差异化之处。换句话说，底层用POI搞定“解包”，业务层自己定义“怎么用”，这才是“集成”的正确姿势。

3. 核心实现：基于POI解析Word段落样式与标题结构

下面进入正题。我用Spring Boot + Apache POI来演示，解析目标是docx文档。这套代码已经在申报书解析、检测报告抽取两个模块里跑过，稳定运行一年多。

3.1 依赖引入与环境准备

Maven依赖如下，版本以5.x为例。注意两点：一是poi-ooxml要跟poi版本保持一致，否则容易遇到类冲突；二是在某些内网环境，需要把poi-ooxml-lite一起带上，否则可能遇到OOXML schema类缺失的报错。

<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.5</version> </dependency>

docx本质上是一个zip包，里面的word/document.xml存放正文。POI只是把这个XML解析成了Java对象模型。理解这一点很重要：样式解析组件能拿到多少信息，取决于document.xml里写了什么。比如Word显示“标题1”，底层可能是w:pStyle w:val="Heading1"，也可能是直接设置了大纲级别w:outlineLvl，还可能只是字体加粗变大（手动标题）。这三种情况解析方式完全不同，后面会讲。

3.2 打开文档遍历段落

读取Word文件，遍历所有段落，代码非常直观：

try (InputStream is = new FileInputStream("申报书.docx"); XWPFDocument doc = new XWPFDocument(is)) { for (XWPFParagraph para : doc.getParagraphs()) { System.out.println("段落文本: " + para.getText()); System.out.println("样式ID: " + para.getStyleID()); } }

这里有一个容易踩的坑：getParagraphs()只返回正文中的顶层段落，表格内的段落不在这个列表里，需要单独遍历表格。明明文档里有一段话，getParagraphs()里却找不到，它藏在表格单元格里。农业文档里表格密度高，这个坑踩中的人非常多，我一开始做检测报告解析时就吃过亏，漏掉了一整段“检测依据”文本。

3.3 段落样式名、大纲级别与直接格式

要判断一个段落是不是标题，有三个线索。

第一，样式ID。para.getStyleID()返回样式ID，比如"Heading1"、"1"。如果文档用的内置标题样式，样式ID可以直接判断。不过POI不同小版本的这个API实现略有差异，我习惯从XML层面直接取值，最可靠：

private String getStyleId(XWPFParagraph para) { if (para.getCTP().getPPr() != null && para.getCTP().getPPr().isSetPStyle()) { return para.getCTP().getPPr().getPStyle().getVal(); } return null; }

第二，大纲级别w:outlineLvl是更可靠的信号。Word的“标题1”样式默认绑定了大纲级别0，但用户可能修改过样式定义，或者直接在“正文”样式上手动设置了大纲级别。所以判断标题别只认样式名，要两者结合：

private int getOutlineLevel(XWPFParagraph para) { if (para.getCTP().getPPr() != null && para.getCTP().getPPr().getOutlineLvl() != null) { return para.getCTP().getPPr().getOutlineLvl().getVal().intValue(); } return -1; }

第三，如果既没有样式名也没有大纲级别，就只能靠启发式规则：字体大于正文、加粗、居中。这个规则容易误判，我只作为兜底，不推荐作为主要判断依据。

字体和格式信息的提取要从run层面取。同一个段落里可能有多个run，每个run的格式都不同。比如“农产品质量检测”中加粗只作用于部分文字。遍历run的代码：

for (XWPFRun run : para.getRuns()) { String text = run.getText(0); if (text == null || text.isBlank()) continue; boolean bold = run.isBold(); double fontSize = run.getFontSizeAsDouble(); String color = run.getColor(); System.out.println(text + " bold=" + bold + " size=" + fontSize + " color=" + color); }

3.4 中文字体读取：别被getFontName误导

这里是农业系统中文字档最常见的一个坑。run.getFontName()默认返回的是ASCII字体（w:rFonts的ascii属性），对中文内容来说，真正起作用的是东亚字体属性（w:rFonts的eastAsia属性）。

private String getEastAsiaFont(XWPFRun run) { if (run.getCTR().getRPr() != null && run.getCTR().getRPr().getRFonts() != null) { return run.getCTR().getRPr().getRFonts().getEastAsia(); } return null; }

我在做申报书格式校验时，遇到过一份材料中文是宋体、数字和英文是Times New Roman，用getFontName()读出来是Times New Roman，一对比字体模板就判定“字体不符”，导致大量误报。改成同时读取ascii和eastAsia两个属性后，误报率才降下来。这个细节常规文档里很少写，但做中文文档解析一定会碰到。

3.5 构建标题树

把段落解析完，下一步是按大纲级别构建标题树。这一层就涉及业务逻辑了。我通常解析成如下结构：

public class HeadingNode { private int level; private String title; private int startPage; private List<HeadingNode> children; }

构建时维护一个栈，当遇到大纲级别比栈顶小的节点就出栈，再挂到父节点下。这样得到的标题树就是申报书在线目录的数据源，也是文档结构对比的基础。在农业政策库里，我还会把标题树和正文内容一起转成Markdown，做全文检索时按标题级别加权，效果比纯关键词搜索好很多。

4. 表格与图片：农业文档解析里的大头

文档里表格的重要性前面讲过了。这一节说具体实现和几个常见坑。

4.1 遍历表格和行列

基础遍历代码：

for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { String cellText = cell.getText(); } } }

这里的难点是合并单元格。Word表格的合并有两种：水平合并（gridSpan）和垂直合并（vMerge），都定义在单元格的tcPr里。水平合并的判断：

private boolean isHorizontalMerged(XWPFTableCell cell) { if (cell.getCTTc().getTcPr() != null && cell.getCTTc().getTcPr().isSetGridSpan()) { return cell.getCTTc().getTcPr().getGridSpan().getVal() > 1; } return false; }

垂直合并的处理稍微复杂。Word中垂直合并的首行标记vMerge为restart，后续行标记为continue。如果只是读取文本，continue行通常没有内容；如果要重建表格结构，你要把continue行的语义合并到首行单元格上。农业检测报告的表格经常有跨行合并的“样品编号”列，处理不好就会在每一行数据里都插入一个空值字段。

农业检测报告的表格还有另一个特点：表头经常跨页重复。Word通过tblHeader属性标记重复表头，POI读取时要注意判断当前行是表头还是数据行，否则同一批数据的表头会被当成一条记录入库。

4.2 表头识别：样式解析解决不了的，用文本规则补

样式解析能告诉你“这一行加粗、底色更深”，但不能直接告诉你“这是表头”。我见过团队在表头识别上死磕算法，效果都不好。这是农业系统文档解析里一个真实的心得：不要试图用纯排版规则解决所有语义问题。

实践中我会把表头识别拆成三层策略。第一层是结构特征：第一行、有合并单元格、背景色填充，这些是表头的常见信号。第二层是关键词语料库：“序号”“项目名称”“检测依据”“限量值”“实测值”“结论”这类农业检测报告的高频表头词，维护进词典。第三层是历史规则：如果同一检测机构的报告格式稳定，可以缓存该机构的表头模板，下次按模板套用。

这三层策略组合使用，识别准确率能到95%以上。注意，这几层是递进关系，不是并列关系，能命中结构特征就直接判定，判定不了再走词典。

4.3 图片抽取与关联

农业检测报告里的图谱、遥感图、现场照片，对追溯场景很重要。POI支持两种取图方式：全文档取图，或按run位置取图。

// 方式一：取全部图片 for (XWPFPictureData pic : doc.getAllPictures()) { byte[] data = pic.getData(); String ext = pic.suggestFileExtension(); } // 方式二：按段落、按run定位取图 for (XWPFRun run : para.getRuns()) { for (XWPFPicture pic : run.getEmbeddedPictures()) { XWPFPictureData data = pic.getPictureData(); // 可以拿到图片在文档中的位置，方便和段落关联 } }

方式二对农业场景更实用，因为图片必须和它所属的检测项目、样品记录关联起来，不能无脑塞进图片堆。比如一份检测报告里既有质谱图又有现场采样照片，如果只用方式一，图片顺序和所属项目根本对不上，下游做报告追溯时就是一团乱麻。

4.4 公式处理：OMML转LaTeX并不神秘

农业标准文件、化肥配方文档里偶尔会出现公式和特殊符号。Word公式默认是OMML格式，POI对它的读取不是直接的，最简单的方案是分两步：第一步，用XSLT把OMML转成MathML，POI工具包里有一个OMML2MML.XSL样式表，网上也能找到社区的加强版；第二步，再把MathML转成LaTeX或直接转成图片。Java侧可以用JLaTeXMath把MathML转成可渲染的LaTeX，或解析成Office的OMML再渲染。

这一块我建议不要过度投入。真实农业文档里公式占比很低，真正高频的是上下标、特殊单位，这些用普通run的字体格式（vertAlign、superscript）就能读取。只有科研型文档才需要完整的OMML处理链路。我在项目里只对“限量值”“单位”这类字段做了上下标识别，公式渲染至今还没有一个农业客户提过强需求。

5. 集成到Spring Boot农业服务：从解析组件到业务链路

解析能力有了，还要把它和业务系统真正串起来。这一节讲我在项目里的集成方式。

5.1 文件上传与类型校验

接口层面要做的第一件事是区分docx和doc。docx的magic number是PK（zip），doc是OLE复合文档（D0 CF 11 E0）。不要只看扩展名，因为用户会把doc直接改名为docx，导致解析报错。用文件头判断更可靠：

private boolean isDocx(byte[] head) { return head.length > 4 && (head[0] & 0xFF) == 0x50 && (head[1] & 0xFF) == 0x4B; }

识别到老版doc时，我现在的处理方式是直接提示用户转成docx再上传，或者由后台调用转换服务。很多农业系统的用户是基层人员，文档由Word或WPS生成，确实存在大量.doc；与其在解析端弥补，不如在入口把格式统一。这不算偷懒，而是把有限的开发资源用在更有价值的业务解析上。

5.2 解析任务异步化

解析Word是CPU密集操作，几十页的文档加一堆图片，单线程跑一次可能好几秒，用户批量上传时直接把Web请求阻塞很不划算。我用Spring的@Async把解析任务放到线程池里，前端轮询获取解析状态：

@Async("wordParseExecutor") public CompletableFuture<ParseResult> parseAsync(MultipartFile file) { ParseResult result = wordParseService.parse(file); return CompletableFuture.completedFuture(result); }

线程池大小不要用默认值。我一般配置为核心线程数等于CPU核数，最大不超过8，因为POI解析时内存占用很高，开太多线程容易把应用打挂。队列用有界队列，超出就拒绝并提示用户稍后再试。这个策略让我在政务云的低配机器上也能扛住几十个文件同时上传。

5.3 输出结构化数据，对接下游

解析结果统一成如下模型：

public class ParseResult { private List<HeadingNode> headings; private List<ParagraphInfo> paragraphs; private List<TableInfo> tables; private List<ImageInfo> images; }

拿到这个结果后，下游是自由的。可以转成JSON存到对象存储，供前端在线预览；可以转成Markdown入库，作为知识库检索的语料；可以交给大模型接口，按用户提供的字段定义从表格里抽取实体信息；也可以做格式合规校验，比对标题数、章节顺序、字体字号。

在农业项目申报场景里，我还会把解析产生的标题树和表格结果存成一份“文档指纹”。下次相同模板的申报书来了，直接和指纹比对，格式差异一目了然。这套思路对申报材料初审非常有效，可以自动标出“缺少第三章”“表头格式不对”等问题。

6. 实战中的坑：zip损坏、WPS样式名与内存失控

最后这部分是我最想分享的，也是各个技术社区里提问最多的地方。有些坑不踩一遍真不知道。

6.1 “修改数据后无法打开生成的docx”是zip包坏了

很多人遇到生成或修改后的docx打不开，第一反应是POI写坏了XML。我在实践中发现，绝大多数原因是docx这个zip包本身不完整。最常见的情况是：多线程同时写同一个XWPFDocument对象，或者写出时OutputStream没有关闭。

docx本质是zip包，POI写入时会边写边更新zip条目，如果中途抛异常、流没有flush，就会生成一个部分写入的包。Word打开时会提示“文件已损坏”。解决办法有三条：一是每次解析和写出的对象都独立创建，绝不共享；二是写出方法用try-with-resources保证流关闭；三是写入后重新打开校验一次，确认能正常读取再给用户下载。最后一条最有效，我把它做成了一个内置的自我检查步骤，解析结果不通过校验就直接返回失败，避免用户拿到坏文件。

6.2 表格列宽读不准

很多人问POI设置Word表格单元格宽度相关的问题。这里对应的坑是：Word里看到的表格列宽和XML里的值经常对不上。因为列宽存储在三个地方：表的tblGrid的gridCol、每个单元格的tcW、以及表格属性的tblW，解析时优先级和单位换算容易出错。

POI对单位有一个处理逻辑：tcW的type属性可能是dxa（twips，1英寸等于1440twips）、auto或pct（百分比）。读取时你要看type，而不是直接拿数值。我写过一个转换工具，把所有单位统一转成像素或毫米，这个工具是所有表格解析逻辑的基础。列宽解析不准，下游做报告打印、网页预览时表格就会挤成一团。

6.3 WPS文档的样式名是个大坑

国产环境里WPS生成的docx非常多，而WPS对样式名的写法不完全和微软一致。常见的有：样式名是“标题 1”（带空格）而不是“Heading 1”，段落样式ID写成了“1”而不是“heading1”，大纲级别缺失但字体又大又粗。所以我在解析标题时，规则是“样式ID优先，大纲级别辅助，外观特征兜底”，并且维护一个样式名映射表：

Map<String, Integer> styleMap = Map.of( "heading 1", 1, "标题 1", 1, "标题1", 1, "heading 2", 2, "标题 2", 2, "标题2", 2 );

样式名映射表一定要做成配置化的，放在数据库或配置文件里，不要写死在代码中。因为不同单位可能用不同的模板，比如有的单位喜欢用“一、”“（一）”这种大纲编号来代替Word样式，这种情况就要靠文本正则辅助识别层级。

6.4 内存控制和性能优化

解析大文档时，POI的XWPFDocument会把整个document.xml的DOM树加载进内存，一个50页带图的文档吃几百MB内存是常有的事。内网服务器配置通常不高，批量解析时很容易OOM。

我现在用几个偏方来控制：上传前限制文件大小（单文档不超过50MB）；解析在独立线程池里跑，便于隔离；解析完成的document对象及时关闭输入流、把对象引用置空，交给GC处理；如果只是需要对拍某几段内容，可以用POI的只读流式方式，不加载全部图片到内存。这些做法不一定优雅，但在生产环境里确实能让服务稳定不少。

6.5 别把样式解析和语义抽取混为一谈

这是给新手最后的一个提醒。样式解析组件解决的是“文档长什么样”，语义抽取解决的是“文档在说什么”（比如把检测结论抽成结构化字段）。这两件事可以串成一条流水线，但不要指望一个组件全干完。

农业文档里，语义抽取的准确率短板往往在表格合并、跨页、表头重复这些结构问题上，所以先把样式和表格结构做扎实，语义抽取才会省心。在我做过的检测报告解析里，只要表格合并和表头识别这一步稳定了，后面用规则匹配或大模型抽字段都顺畅得多；反过来，结构都拆错了，后面的模型再强也是白搭。

我自己的体会是，集成Word样式解析组件要稳扎稳打。第一步先拿十份真实的业务文档做测试，把样式名映射、合并单元格、表头识别这些基础规则调对，比急着上大模型要实在得多。最后分享一个小技巧：解析组件跑通后，把样式映射表和表头词典做成可维护的配置界面，试点单位换了文档模板，改配置就能适配，完全不用动代码。这套组件在我们几个农业项目里从申报书解析扩展到检测报告抽取，一直很稳，核心逻辑几乎没有改过。