简介面向需要把办公文档数据自动导入业务系统的Java开发者这份素材包聚焦Word文档解析与数据库写入的完整实现路径借助Apache POI读取docx正文与表格内容经类型转换后通过JDBC与PreparedStatement批量入库并覆盖异常捕获、事务管理与多文件并行处理等工程细节适合具备Java基础、正在处理数据录入自动化的初中级开发者参考。压缩包共41个文件、约13.24MB以11个依赖jar、9个java源码与9个class编译产物为主体配合2个xml配置、2个properties数据库连接参数及Eclipse工程配置项构成可直接导入IDE运行的示例工程结构同包还附带Excel读取相关内容便于横向对照两种Office格式的解析差异。已有5138人学习读者可获得可调试的读取、转换、入库链路代码与依赖清单、工程配置模板并据此理解解析层与持久层的衔接方式快速改造为自身项目的导入模块。1. Java 读取 Word 并入库一个“上传按钮”背后的四层工程后台管理系统里加一个上传 Word 的功能看起来只需要一个MultipartFile参数实际项目里真正麻烦的地方在解析层和存储层。常见需求是用户上传.doc或.docx系统读出正文、标题、段落、表格做校验后把内容连同元信息写进数据库。新手容易卡在依赖版本和文件流处理有经验的人则更关心格式兼容、大文件内存占用和入库字段怎么设计。这篇用一份完整的 Java 示例把链路拆开从 Apache POI 选型讲到入库事务边界能直接照着复现。2. 选型与解析原理POI、流式读取和文档模型2.1 为什么 Word 读取首选 POI而不是转换工具Java 生态里读写 Office 文档绕不开 Apache POI。XWPF负责.docxOOXMLHWPF负责.docOLE2 二进制。有人图省事先用 LibreOffice 或某些转换服务转成纯文本再解析这在测试环境能跑上线后问题集中爆发转换进程需要额外部署、并发低、字体缺失会导致内容错乱还有安全审计风险。POI 是纯 Java 库不用外部进程字段级控制力强段落、表格、样式都能取到。必须先认清一个事实.doc和.docx是两种完全不同的格式不是改后缀的关系。.docx本质是 zip 包加 XMLPOI 的XWPFDocument基于 XML 模型能力成熟.doc是 OLE2 复合文档HWPFDocument只覆盖读取场景的一部分复杂嵌套对象容易抛异常而且 HWPF 写回能力很弱。所以工程上常见的做法是.docx走完整解析.doc只做有限的文本提取或者明确要求上传时转存.docx。依赖上要成组引入版本必须一致。下面这份是常用的 Maven 组合poi-ooxml会自动带上poi和poi-ooxml-lite但很多老项目踩坑就踩在只引入了poi结果XWPFDocument找不到类。properties poi.version5.2.5/poi.version /properties dependencies !-- .docx 解析核心必须同时引入 -- dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version${poi.version}/version /dependency !-- 大文件流式读取避免整份文档进内存 -- dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version${poi.version}/version classifiertests/classifier scopetest/scope /dependency dependency groupIdorg.apache.xmlbeans/groupId artifactIdxmlbeans/artifactId version5.2.0/version /dependency /dependencies提示POI 5.x 需要 JDK 8 以上且内部依赖log4j-api与commons-compress。如果你的项目里存在旧版xmlbeans2.x启动时会报NoSuchMethodError这是版本冲突最常见的一种表现用mvn dependency:tree排掉旧版本即可。2.2 文档对象模型和可提取的内容粒度XWPFDocument暴露的模型自上而下分四层文档 → 正文document body→ 段落 / 表格 → 段落内的 run。run 是格式一致的最小文本单位粗体、斜体、不同字号都会切一个 run。这也解释了为什么直接拿getText()有时字符串中间会出现奇怪的拼接——多 run 拼接是正常的但如果你要做富文本渲染就得遍历 run 而不是取整段文本。可提取的粒度大致如下内容类型提取方式典型用途正文纯文本paragraph.getText()全文检索、摘要段落样式paragraph.getStyle()判断标题层级表格单元格table.getRow(i).getCell(j).getText()结构化数据导入页眉页脚document.getHeaderArray()合同编号、公司名内嵌图片paragraph.getRuns()里的 picture附件转存工程上通常不追求“把 Word 完整还原成 HTML”那是一类独立需求成本很高。多数入库场景只需要“标题 正文纯文本 表格结构 基础元信息文件名、大小、段落数、上传时间”。把提取范围先限定死后面的表结构和事务设计才能稳定。2.3 大文件场景XWPF 与“事件模型”该怎么选XWPFDocument会把整份文档的 XML 树加载进内存。经验阈值是这样的几 MB、几百页以内的文档完全没问题一旦超过 50MB 或者并发几十个上传堆内存会明显吃紧严重时 OOM。这时应该换成XWPFWordExtractor配合流式读取或者用opc包下的OPCPackage打开后按需读取。另一种是 POI 的事件模型XSSF 那一套流式接口Word 侧对应XWPFDocument之外的读取方式API 更绕只在确实需要处理超大文档时才值得投入。平时我一般会加一个前置门槛文件大小上限 20MB、扩展名白名单.docx/.doc、解析前后各打一次耗时日志。超过阈值的文件直接拒掉并提示用户拆分这比在解析过程中做各种兜底要省事得多。真正要处理超大文档就单独开一条异步解析链路不放在同步上传接口里。3. 从上传到入库接口、解析与持久化实现3.1 接口层上传参数校验先于解析很多线上故障不是解析写错而是校验放得太晚。文件类型如果单纯看后缀很容易被改名的文件绕过。比较稳的做法是后缀 MIME 双校验再结合 POI 打开时的异常兜底。下面的 Controller 代码用 Spring Boot 风格入参是MultipartFile校验失败按统一响应返回。RestController RequestMapping(/api/doc) public class WordUploadController { private final WordParseService wordParseService; public WordUploadController(WordParseService wordParseService) { this.wordParseService wordParseService; } PostMapping(/upload) public ResultLong upload(RequestParam(file) MultipartFile file) { // 1. 空文件快速失败 if (file null || file.isEmpty()) { return Result.fail(文件为空); } // 2. 后缀白名单 String name Objects.requireNonNull(file.getOriginalFilename()); String lower name.toLowerCase(Locale.ROOT); if (!lower.endsWith(.docx) !lower.endsWith(.doc)) { return Result.fail(仅支持 .doc/.docx); } // 3. 大小上限 20MB避免整份文档进堆 if (file.getSize() 20L * 1024 * 1024) { return Result.fail(文件超过 20MB请拆分后再传); } // 4. 进入解析与入库异常统一在 service 内包装 Long docId wordParseService.parseAndSave(file); return Result.ok(docId); } }这里的关键逻辑是“先挡后解”空文件、后缀、大小三项都在 Controller 里拦掉不进解析逻辑。getOriginalFilename()在个别容器里可能返回 null所以要判空。大小限制用字节数写死而不是靠配置中心是为了让这条链路的边界足够确定需要调整时改这一处即可。参数说明MultipartFile.getSize()返回字节数20MB 的阈值适合一般管理系统lower转换后判断避免.DOCX这类大写后缀被误拒。这里不校验 MIME是因为不同浏览器对.doc的 MIME 不一致application/msword和application/octet-stream都常见强校验反而误伤真正的兜底放在解析层的异常捕获上。3.2 解析层.docx 与 .doc 分开处理解析服务要解决两个问题按扩展名走不同 API以及把段落和表格抽成统一结构。下面的实现返回一个ParsedDoc包含标题、纯文本、段落列表和表格数量入库时按这个结构落库。Service public class WordParseService { public ParsedDoc parse(InputStream in, String filename) throws IOException { String lower filename.toLowerCase(Locale.ROOT); if (lower.endsWith(.docx)) { // .docxXWPF 完整解析 try (XWPFDocument doc new XWPFDocument(in)) { return parseDocx(doc); } } // .docHWPF 只做文本提取结构能力有限 try (HWPFDocument doc new HWPFDocument(in)) { String text doc.getText().toString(); ParsedDoc r new ParsedDoc(); r.setTitle(filename); r.setPlainText(text); r.setParagraphCount(0); // .doc 不保证段落信息 return r; } } private ParsedDoc parseDocx(XWPFDocument doc) { ListString paragraphs new ArrayList(); StringBuilder plain new StringBuilder(); String title null; for (XWPFParagraph p : doc.getParagraphs()) { String t p.getText(); // 用样式名识别一级标题常见样式是 Heading1 if (title null p.getStyle() ! null p.getStyle().toLowerCase().startsWith(heading1)) { title t; } if (t ! null !t.isBlank()) { paragraphs.add(t.trim()); plain.append(t.trim()).append(\n); } } ParsedDoc r new ParsedDoc(); r.setTitle(title null ? 未命名文档 : title); r.setPlainText(plain.toString()); r.setParagraphs(paragraphs); r.setParagraphCount(paragraphs.size()); r.setTableCount(doc.getTables().size()); return r; } }逻辑说明.docx用XWPFDocument打开后遍历getParagraphs()空段落直接过滤避免正文里出现大量空行。标题识别靠样式名而不是“第一个非空段落”因为很多文档开头是封面信息。getStyle()可能返回 null必须先判断。.doc分支用HWPFDocument.getText()拿全量文本明确不承诺段落粒度这比强行解析后抛异常要诚实。参数上要注意几个点XWPFDocument和HWPFDocument都实现了Closeable必须 try-with-resources否则文件句柄泄漏在高并发下会很快耗尽InputStream由调用方管理解析层不要关闭它两次tableCount只统计顶层表格嵌套表格需要用getTables()的单元格内表格再递归一般入库场景不要求这个粒度。3.3 持久化表结构和事务边界怎么定入库设计有两派一派把整份纯文本塞进一个CLOB字段另一派把段落拆成子表。前者简单适合全文检索以外的一般展示后者能做段落级定位和编辑但表量和写入成本都高。我一般选混合方案主表存文档元信息和纯文本子表存段落表格只存数量摘要需要时再延迟解析。CREATE TABLE doc_main ( id BIGINT PRIMARY KEY AUTO_INCREMENT, file_name VARCHAR(255) NOT NULL, file_size BIGINT NOT NULL, title VARCHAR(300), plain_text LONGTEXT, paragraph_cnt INT DEFAULT 0, table_cnt INT DEFAULT 0, create_time DATETIME DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE doc_paragraph ( id BIGINT PRIMARY KEY AUTO_INCREMENT, doc_id BIGINT NOT NULL, seq INT NOT NULL, content TEXT, KEY idx_doc_seq (doc_id, seq) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;注意字符集必须用utf8mb4。Word 里常见的方块符号、特殊标点、表情符号在utf8三字节编码下会直接报错这个坑几乎每个项目都要踩一次。事务上要把“插主表 批量插段落”包在同一个事务里。段落数量可能上千逐条插入会明显拖慢用 MyBatis 的foreach批量或在 JDBC 里addBatch。批大小经验值是 500 条一提交太大反而增加回滚开销。入库完成后返回主表 id前端跳转到详情页整个链路就闭合了。4. 踩坑与排查这几类故障占了大半4.1 现象解析报OfficeXmlFileException原因是伪装成 docx 的 doc现象很典型前端把.doc文件改名成.docx上传后端按后缀走XWPFDocument抛The supplied data appears to be in the OLE2 Format。原因就是扩展名不可信OOXML 和 OLE2 的魔数头完全不同。解决方式是解析前读前 8 个字节判断格式或者直接 try-catch 这个异常后回退到HWPFDocument。我一般是在 service 里做一次回退日志里记一条“后缀与实际格式不符”顺便统计这类文件的比例。4.2 现象生产环境偶发 OOM原因是整份文档和并发上传叠加现象是上线一段时间后堆内存持续上涨full GC 后不回落dump 出来全是XWPFDocument相关的 XML 对象。原因是单份文档全量加载加上上传接口是同步的并发一高内存就顶不住。解决分三步接口层加上大小上限和并发限流解析后立刻关闭文档对象如果业务确实需要处理大文件改成先落临时文件、异步解析接口只返回任务 id。临时文件用完必须删否则磁盘也会被慢慢吃掉。4.3 现象中文乱码或特殊字符插入失败原因是连接与字符集不一致现象是入库后详情页显示问号或者插入时报Incorrect string value。原因通常有两层数据库或表用了utf8而不是utf8mb4JDBC URL 没带characterEncodingutf8。解决顺序是先改表字符集和字段再检查连接串最后确认解析时没有用错编码读取流。这三步里漏掉任何一步都会继续乱码排查时按从存储到读取的顺序逐一确认。4.4 现象依赖冲突导致启动失败原因是 POI 与旧版 xmlbeans 并存现象是应用启动或首次解析时抛NoSuchMethodError、NoClassDefFoundError堆栈指向org.apache.xmlbeans或org.apache.commons.compress。原因是项目里其他组件传递依赖了旧版本。解决办法是mvn dependency:tree -Dincludesorg.apache.xmlbeans定位来源用exclusion排掉旧版本并在dependencyManagement里锁定 POI 官方对应的版本。血泪经验是POI 升级不要只升一个包poi、poi-ooxml、xmlbeans、commons-compress要一起看。4.5 现象表格内容丢失原因是只取了段落没遍历表格现象是纯文本里表格数据完全不见用户反馈“导入后表格没了”。原因是getParagraphs()只返回正文段落表格是getTables()单独的对象二者不重叠。解决是按文档 body 的顺序遍历先处理段落再处理表格或者用bodyElements按真实顺序取。如果需要表格结构入库就单独建一张明细表把行、列、单元格值序列化存 JSON比强行拍平成文本更可靠。5. 进阶技巧把解析做成可验证、可回滚的链路上面几步跑通之后真正决定这套东西能不能长期用的是“出问题时能不能快速定位”。我在项目里一般会加三层可验证手段。第一层是解析结果的摘要日志文件名、大小、段落数、表格数、纯文本长度、解析耗时五个字段打一行出问题先看这一行就能判断是解析失败还是入库失败。第二层是入库前的内容指纹对纯文本做一次 MD5主表存这个字段重复上传同一份文档时可以直接命中避免重复解析和重复入库。public String fingerprint(String plainText) { try { MessageDigest md MessageDigest.getInstance(MD5); byte[] digest md.digest(plainText.getBytes(StandardCharsets.UTF_8)); StringBuilder sb new StringBuilder(); for (byte b : digest) { sb.append(String.format(%02x, b)); } return sb.toString(); } catch (NoSuchAlgorithmException e) { throw new IllegalStateException(MD5 不可用, e); } }这段代码没什么花哨的地方但用处很大指纹相同直接返回已有 id前端体验是“秒传”后端省掉一次解析。注意指纹只对纯文本计算不包含文件名和上传时间否则永远对不上。如果业务要求同一份内容允许不同标题就在指纹里拼上标题再算。第三层是失败回滚。解析和入库放在同一个事务里还不够因为文件本身可能已经写到了临时目录或对象存储。我的习惯是解析阶段完全不碰持久化存储只产出ParsedDoc对象入库成功后才把原始文件转存转存失败就补偿删除主表记录。这个顺序能保证“数据库里有记录但文件没了”这种脏数据不会出现。还有一个容易被忽略的点是线程安全。XWPFDocument不是线程安全的绝对不能做成单例复用或者放进缓存。每次请求新建、用完关闭这是最稳的用法。如果确实要做解析结果缓存缓存的是ParsedDoc这种纯数据对象不是文档对象本身。验证方法上我一般准备一个小型回归集一份带标题的正常文档、一份只有表格的文档、一份.doc老格式、一份改名的伪.docx、一份 15MB 左右的大文件。这五份跑一遍基本能覆盖八成线上问题。每次改解析逻辑或升 POI 版本这五份都要过一遍。从那以后我每次动 Word 解析相关代码都强制先把这份回归集跑完再提交比事后翻日志省太多时间。希望帮到你。本文还有配套的精品资源点击获取