簡介面向需要把Word文檔數(shù)據(jù)自動(dòng)錄入數(shù)據(jù)庫的Java開發(fā)者與學(xué)習(xí)者這份項(xiàng)目示例圍繞Apache POI解析.docx文本與表格、JDBC連接數(shù)據(jù)庫并批量寫入展開覆蓋數(shù)據(jù)轉(zhuǎn)換、異常處理、事務(wù)一致性和多文件并行處理等常見工程要點(diǎn)適合作為企業(yè)數(shù)據(jù)錄入、表單歸檔類功能的參考實(shí)現(xiàn)。壓縮包共41個(gè)文件、約13.24MB包含11個(gè)jar依賴、9個(gè)java源文件與9個(gè)class編譯文件另有xml、properties等配置及Eclipse項(xiàng)目描述文件便于直接導(dǎo)入對照源碼與運(yùn)行結(jié)構(gòu)。已有5138人學(xué)習(xí)下載。讀者可從中獲得可運(yùn)行的POI讀取表格、字段映射、PreparedStatement批量插入示例以及連接配置和編譯產(chǎn)物幫助快速搭建Word到數(shù)據(jù)庫的處理鏈路并借鑒異常與事務(wù)處理思路減少排錯(cuò)成本。1. 從一份 Word 到一張表Java 讀取上傳鏈路到底卡在哪某后臺的合同臺賬要支持運(yùn)營上傳 Word解析后按段落和表格行入庫還要能按關(guān)鍵詞檢索。很多人把 Java 讀取 Word 文件并上傳數(shù)據(jù)庫想成 MultipartFile 接住、POI 讀文本、insert 三條語句真跑起來先翻車在 .doc 與 .docx 分叉再卡在合并單元格和中文亂碼。這個(gè)源碼包把上傳、解析、結(jié)構(gòu)化、入庫、回讀校驗(yàn)串成一條能落地的鏈路適合做文檔導(dǎo)入、合同臺賬、報(bào)表采集的后端。它不是 OCR掃描件和純圖片 Word 讀不出內(nèi)容也不是低代碼平臺字段映射仍要按業(yè)務(wù)表改。新手能順著接口和表結(jié)構(gòu)跑通熟手重點(diǎn)看解析器邊界、批量插入和冪等設(shè)計(jì)。2. 選型先定邊界POI、docx4j 還是先轉(zhuǎn) PDF 再抽文本2.1 為什么大多數(shù)后臺系統(tǒng)選 Apache POIWord 導(dǎo)入這類需求選型先看兩件事要不要保留表格結(jié)構(gòu)要不要兼容老 .doc。把 Word 先轉(zhuǎn) PDF 再抽文本看起來省事實(shí)際把段落、表格行列、單元格坐標(biāo)全丟了后面做字段映射只能靠正則猜。docx4j 功能全但 JAXB 依賴和 API 心智負(fù)擔(dān)不低小團(tuán)隊(duì)維護(hù)成本高。常見做法是 Apache POI 打底docx 用 XWPF老 doc 用 HWPF圖片和表格都能拿到結(jié)構(gòu)。我一般會把依賴拆成兩個(gè)poi-ooxml負(fù)責(zé) .docxpoi-scratchpad負(fù)責(zé) .doc。版本不要散落在各個(gè)模塊統(tǒng)一放父 POM 的dependencyManagement避免 poi 和 poi-ooxml 版本錯(cuò)位導(dǎo)致NoSuchMethodError。dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version${poi.version}/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-scratchpad/artifactId version${poi.version}/version /dependency${poi.version}由項(xiàng)目依賴管理統(tǒng)一鎖定不要在這個(gè)片段里寫死。poi-ooxml會傳遞引入poi與xmlbeans如果項(xiàng)目里已經(jīng)有舊版xmlbeans先用mvn dependency:tree排掉沖突。poi-scratchpad只在需要讀 .doc 時(shí)加不讀老格式可以省掉。選 POI 的理由不是它“最強(qiáng)”而是邊界清楚段落是段落表格是表格讀不到就拋異常不會悄悄降級成一段純文本。對入庫場景結(jié)構(gòu)丟失比解析失敗更可怕失敗還能重試結(jié)構(gòu)錯(cuò)了要洗數(shù)據(jù)。2.2 .doc 與 .docx 的解析分叉XWPF 和 HWPF 不要混用.docx本質(zhì)是 zip 包里的 XMLXWPFDocument 能直接按段落、表格、頁眉頁腳讀。.doc是二進(jìn)制復(fù)合文檔HWPF 只能覆蓋一部分格式遇到復(fù)雜表格、文本框、域代碼讀出來缺行少列很常見。實(shí)際項(xiàng)目里我一般把 .doc 當(dāng)降級通道能讀文本和簡單表格就入庫讀不了就提示用戶另存為 .docx不做無限兼容。統(tǒng)一入口先按后綴分叉再交給兩個(gè)解析器不要讓 Service 里出現(xiàn)instanceof XWPFDocument。public DocumentDTO parse(MultipartFile file) throws IOException { String original Optional.ofNullable(file.getOriginalFilename()).orElse(); String lower original.toLowerCase(Locale.ROOT); if (lower.endsWith(.docx)) { return parseDocx(file.getInputStream()); } if (lower.endsWith(.doc)) { return parseDoc(file.getInputStream()); } throw new IllegalArgumentException(only .doc and .docx are supported); } private DocumentDTO parseDocx(InputStream in) throws IOException { try (XWPFDocument doc new XWPFDocument(in)) { return DocxReader.read(doc); } } private DocumentDTO parseDoc(InputStream in) throws IOException { try (HWPFDocument doc new HWPFDocument(in)) { return DocReader.read(doc); } }這段代碼的關(guān)鍵在try-with-resourcesXWPFDocument 和 HWPFDocument 都持有底層流忘記關(guān)會在批量導(dǎo)入時(shí)把文件句柄耗光。parseDocx和parseDoc返回同一個(gè)DocumentDTO上層不感知 POI 類型。后綴判斷用toLowerCase(Locale.ROOT)避免土耳其語環(huán)境下的I/i問題這種小坑在容器里排查很費(fèi)時(shí)間。2.3 把“讀取”拆成段落、表格、圖片三條管線Word 入庫最怕一鍋燉。段落、表格、圖片的生命周期不一樣段落要保留順序和樣式表格要保留行列坐標(biāo)圖片一般只存路徑或文件 ID不把二進(jìn)制塞進(jìn)業(yè)務(wù)表。解析器里拆成三條管線DTO 里各放各的集合后面入庫按表拆。public final class DocxReader { public static DocumentDTO read(XWPFDocument doc) { DocumentDTO dto new DocumentDTO(); ListParagraphDTO paragraphs new ArrayList(); for (int i 0; i doc.getParagraphs().size(); i) { XWPFParagraph p doc.getParagraphs().get(i); ParagraphDTO pd new ParagraphDTO(); pd.setIndex(i); pd.setText(p.getText()); pd.setStyle(p.getStyle()); paragraphs.add(pd); } dto.setParagraphs(paragraphs); ListTableDTO tables new ArrayList(); for (int t 0; t doc.getTables().size(); t) { XWPFTable table doc.getTables().get(t); TableDTO td new TableDTO(); td.setTableIndex(t); ListListString rows new ArrayList(); for (XWPFTableRow row : table.getRows()) { ListString cells new ArrayList(); for (XWPFTableCell cell : row.getTableCells()) { cells.add(cell.getText()); } rows.add(cells); } td.setRows(rows); tables.add(td); } dto.setTables(tables); return dto; } }doc.getParagraphs()只拿頂層段落表格單元格里的段落不會出現(xiàn)在這里這是很多人統(tǒng)計(jì)段落數(shù)對不上的原因。表格行用getTableCells()拿物理單元格合并列會少列后面入庫前要按最大列數(shù)補(bǔ)齊。cell.getText()只拿文本單元格里的換行、制表符會被壓平需要保留格式就繼續(xù)讀cell.getParagraphs()。圖片管線不在這個(gè)骨架里展開常見做法是遍歷doc.getAllPictures()存到文件服務(wù)業(yè)務(wù)表只留media_id和順序號。3. 上傳接口與解析服務(wù)從 MultipartFile 到結(jié)構(gòu)化文檔對象3.1 控制器只做三件事校驗(yàn)后綴、限流大小、轉(zhuǎn)交解析上傳接口最容易被寫成萬能入口接文件、解析、入庫、返回結(jié)果全在 Controller 里。后面加異步、加冪等、加回讀校驗(yàn)改一處崩三處。我一般讓 Controller 只做三件事判空和后綴、卡文件大小、把 MultipartFile 交給導(dǎo)入服務(wù)。業(yè)務(wù)異常統(tǒng)一拋返回體只帶docId、段落數(shù)、表格數(shù)和耗時(shí)方便前端提示和排查。PostMapping(/api/docs/import) public ImportResult importDoc(RequestParam(file) MultipartFile file) { if (file null || file.isEmpty()) { throw new BizException(EMPTY_FILE); } String name Optional.ofNullable(file.getOriginalFilename()).orElse(); String lower name.toLowerCase(Locale.ROOT); if (!lower.endsWith(.doc) !lower.endsWith(.docx)) { throw new BizException(ONLY_DOC_OR_DOCX); } if (file.getSize() 20L * 1024 * 1024) { throw new BizException(FILE_TOO_LARGE); } return importService.importOne(file); }RequestParam(file)要和前端表單字段名一致不一致會直接 400不是解析失敗。20MB 是業(yè)務(wù)側(cè)兜底Spring 的spring.servlet.multipart.max-file-size和max-request-size也要同步設(shè)兩個(gè)地方一個(gè)放寬一個(gè)收緊最后表現(xiàn)就是“偶爾能傳偶爾不能”。后綴校驗(yàn)只防誤傳不防偽造真正解析時(shí) POI 拋異常再兜一層。3.2 解析器返回統(tǒng)一 DTO別把 XWPFDocument 泄漏到 ServiceDTO 要按入庫表設(shè)計(jì)不要按 POI 的類設(shè)計(jì)。段落 DTO 至少留index、text、style表格 DTO 留tableIndex、rows、maxColumns文檔 DTO 再掛fileName、fileSha256、paragraphs、tables。這樣解析器換實(shí)現(xiàn)Service 和 DAO 不用動(dòng)。public class DocumentDTO { private String fileName; private String fileSha256; private ListParagraphDTO paragraphs new ArrayList(); private ListTableDTO tables new ArrayList(); // getter/setter 省略 } public class TableDTO { private int tableIndex; private int maxColumns; private ListListString rows new ArrayList(); // getter/setter 省略 }maxColumns不是裝飾字段。合并單元格、空單元格會讓每行列數(shù)不一致入庫前用它統(tǒng)一補(bǔ)齊不然前端渲染表格時(shí)列錯(cuò)位查起來像玄學(xué)。fileSha256在解析前算重復(fù)上傳直接命中唯一鍵不用先解析再判重。DTO 里不要放XWPFDocument、XWPFTable這類對象它們持有 XML 樹和流序列化、緩存、異步傳遞都會出問題。3.3 表格行怎么映射成業(yè)務(wù)字段表頭別名與空單元格表格入庫有兩種做法整行 JSON 存一張子表或者按表頭映射成業(yè)務(wù)字段。前者通用后者好查。源碼包里一般兩種都留doc_table_row存原始行 JSON業(yè)務(wù)表按需再抽字段。表頭映射不要寫死中文用別名表運(yùn)營改個(gè)“姓名/員工姓名/人員姓名”不至于改代碼。public MapString, Integer headerIndex(ListString header) { MapString, String alias new HashMap(); alias.put(姓名, name); alias.put(員工姓名, name); alias.put(人員姓名, name); alias.put(部門, dept); alias.put(所屬部門, dept); MapString, Integer index new HashMap(); for (int i 0; i header.size(); i) { String key alias.get(header.get(i).trim()); if (key ! null) { index.putIfAbsent(key, i); } } return index; }trim()不能省Word 表頭里常有前后空格和不間斷空格。putIfAbsent保證重復(fù)別名只取第一列后面出現(xiàn)同名列不會覆蓋。映射不到的業(yè)務(wù)字段要記錄到unmapped_headers不要靜默丟列。空單元格按空字符串入庫不要轉(zhuǎn) null否則前端回顯和后續(xù)concat查詢會多一層判空。4. 入庫不是 save 一下批量插入、事務(wù)與字段長度4.1 表結(jié)構(gòu)設(shè)計(jì)主表存元數(shù)據(jù)子表存段落與表格行Word 導(dǎo)入的表結(jié)構(gòu)不要只建一張大表。主表存文件元數(shù)據(jù)和解析狀態(tài)段落表按順序存文本表格行表存原始行 JSON需要檢索的字段再抽到業(yè)務(wù)表。這樣重導(dǎo)入時(shí)只刪子表不污染業(yè)務(wù)數(shù)據(jù)。表關(guān)鍵字段用途doc_mainid、file_name、file_sha256、status、created_at一次導(dǎo)入一條file_sha256唯一doc_paragraphdoc_id、para_index、content、style段落順序和文本doc_table_rowdoc_id、table_index、row_index、row_json表格原始行保留列坐標(biāo)doc_import_logdoc_id、step、cost_ms、error_msg排查解析和入庫耗時(shí)file_sha256用char(64)不要用varchar(255)唯一索引長度可控。content用text或mediumtext按單段落長度選別一上來就longtext。row_json用 JSON 類型MySQL 5.7 以上支持查詢時(shí)可以用json_extract但高頻檢索字段還是抽列別讓業(yè)務(wù)查詢?nèi)?JSON 掃描。4.2 JdbcTemplate 批量插入與批大小段落和表格行動(dòng)輒幾百上千條逐條insert在開發(fā)環(huán)境看不出生產(chǎn)上一萬行能跑幾十秒。用JdbcTemplate.batchUpdate按批提交批大小我一般設(shè) 500太小網(wǎng)絡(luò)往返多太大事務(wù)日志和內(nèi)存壓力上來。MySQL 連接串要開rewriteBatchedStatementstrue否則驅(qū)動(dòng)可能還是一條條發(fā)。public void saveParagraphs(long docId, ListParagraphDTO list) { String sql insert into doc_paragraph(doc_id, para_index, content, style) values (?, ?, ?, ?); ListObject[] args new ArrayList(list.size()); for (ParagraphDTO p : list) { args.add(new Object[]{docId, p.getIndex(), p.getText(), p.getStyle()}); } int batchSize 500; for (int from 0; from args.size(); from batchSize) { int to Math.min(from batchSize, args.size()); jdbcTemplate.batchUpdate(sql, args.subList(from, to)); } }args.subList是視圖不要在循環(huán)里再改原列表。batchSize按數(shù)據(jù)庫和網(wǎng)絡(luò)調(diào)500 是保守值。content入庫前做長度截?cái)嗷蛐ｒ?yàn)超長直接拋業(yè)務(wù)異常別讓數(shù)據(jù)庫報(bào)Data too long后整批回滾。style可能為 null允許空就留空不允許就在 DTO 層給默認(rèn)值。4.3 事務(wù)邊界解析失敗不留半截?cái)?shù)據(jù)事務(wù)最容易翻車的點(diǎn)是把解析也包進(jìn)去。POI 解析大文件耗時(shí)幾秒到幾十秒事務(wù)一直開著數(shù)據(jù)庫連接被占住并發(fā)一上來連接池就滿。我一般把流程拆成三段事務(wù)外解析并算哈希事務(wù)內(nèi)先查重再寫主表和子表事務(wù)外做回讀校驗(yàn)和日志。Transactional(rollbackFor Exception.class) public long saveDocument(DocumentDTO dto) { Long exists jdbcTemplate.queryForObject( select id from doc_main where file_sha256 ?, Long.class, dto.getFileSha256()); if (exists ! null) { return exists; } KeyHolder kh new GeneratedKeyHolder(); jdbcTemplate.update(con - { PreparedStatement ps con.prepareStatement( insert into doc_main(file_name, file_sha256, status, created_at) values (?, ?, ?, now()), Statement.RETURN_GENERATED_KEYS); ps.setString(1, dto.getFileName()); ps.setString(2, dto.getFileSha256()); ps.setString(3, PARSED); return ps; }, kh); long docId kh.getKey().longValue(); saveParagraphs(docId, dto.getParagraphs()); saveTableRows(docId, dto.getTables()); return docId; }rollbackFor Exception.class要顯式寫默認(rèn)只回滾運(yùn)行時(shí)異常。查重和插入放在同一事務(wù)里仍有并發(fā)窗口所以file_sha256上必須建唯一索引捕獲DuplicateKeyException后回查已有 ID。先刪后插只適合重導(dǎo)入明確覆蓋的場景正常導(dǎo)入用唯一鍵冪等更穩(wěn)。5. 避坑排查中文亂碼、合并單元格、OOM 與重復(fù)上傳5.1 現(xiàn)象中文變成問號或方塊現(xiàn)象是入庫后段落文本正常表格里的中文變成???或者前端展示成方塊。原因通常不在 POI而在數(shù)據(jù)庫連接和表字符集連接串沒帶useUnicodetruecharacterEncodingUTF-8表用latin1或者上傳文件名按 ISO-8859-1 解了一遍。先查庫和連接再懷疑文件。show variables like character_set%; show create table doc_paragraph;表統(tǒng)一utf8mb4連接串顯式指定編碼。老 .doc 里的文本如果是本地編碼HWPF 讀出來可能已經(jīng)是錯(cuò)碼這種要在解析入口按文件來源做編碼探測別指望入庫時(shí)再救。文件名亂碼則用new String(name.getBytes(StandardCharsets.ISO_8859_1), StandardCharsets.UTF_8)前先確認(rèn)容器編碼不要無腦轉(zhuǎn)。5.2 現(xiàn)象表格列數(shù)對不上現(xiàn)象是同一張表第一行 6 列第三行 4 列前端渲染錯(cuò)位。原因多半是合并單元格POI 的getTableCells()返回物理單元格跨列合并不會重復(fù)占位空單元格也可能被跳過。解決是按maxColumns補(bǔ)齊同時(shí)保留原始tableIndex和rowIndex別在解析階段就把坐標(biāo)丟了。private ListString normalize(ListString cells, int maxColumns) { ListString row new ArrayList(cells); while (row.size() maxColumns) { row.add(); } return row.size() maxColumns ? row.subList(0, maxColumns) : row; }補(bǔ)齊只解決渲染業(yè)務(wù)映射還要知道哪一列是合并出來的。需要精確坐標(biāo)就繼續(xù)讀CTTcPr的gridSpan把跨列數(shù)記到 JSON 里。不要用“第一列一定是姓名”這種假設(shè)表頭別名映射比位置映射抗改。5.3 現(xiàn)象大文件解析時(shí)堆內(nèi)存飆升現(xiàn)象是 30MB 的 Word 一上傳服務(wù)堆內(nèi)存直線上升頻繁 Full GC最后 OOM。XWPFDocument 會把整個(gè)文檔加載進(jìn)內(nèi)存圖片越多越明顯。先卡上傳大小再把解析放異步線程池別在 Web 線程里硬扛。圖片不要全部讀成byte[]再塞 DTO邊讀邊寫臨時(shí)文件或?qū)ο蟠鎯?。if (file.getSize() maxFileSize) { throw new BizException(FILE_TOO_LARGE); }maxFileSize按業(yè)務(wù)定合同類 20MB 夠用帶大量掃描圖的 Word 要單獨(dú)走圖片壓縮或人工拆分。異步解析要配獨(dú)立線程池和隊(duì)列上限隊(duì)列滿了直接拒絕別讓任務(wù)堆在內(nèi)存里。解析完及時(shí)關(guān)流XWPFDocument的close()不能漏。5.4 現(xiàn)象同一文件重復(fù)入庫現(xiàn)象是運(yùn)營點(diǎn)兩次上傳主表出現(xiàn)兩條一樣的數(shù)據(jù)子表翻倍。原因可能是前端重復(fù)提交、網(wǎng)關(guān)重試、用戶改文件名再傳。解決用文件內(nèi)容哈希做冪等鍵不要用文件名。SHA-256 在解析前算命中唯一鍵直接返回已有docId。public static String sha256(InputStream in) throws IOException { MessageDigest md MessageDigest.getInstance(SHA-256); byte[] buf new byte[8192]; int len; while ((len in.read(buf)) ! -1) { md.update(buf, 0, len); } StringBuilder sb new StringBuilder(); for (byte b : md.digest()) { sb.append(String.format(%02x, b)); } return sb.toString(); }流讀完要重新打開文件再解析MultipartFile 的getInputStream()每次調(diào)用一般給新流但不要假設(shè)所有實(shí)現(xiàn)都支持重復(fù)讀。唯一索引沖突捕獲后回查返回同一docId前端提示“已存在”而不是報(bào)錯(cuò)。5.5 現(xiàn)象.doc 文件一讀就拋異?，F(xiàn)象是 .docx 正常.doc 一上傳就拋OfficeXmlFileException或OldWordFileFormatException或者讀出來只有幾行。原因常見兩類后綴是 .doc 實(shí)際是 .docx 改名的或者 HWPF 不支持該 .doc 的復(fù)雜結(jié)構(gòu)。先做文件頭校驗(yàn)再看異常類型不要一律當(dāng)解析失敗。if (lower.endsWith(.doc)) { try (InputStream in file.getInputStream()) { new HWPFDocument(in); } catch (Exception e) { throw new BizException(DOC_PARSE_FAILED_SAVE_AS_DOCX); } }文件頭校驗(yàn)?zāi)軗踝「拿募?。HWPF 讀不了的就提示另存為 .docx不要在生產(chǎn)環(huán)境做二進(jìn)制格式轉(zhuǎn)換依賴重、效果不穩(wěn)。導(dǎo)入日志里記下原始文件名、大小、異常類名后面運(yùn)營反饋“這份文件傳不上”時(shí)能直接定位不用靠猜。6. 進(jìn)階驗(yàn)證用回讀比對和影子表把上傳鏈路跑穩(wěn)6.1 回讀比對段落數(shù)、表格行列數(shù)、文本哈希解析入庫后別只看接口返回成功。我一般做一次回讀比對按doc_id查段落數(shù)、表格行數(shù)和 DTO 里的數(shù)量比再抽前 20 段拼文本算哈希和解析結(jié)果比。數(shù)量對不上先查合并單元格和空行哈希對不上查字符集和trim。這三項(xiàng)跑通基本能擋住大部分“看起來成功、查出來是空”的問題。public void verify(long docId, DocumentDTO dto) { Integer paraCount jdbcTemplate.queryForObject( select count(*) from doc_paragraph where doc_id ?, Integer.class, docId); if (paraCount null || paraCount ! dto.getParagraphs().size()) { throw new IllegalStateException(paragraph count mismatch); } Integer tableRows jdbcTemplate.queryForObject( select count(*) from doc_table_row where doc_id ?, Integer.class, docId); int expected dto.getTables().stream().mapToInt(t - t.getRows().size()).sum(); if (tableRows null || tableRows ! expected) { throw new IllegalStateException(table row count mismatch); } }verify放在事務(wù)提交后跑失敗只記日志和告警不回滾已入庫數(shù)據(jù)避免大文件反復(fù)重試把庫壓垮?；刈x比對用的連接要和業(yè)務(wù)連接分開別讓校驗(yàn)把連接池占滿。6.2 影子表先跑批再切主表新解析器上線前我會建一張doc_shadow影子表拿歷史 Word 跑批把段落數(shù)、表格行數(shù)、文本哈希、耗時(shí)四個(gè)指標(biāo)記下來和舊鏈路對比。差異超過閾值的樣本單獨(dú)撈出來看是合并單元格還是編碼問題。影子表跑一周再切主表比直接上線后靠用戶反饋穩(wěn)得多。指標(biāo)采集方式關(guān)注點(diǎn)段落數(shù)doc_paragraphcount頂層段落是否漏讀表格行數(shù)doc_table_rowcount合并單元格是否少列文本哈希前 20 段拼接 SHA-256編碼和空白字符解析耗時(shí)日志cost_ms大文件是否拖垮線程池從那以后我每次接 Word 解析需求都先拿三份臟樣本跑一遍列數(shù)比對和回讀校驗(yàn)再談入庫。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取