態(tài)表頭Excel導(dǎo)出：告別硬編碼，靈活應(yīng)對(duì)需求變更)
上周運(yùn)營提了一個(gè)新需求說報(bào)表導(dǎo)出的時(shí)候要能自己勾選導(dǎo)出哪些列不同角色看的列還不一樣。這已經(jīng)不是第一次為了導(dǎo)出表頭改代碼了以前每次字段調(diào)整都要去改實(shí)體類上的ExcelProperty注解加一個(gè)字段、改一個(gè)列名都得出一次版本。這次我直接把導(dǎo)出工具類重構(gòu)了一版核心思路就一句話表頭不再寫死在注解里而是運(yùn)行時(shí)動(dòng)態(tài)傳入。做完之后發(fā)現(xiàn)這個(gè)改動(dòng)帶來的一連串收益遠(yuǎn)超預(yù)期今天把整個(gè)設(shè)計(jì)和實(shí)現(xiàn)過程完整記錄一下。這篇內(nèi)容主要面向做 Java 后端、經(jīng)常要和 Excel 導(dǎo)出打交道的朋友。如果你還在用硬編碼表頭的方式寫導(dǎo)出每次需求變更都要發(fā)版那這篇文章正好能解決你的問題。我會(huì)從頭到尾講清楚為什么表頭要?jiǎng)討B(tài)化、工具類怎么設(shè)計(jì)、核心代碼怎么落地以及我在實(shí)現(xiàn)過程中踩過的各種坑。1. 為什么表頭非要?jiǎng)討B(tài)不可從一次改到煩的需求說起1.1 運(yùn)營一句話后端改半天做后臺(tái)系統(tǒng)的同學(xué)應(yīng)該都有這種經(jīng)歷。運(yùn)營同學(xué)跑過來說這個(gè)用戶列表的導(dǎo)出能不能把最后登錄時(shí)間放在手機(jī)號(hào)前面你看了看代碼實(shí)體類上的ExcelProperty(value 手機(jī)號(hào))和ExcelProperty(value 最后登錄時(shí)間)順序?qū)懰懒说谜{(diào)注解順序重新發(fā)版。好不容易上線了運(yùn)營又說現(xiàn)在不看手機(jī)號(hào)了幫我換成注冊(cè)來源吧。你又得改注解、提測、發(fā)版。一次兩次還行一個(gè)月來五次誰受得了后來運(yùn)營又提了一個(gè)更復(fù)雜的需求不同的人打開導(dǎo)出頁面看到的列不一樣。管理員要看手機(jī)號(hào)普通運(yùn)營不能看手機(jī)號(hào)只讓看脫敏后的用戶名和注冊(cè)時(shí)間。這種需求靠注解就真的沒法實(shí)現(xiàn)了因?yàn)橥粋€(gè)實(shí)體類不可能同時(shí)對(duì)應(yīng)多套表頭結(jié)構(gòu)。你得寫兩個(gè)實(shí)體類各寫一套注解加一個(gè)場景再加一個(gè)類。1.2 注解寫死表頭的三個(gè)核心痛點(diǎn)我把用注解方式做導(dǎo)出的痛點(diǎn)梳理了一下歸根結(jié)底是這三條。第一表頭變更必須改代碼發(fā)版。這是最直接的痛。表頭本質(zhì)上是一個(gè)需求層面的東西業(yè)務(wù)方改表頭跟改頁面上的文案一樣頻繁把這種高頻變化的東西硬編碼進(jìn)代碼里等于每次變更都要走一遍完整的開發(fā)流程。第二一個(gè)實(shí)體類只能綁一套表頭。你想讓同一個(gè)查詢結(jié)果導(dǎo)出成兩種不同列組合的 Excel用注解就非常別扭。要么寫兩個(gè)實(shí)體類要么導(dǎo)出前先做一遍字段映射把實(shí)體轉(zhuǎn)成另一個(gè)結(jié)構(gòu)非常繁瑣。第三復(fù)雜表頭實(shí)現(xiàn)成本高。像用戶信息這個(gè)大分類下面掛姓名和年齡兩個(gè)子列這種多層合并表頭用注解雖然也能做但寫起來很繞需要額外定義一堆內(nèi)部類。等你想支持運(yùn)行時(shí)用戶自己選列注解這套玩法就徹底走不通了。1.3 動(dòng)態(tài)表頭解決的其實(shí)是響應(yīng)變化的問題動(dòng)態(tài)表頭這個(gè)詞聽起來挺玄乎本質(zhì)上就是把表頭長什么樣這個(gè)決策時(shí)機(jī)從編譯期推遲到運(yùn)行時(shí)。你不再告訴代碼表頭永遠(yuǎn)是這三列而是讓調(diào)用方在調(diào)用導(dǎo)出方法的時(shí)候把想要的表頭結(jié)構(gòu)傳進(jìn)來。表頭想變調(diào)用方改一下傳參就行導(dǎo)出工具類一行代碼都不用改。這個(gè)思路和依賴注入其實(shí)是一個(gè)道理把變化的部分從穩(wěn)定的部分中剝離出來。穩(wěn)定的部分是我怎么生成一個(gè) Excel 文件變化的部分是表頭長什么樣、數(shù)據(jù)有哪些列。工具類負(fù)責(zé)處理穩(wěn)定的部分動(dòng)態(tài)表頭負(fù)責(zé)承載變化的部分。這樣一來任何表頭層面的調(diào)整都只是調(diào)用方的參數(shù)變化不會(huì)再波及導(dǎo)出的底層代碼。2. 需求邊界一個(gè)動(dòng)態(tài)表頭導(dǎo)出工具類到底要做到什么程度2.1 先列清楚功能需求清單動(dòng)手寫代碼之前我先把需求邊界劃清楚。如果只說支持動(dòng)態(tài)修改表頭很容易做成一個(gè)四不像所以我把工具類需要支持的能力列了個(gè)清單。表頭列表由調(diào)用方傳入不依賴實(shí)體類上的注解想導(dǎo)哪些列、列名叫什么全部由參數(shù)決定。支持多層合并表頭即一個(gè)父列下掛多個(gè)子列這是實(shí)際業(yè)務(wù)里最常用的復(fù)雜表頭形態(tài)。數(shù)據(jù)行和表頭列順序嚴(yán)格對(duì)應(yīng)調(diào)用方按表頭順序逐列給數(shù)據(jù)。支持大數(shù)據(jù)量分批寫入不能因?yàn)閷?dǎo)出 10 萬行數(shù)據(jù)就把堆內(nèi)存打滿。不綁定具體業(yè)務(wù)模型任何業(yè)務(wù)都能復(fù)用同一個(gè)工具類。有了這份清單工具類的定位就清楚了它不是一個(gè)用戶導(dǎo)出工具也不是訂單導(dǎo)出工具而是一個(gè)通用的Excel 導(dǎo)出底座。2.2 技術(shù)選型為什么選 EasyExcel 而不是原生 POI這個(gè)工具類底層我用的是阿里開源的 EasyExcel。沒有從零基于 POI 手寫原因很現(xiàn)實(shí)EasyExcel 在 POI 之上封裝了很多易用性和內(nèi)存優(yōu)化尤其是SAX模式逐行讀寫的設(shè)計(jì)能顯著降低大數(shù)據(jù)量導(dǎo)出時(shí)內(nèi)存的占用這在后文踩坑部分我會(huì)詳細(xì)對(duì)比數(shù)據(jù)。易用性上EasyExcel 天然支持把表頭定義成ListListString傳入這正好是動(dòng)態(tài)表頭需要的形態(tài)。原生 POI 要自己創(chuàng)建 Row 和 Cell 去拼表頭代碼量會(huì)翻一倍。我整理了一個(gè)簡單對(duì)比當(dāng)時(shí)就是基于這個(gè)對(duì)比鎖定的 EasyExcel對(duì)比項(xiàng)原生 POIEasyExcel表頭動(dòng)態(tài)化便利度需要手動(dòng)操作 Cell直接傳入 List 結(jié)構(gòu)開箱即用5 萬行數(shù)據(jù)的粗略內(nèi)存占用較高容易 OOM明顯更低實(shí)測比較穩(wěn)API 易用性代碼較多心智負(fù)擔(dān)重封裝度高配置清晰社區(qū)活躍度穩(wěn)定但更新慢國內(nèi)企業(yè)使用廣泛資料多2.3 動(dòng)態(tài)表頭模式的邊界條件這里有一點(diǎn)必須先說清楚動(dòng)態(tài)表頭模式下注解自動(dòng)映射的能力就廢了。你用ExcelProperty綁定實(shí)體類字段時(shí)EasyExcel 會(huì)自動(dòng)把對(duì)象屬性和列對(duì)應(yīng)起來但一旦表頭改成運(yùn)行時(shí)傳入的ListListString數(shù)據(jù)部分就必須配套改成ListListObject——外層 List 代表一行記錄內(nèi)層 List 按表頭順序存放這一行的每個(gè)單元格的值。順序一旦錯(cuò)位數(shù)據(jù)就會(huì)填到錯(cuò)誤的列下面這在第 5 部分踩坑里我會(huì)詳細(xì)展開。另外動(dòng)態(tài)表頭模式下默認(rèn)的單元格樣式會(huì)變得比較原始比如表頭沒有加粗、內(nèi)容不做居中。要處理這個(gè)問題需要額外的樣式 Handler 或者策略類并不會(huì)因?yàn)橛昧?EasyExcel 就自動(dòng)帶過來。3. 整體設(shè)計(jì)先畫清楚主流程再寫代碼3.1 工具類的核心結(jié)構(gòu)整個(gè)工具類的設(shè)計(jì)我分成三個(gè)部分一個(gè)對(duì)外暴露的靜態(tài)方法入口ExcelExportUtils、一個(gè)承載表頭結(jié)構(gòu)的元數(shù)據(jù)模型、以及底層的寫入執(zhí)行流程。沒有引入 Spring 依賴純 JDK EasyExcel這樣不管你是 Spring Boot 項(xiàng)目還是普通 Java 項(xiàng)目都能直接用。對(duì)外入口我設(shè)計(jì)成兩個(gè)重載方法。第一個(gè)方法接收完整的數(shù)據(jù)集合適合中小數(shù)據(jù)量場景一次性把表頭和數(shù)據(jù)傳給工具類第二個(gè)方法接收一個(gè)分批獲取數(shù)據(jù)的函數(shù)式接口適合大數(shù)據(jù)量場景工具類內(nèi)部按頁調(diào)用這個(gè)接口拿數(shù)據(jù)并批量寫入避免一次性把全量數(shù)據(jù)加載進(jìn)內(nèi)存。3.2 表頭數(shù)據(jù)結(jié)構(gòu)怎么定動(dòng)態(tài)表頭的核心是表頭的數(shù)據(jù)結(jié)構(gòu)。我選擇了ListListString這個(gè)結(jié)構(gòu)一開始可能有點(diǎn)繞我舉個(gè)例子。假設(shè)我要生成一個(gè)這樣的表頭| 序號(hào) | 用戶信息 | 注冊(cè)信息 | | | 姓名 | 年齡 | 注冊(cè)時(shí)間 |對(duì)應(yīng)到ListListString就是ListListString headList new ArrayList(); // 第一列只有一層占兩行 headList.add(Arrays.asList(序號(hào))); // 第二列父列用戶信息子列姓名 headList.add(Arrays.asList(用戶信息, 姓名)); // 第三列父列用戶信息子列年齡 headList.add(Arrays.asList(用戶信息, 年齡)); // 第四列父列注冊(cè)信息子列注冊(cè)時(shí)間 headList.add(Arrays.asList(注冊(cè)信息, 注冊(cè)時(shí)間));內(nèi)層 List 的長度代表這個(gè)列跨幾層同一父列下的子列 EasyExcel 會(huì)自動(dòng)幫你合并單元格。這個(gè)數(shù)據(jù)結(jié)構(gòu)是 EasyExcel 官方支持的動(dòng)態(tài)表頭寫法理解起來也不難外層一個(gè)元素是一整列內(nèi)層的字符串從上到下就是這一列從父級(jí)到子級(jí)的表頭內(nèi)容。3.3 導(dǎo)出主流程工具類內(nèi)部的主流程其實(shí)很簡潔。第一步根據(jù)文件名和響應(yīng)對(duì)象初始化ExcelWriter第二步用傳入的headList構(gòu)建WriteSheet第三步寫入數(shù)據(jù)第四步調(diào)用finish方法把緩沖區(qū)的內(nèi)容刷到輸出流并釋放資源。整個(gè)過程最難的不是代碼而是調(diào)參和防坑。在第 4 部分我會(huì)先給出完整可用的實(shí)現(xiàn)代碼第 5 部分再集中講我踩過的坑這樣你在使用的時(shí)候遇到問題可以回頭對(duì)照。4. 動(dòng)態(tài)表頭的核心實(shí)現(xiàn)直接給可落地的工具類代碼4.1 基礎(chǔ)版本一次性傳入表頭和數(shù)據(jù)先給一個(gè)最直接的版本適用于大多數(shù)中小數(shù)據(jù)量的導(dǎo)出場景。package com.example.excel; import com.alibaba.excel.EasyExcel; import com.alibaba.excel.ExcelWriter; import com.alibaba.excel.write.metadata.WriteSheet; import com.alibaba.excel.write.style.HorizontalCellStyleStrategy; import org.apache.poi.ss.usermodel.HorizontalAlignment; import org.apache.poi.ss.usermodel.IndexedColors; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import java.util.List; /** * Excel 導(dǎo)出工具類核心特性動(dòng)態(tài)表頭。 * 表頭結(jié)構(gòu)由調(diào)用方傳入 ListListString不綁定任何實(shí)體類注解。 */ public final class ExcelExportUtils { private ExcelExportUtils() { } /** * 導(dǎo)出 Excel一次性寫入全部數(shù)據(jù)適合中小數(shù)據(jù)量。 * * param response HTTP 響應(yīng)對(duì)象 * param fileName 導(dǎo)出文件名不需要帶 .xlsx 后綴 * param sheetName Sheet 名稱 * param headList 動(dòng)態(tài)表頭外層 List 是一列內(nèi)層 List 從父級(jí)到子級(jí)排列 * param dataList 數(shù)據(jù)行每行 List 的元素順序必須與 headList 的列順序一致 */ public static void exportWithData(HttpServletResponse response, String fileName, String sheetName, ListListString headList, ListListObject dataList) throws IOException { // 1. 設(shè)置 HTTP 響應(yīng)頭讓瀏覽器識(shí)別為下載 response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setCharacterEncoding(utf-8); String encodedFileName URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString()) .replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment;filename*utf-8 encodedFileName); // 2. 構(gòu)建樣式策略 HorizontalCellStyleStrategy styleStrategy buildDefaultStyleStrategy(); // 3. 寫入并釋放資源 ExcelWriter excelWriter EasyExcel.write(response.getOutputStream()).build(); WriteSheet writeSheet EasyExcel.writerSheet(sheetName).head(headList).build(); excelWriter.write(dataList, writeSheet); excelWriter.finish(); } /** * 構(gòu)建默認(rèn)樣式表頭灰底加粗居中內(nèi)容居中。 */ private static HorizontalCellStyleStrategy buildDefaultStyleStrategy() { // 表頭樣式 WriteCellStyle headStyle new WriteCellStyle(); headStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex()); headStyle.setHorizontalAlignment(HorizontalAlignment.CENTER); WriteFont headFont new WriteFont(); headFont.setBold(true); headFont.setFontHeightInPoints((short) 11); headStyle.setWriteFont(headFont); // 數(shù)據(jù)行樣式 WriteCellStyle contentStyle new WriteCellStyle(); contentStyle.setHorizontalAlignment(HorizontalAlignment.CENTER); return new HorizontalCellStyleStrategy(headStyle, contentStyle); } }這里有幾個(gè)細(xì)節(jié)需要說明一下。響應(yīng)頭里的filename*utf-8是解決中文文件名亂碼的標(biāo)準(zhǔn)寫法我一開始直接用filename加 URL 編碼后的文件名發(fā)現(xiàn)部分瀏覽器會(huì)把文件名里的%E6%9F%90這種字符直接顯示出來用filename*配合URLEncoder編碼后就正常了。另外ExcelWriter的finish()方法一定要在 finally 或者正常流程末尾調(diào)用它會(huì)觸發(fā)流資源的釋放漏掉的話會(huì)導(dǎo)致導(dǎo)出的文件損壞、打不開。4.2 大數(shù)據(jù)量版本分批拉取邊查邊寫一次性傳入所有數(shù)據(jù)雖然簡單但假如你要導(dǎo)出的是幾十萬行用戶數(shù)據(jù)把所有數(shù)據(jù)先查出來放到內(nèi)存里再傳給工具類內(nèi)存很容易扛不住。EasyExcel 的優(yōu)勢在于它可以分批寫入每批寫完就釋放內(nèi)存壓力很小。我設(shè)計(jì)了一個(gè)函數(shù)式接口DataPageProvider由調(diào)用方實(shí)現(xiàn)分批查詢邏輯FunctionalInterface public interface DataPageProvider { /** * 獲取一頁數(shù)據(jù)。 * * param pageNum 頁碼從 1 開始 * param pageSize 每頁行數(shù) * return 當(dāng)前頁數(shù)據(jù)列表如果沒有更多數(shù)據(jù)返回 null 或空集合 */ ListListObject fetch(int pageNum, int pageSize); }然后增加一個(gè)分批導(dǎo)出的重載方法public static void exportByPage(HttpServletResponse response, String fileName, String sheetName, ListListString headList, int pageSize, DataPageProvider dataPageProvider) throws IOException { response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setCharacterEncoding(utf-8); String encodedFileName URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString()) .replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment;filename*utf-8 encodedFileName); HorizontalCellStyleStrategy styleStrategy buildDefaultStyleStrategy(); ExcelWriter excelWriter EasyExcel.write(response.getOutputStream()) .registerWriteHandler(styleStrategy) .build(); WriteSheet writeSheet EasyExcel.writerSheet(sheetName).head(headList).build(); int pageNum 1; while (true) { ListListObject pageData dataPageProvider.fetch(pageNum, pageSize); if (pageData null || pageData.isEmpty()) { break; } excelWriter.write(pageData, writeSheet); pageNum; // 每批數(shù)據(jù)用完即可被 GC內(nèi)存只保留當(dāng)前批的數(shù)據(jù) } excelWriter.finish(); }這樣調(diào)用方就可以用 lambda 把 MyBatis-Plus 的分頁查詢邏輯傳進(jìn)來比如ExcelExportUtils.exportByPage(response, 用戶導(dǎo)出, 用戶, headList, 5000, (pageNum, pageSize) - { PageUserDO page userMapper.selectPage(new Page(pageNum, pageSize), null); if (page.getRecords().isEmpty()) { return null; } return page.getRecords().stream() .map(user - Arrays.asList( user.getId(), user.getName(), user.getPhone() )) .collect(Collectors.toList()); });這種方式下無論導(dǎo)出的數(shù)據(jù)量多大內(nèi)存里同一時(shí)刻只保留一個(gè) pageSize 批次的數(shù)據(jù)極大的降低了 OOM 概率。4.3 一個(gè)復(fù)雜的動(dòng)態(tài)表頭實(shí)際調(diào)用示例為了讓你對(duì)動(dòng)態(tài)表頭有一個(gè)直觀的概念我放一個(gè)真實(shí)場景的調(diào)用代碼。假設(shè)運(yùn)營后臺(tái)需要導(dǎo)出一份帶合并表頭的用戶分析表ListListString headList new ArrayList(); headList.add(Collections.singletonList(序號(hào))); headList.add(Arrays.asList(用戶信息, 姓名)); headList.add(Arrays.asList(用戶信息, 年齡)); headList.add(Arrays.asList(用戶信息, 手機(jī)號(hào))); headList.add(Arrays.asList(行為數(shù)據(jù), 最近登錄時(shí)間)); headList.add(Arrays.asList(行為數(shù)據(jù), 訂單數(shù))); ListListObject dataList new ArrayList(); dataList.add(Arrays.asList(1, 張三, 28, 138****1234, 2025-01-15 10:24:00, 12)); dataList.add(Arrays.asList(2, 李四, 32, 139****5678, 2025-01-14 22:10:00, 5)); ExcelExportUtils.exportWithData(response, 用戶分析報(bào)表, 用戶分析, headList, dataList);這段代碼導(dǎo)出的 Excel 里用戶信息和行為數(shù)據(jù)兩個(gè)父列會(huì)自動(dòng)跨行合并效果和你在 Excel 里手動(dòng)合并單元格是一樣的。運(yùn)營再提我要加一列注冊(cè)來源這個(gè)需求時(shí)你只需要在 headList 和數(shù)據(jù)列表里各加一個(gè)元素工具類一行都不用改。5. 踩坑記錄動(dòng)態(tài)表頭遠(yuǎn)沒有看起來那么簡單5.1 坑一動(dòng)態(tài)表頭下樣式和列寬全部失效第一次跑通動(dòng)態(tài)表頭導(dǎo)出時(shí)導(dǎo)出的文件確實(shí)能打開但表頭灰白的底色沒了字體也不加粗了數(shù)據(jù)全部擠在左側(cè)列寬也是默認(rèn)寬度列名都顯示不全。原因是當(dāng)你通過head(ListListString)傳入表頭時(shí)EasyExcel 不會(huì)自動(dòng)套用基于注解設(shè)計(jì)的樣式策略。解決方式就是我工具類里那套HorizontalCellStyleStrategy但這里有一個(gè)容易忽略的細(xì)節(jié)在分批導(dǎo)出版本里一定要通過excelWriter的registerWriteHandler(styleStrategy)來注冊(cè)樣式而不是在writerSheet之后才傳。我之前在測試時(shí)把樣式策略放在writerSheet(...).build()后面?zhèn)魅虢Y(jié)果數(shù)據(jù)行有樣式、表頭沒有樣式排查了半天才意識(shí)到注冊(cè)順序會(huì)影響樣式作用范圍。列寬的坑也值得一提。如果你不對(duì)列寬做任何處理動(dòng)態(tài)表頭模式下所有列寬都是默認(rèn)值中文表頭幾乎一定顯示不全。最簡單的方案是給 excelWriter 注冊(cè)一個(gè)LongestMatchColumnWidthStyleStrategy它會(huì)讓列寬自動(dòng)匹配本列最長的內(nèi)容包括表頭和數(shù)據(jù)。但這個(gè)策略在數(shù)據(jù)量大的時(shí)候會(huì)遍歷每一行的內(nèi)容來計(jì)算寬度性能有損耗。如果數(shù)據(jù)量特別大建議手動(dòng)按業(yè)務(wù)場景指定列寬而不是用自適應(yīng)策略。5.2 坑二表頭和數(shù)據(jù)列順序錯(cuò)位數(shù)據(jù)填到錯(cuò)誤的列動(dòng)態(tài)表頭模式下最容易踩的坑就是這個(gè)headList 的順序和 dataList 內(nèi)層 List 的順序必須完全一致否則數(shù)據(jù)會(huì)錯(cuò)位。這不是工具類能幫你兜底的因?yàn)楣ぞ哳惛静恢滥愕臉I(yè)務(wù)字段叫什么它只認(rèn)順序。我自己的排查經(jīng)驗(yàn)是先在調(diào)用方寫一個(gè)簡單的斷言方法確認(rèn) headList 的 size 和 dataList 每一行的 size 相等如果不相等直接拋異常不要等導(dǎo)出完才發(fā)現(xiàn)。耗時(shí)不多但能避免大量低級(jí)錯(cuò)誤。如果用到分批導(dǎo)出還需要注意每一批數(shù)據(jù)行的列數(shù)都要一致否則后續(xù)的行會(huì)發(fā)生錯(cuò)位。另外DataPageProvider 分批查詢時(shí)每一頁返回的數(shù)據(jù)行數(shù)不能超過 pageSize否則會(huì)出現(xiàn)寫入亂序的問題。這個(gè)在實(shí)現(xiàn)查詢函數(shù)時(shí)稍微注意一下就行分頁查詢框架一般不會(huì)出現(xiàn)這種問題但如果是自己寫 SQL 的就要多留個(gè)心眼。5.3 坑三單元格內(nèi)容以 或 開頭被 Excel 當(dāng)成公式導(dǎo)出用戶備注時(shí)如果用戶備注是逾期用戶或者所有人Excel 打開文件的時(shí)候會(huì)把逾期用戶解析成公式導(dǎo)致單元格報(bào)錯(cuò)或顯示異常。這個(gè)問題不是 EasyExcel 特有的用 POI 也一樣會(huì)遇到屬于 Excel 本身的安全機(jī)制。解決方式是在寫入數(shù)據(jù)前對(duì)單元格內(nèi)容做一次前導(dǎo)字符轉(zhuǎn)義。做一個(gè)簡單的字符串處理private static Object safeCellValue(Object value) { if (value instanceof String) { String str (String) value; if (str.startsWith() || str.startsWith() || str.startsWith()) { return str; } } return value; }注意這個(gè)方法只對(duì)字符串類型做處理數(shù)字、日期等類型直接原樣返回。我在工具類的 write 環(huán)節(jié)之前統(tǒng)一對(duì)數(shù)據(jù)行做一遍清洗和表頭校驗(yàn)放在一起。這個(gè)小函數(shù)幫我避免了好幾次線上數(shù)據(jù)問題。5.4 坑四ExcelWriter 的 finish() 漏調(diào)用導(dǎo)致文件損壞實(shí)際生產(chǎn)環(huán)境里如果導(dǎo)出過程中業(yè)務(wù)代碼拋了異常比如數(shù)據(jù)庫查詢超時(shí)ExcelWriter 的輸出流沒有被正確關(guān)閉用戶下載到的就是一個(gè)損壞的文件。有人會(huì)想我用 try-with-resources 不就行了但 ExcelWriter 實(shí)現(xiàn)了 Closeable 接口可以放進(jìn) try-with-resources 里不過 EasyExcel 更推薦在 finally 里調(diào)用 finish()因?yàn)?finish() 不僅僅是關(guān)閉流還會(huì)做一些收尾工作。以我的經(jīng)驗(yàn)最穩(wěn)妥的寫法是這樣ExcelWriter excelWriter null; try { excelWriter EasyExcel.write(outputStream).build(); // ... 寫入邏輯 } finally { if (excelWriter ! null) { excelWriter.finish(); } }如果是在 Web 導(dǎo)出場景異常情況下還需要在 finally 里調(diào)用 response.reset()防止已經(jīng)寫出去的部分字節(jié)導(dǎo)致瀏覽器解析錯(cuò)誤。這個(gè)細(xì)節(jié)我可以說是踩了三次才長記性。5.5 坑五動(dòng)態(tài)表頭模式下日期格式顯示成一串?dāng)?shù)字如果你在數(shù)據(jù)列表里傳的是Date類型默認(rèn)情況下 EasyExcel 會(huì)按內(nèi)置格式輸出但如果傳的是 LocalDateTime 或者時(shí)間戳字符串顯示效果就不可控。我在工具類里沒有做強(qiáng)制轉(zhuǎn)換因?yàn)橐笳{(diào)用方自己控制數(shù)據(jù)格式。但為了統(tǒng)一體驗(yàn)我在實(shí)際項(xiàng)目中會(huì)讓調(diào)用方把時(shí)間類數(shù)據(jù)先格式化成字符串這樣最簡單可控也不容易踩明明傳了時(shí)間卻顯示成數(shù)字的坑。6. 進(jìn)階玩法從動(dòng)態(tài)表頭走向表頭配置化6.1 表頭定義搬進(jìn) JSON 或 YAML 配置動(dòng)態(tài)表頭解決了不用改代碼改表頭的問題但如果你還是把 headList 的構(gòu)建邏輯寫死在調(diào)用方代碼里本質(zhì)上也只是把改注解變成了改 Java 代碼。要讓表頭變更徹底脫離開發(fā)得把表頭定義搬到配置文件中。比如在 resources 目錄下維護(hù)一個(gè)export-head.json內(nèi)容大致是{ columns: [ { title: [用戶信息, 姓名], dataIndex: name }, { title: [用戶信息, 年齡], dataIndex: age }, { title: [行為數(shù)據(jù), 訂單數(shù)], dataIndex: orderCount } ] }運(yùn)行時(shí)通過 Jackson 把這個(gè)文件讀成配置對(duì)象再轉(zhuǎn)換成 EasyExcel 需要的ListListString。數(shù)據(jù)部分也需要配套改造從寫死每列的值變成根據(jù) dataIndex 從 Map 或?qū)ο罄锶?duì)應(yīng)字段的值這一步可以結(jié)合反射或直接把查詢結(jié)果轉(zhuǎn)成 Map 來做。這樣做的好處非常明顯運(yùn)營想加一列只要告訴運(yùn)維改一下 JSON 文件重啟都不需要配合配置中心就能生效。我見過很多大廠的報(bào)表系統(tǒng)就是這么做的——前端配置列后端按配置導(dǎo)出兩邊共用同一套元數(shù)據(jù)。6.2 表頭存數(shù)據(jù)庫做成可維護(hù)的元數(shù)據(jù)比配置文件更進(jìn)一步的做法是把表頭定義存進(jìn)數(shù)據(jù)庫做成一張導(dǎo)出模板表字段大概包含模板編碼、列序號(hào)、父表頭名稱、子表頭名稱、關(guān)聯(lián)的數(shù)據(jù)字段名、是否啟用等。運(yùn)營或者管理員可以在后臺(tái)頁面維護(hù)這張表增刪列、調(diào)整順序都走可視化界面后端導(dǎo)出時(shí)根據(jù)模板編碼查出表頭定義再查數(shù)據(jù)填充。這種方式配合動(dòng)態(tài)表頭工具類非常順手因?yàn)楣ぞ哳愐呀?jīng)沒有固定結(jié)構(gòu)了天然適配從數(shù)據(jù)庫查出什么表頭就導(dǎo)出什么表頭的模式。唯一要注意的是緩存問題表頭配置不要每次都查數(shù)據(jù)庫可以加一層本地緩存配置變更時(shí)再刷新緩存。我實(shí)現(xiàn)的時(shí)候用的是 Caffeine 本地緩存熱點(diǎn)數(shù)據(jù)基本無感知。6.3 多模板管理同一份數(shù)據(jù)多個(gè)導(dǎo)出視角表頭配置化之后很自然就會(huì)進(jìn)化出多模板管理的能力。比如用戶數(shù)據(jù)導(dǎo)出這個(gè)場景可以設(shè)計(jì)用戶基礎(chǔ)信息模板、用戶行為分析模板、運(yùn)營安全審計(jì)模板三個(gè)模板它們對(duì)應(yīng)不同的列組合、不同的表頭層級(jí)。后端導(dǎo)出接口只要多接收一個(gè)模板編碼參數(shù)工具類統(tǒng)一路由到對(duì)應(yīng)模板查配置、取數(shù)據(jù)、導(dǎo)出。這樣做還有一個(gè)額外的收益權(quán)限控制變得簡單了。管理員模板可以看到手機(jī)號(hào)和身份證號(hào)普通運(yùn)營模板看不到權(quán)限校驗(yàn)只需要在返回模板配置之前做一次判斷前端導(dǎo)出按鈕的可見列隨之變化。整個(gè)體系擴(kuò)展起來非常順暢。從我個(gè)人的使用體驗(yàn)來看把表頭做成配置、把導(dǎo)出工具類做成通用底座這個(gè)方向是對(duì)的。它不僅解決了當(dāng)時(shí)運(yùn)營提的選擇性導(dǎo)出需求還讓后續(xù)幾乎所有報(bào)表導(dǎo)出需求變成了配置工作而不是編碼工作。最后再分享一個(gè)建議如果你也在做類似的重構(gòu)不用一步到位就把配置中心、數(shù)據(jù)庫模板全上了。先把工具類的動(dòng)態(tài)表頭能力做好保證它可以通過參數(shù)控制表頭結(jié)構(gòu)后面再逐步把配置來源從硬編碼升級(jí)到 JSON、再到數(shù)據(jù)庫每一步都可以獨(dú)立上線風(fēng)險(xiǎn)可控。這套工具類在我這邊已經(jīng)穩(wěn)定跑了半年多中間經(jīng)歷了多輪表頭調(diào)整一行導(dǎo)出代碼都沒改過這也是我特別想把這段經(jīng)驗(yàn)記錄下來的原因。 Java動(dòng)態(tài)表頭Excel導(dǎo)出：告別硬編碼，靈活應(yīng)對(duì)需求變更
上周運(yùn)營提了一個(gè)新需求說報(bào)表導(dǎo)出的時(shí)候要能自己勾選導(dǎo)出哪些列不同角色看的列還不一樣。這已經(jīng)不是第一次為了導(dǎo)出表頭改代碼了以前每次字段調(diào)整都要去改實(shí)體類上的ExcelProperty注解加一個(gè)字段、改一個(gè)列名都得出一次版本。這次我直接把導(dǎo)出工具類重構(gòu)了一版核心思路就一句話表頭不再寫死在注解里而是運(yùn)行時(shí)動(dòng)態(tài)傳入。做完之后發(fā)現(xiàn)這個(gè)改動(dòng)帶來的一連串收益遠(yuǎn)超預(yù)期今天把整個(gè)設(shè)計(jì)和實(shí)現(xiàn)過程完整記錄一下。這篇內(nèi)容主要面向做 Java 后端、經(jīng)常要和 Excel 導(dǎo)出打交道的朋友。如果你還在用硬編碼表頭的方式寫導(dǎo)出每次需求變更都要發(fā)版那這篇文章正好能解決你的問題。我會(huì)從頭到尾講清楚為什么表頭要?jiǎng)討B(tài)化、工具類怎么設(shè)計(jì)、核心代碼怎么落地以及我在實(shí)現(xiàn)過程中踩過的各種坑。1. 為什么表頭非要?jiǎng)討B(tài)不可從一次改到煩的需求說起1.1 運(yùn)營一句話后端改半天做后臺(tái)系統(tǒng)的同學(xué)應(yīng)該都有這種經(jīng)歷。運(yùn)營同學(xué)跑過來說這個(gè)用戶列表的導(dǎo)出能不能把最后登錄時(shí)間放在手機(jī)號(hào)前面你看了看代碼實(shí)體類上的ExcelProperty(value 手機(jī)號(hào))和ExcelProperty(value 最后登錄時(shí)間)順序?qū)懰懒说谜{(diào)注解順序重新發(fā)版。好不容易上線了運(yùn)營又說現(xiàn)在不看手機(jī)號(hào)了幫我換成注冊(cè)來源吧。你又得改注解、提測、發(fā)版。一次兩次還行一個(gè)月來五次誰受得了后來運(yùn)營又提了一個(gè)更復(fù)雜的需求不同的人打開導(dǎo)出頁面看到的列不一樣。管理員要看手機(jī)號(hào)普通運(yùn)營不能看手機(jī)號(hào)只讓看脫敏后的用戶名和注冊(cè)時(shí)間。這種需求靠注解就真的沒法實(shí)現(xiàn)了因?yàn)橥粋€(gè)實(shí)體類不可能同時(shí)對(duì)應(yīng)多套表頭結(jié)構(gòu)。你得寫兩個(gè)實(shí)體類各寫一套注解加一個(gè)場景再加一個(gè)類。1.2 注解寫死表頭的三個(gè)核心痛點(diǎn)我把用注解方式做導(dǎo)出的痛點(diǎn)梳理了一下歸根結(jié)底是這三條。第一表頭變更必須改代碼發(fā)版。這是最直接的痛。表頭本質(zhì)上是一個(gè)需求層面的東西業(yè)務(wù)方改表頭跟改頁面上的文案一樣頻繁把這種高頻變化的東西硬編碼進(jìn)代碼里等于每次變更都要走一遍完整的開發(fā)流程。第二一個(gè)實(shí)體類只能綁一套表頭。你想讓同一個(gè)查詢結(jié)果導(dǎo)出成兩種不同列組合的 Excel用注解就非常別扭。要么寫兩個(gè)實(shí)體類要么導(dǎo)出前先做一遍字段映射把實(shí)體轉(zhuǎn)成另一個(gè)結(jié)構(gòu)非常繁瑣。第三復(fù)雜表頭實(shí)現(xiàn)成本高。像用戶信息這個(gè)大分類下面掛姓名和年齡兩個(gè)子列這種多層合并表頭用注解雖然也能做但寫起來很繞需要額外定義一堆內(nèi)部類。等你想支持運(yùn)行時(shí)用戶自己選列注解這套玩法就徹底走不通了。1.3 動(dòng)態(tài)表頭解決的其實(shí)是響應(yīng)變化的問題動(dòng)態(tài)表頭這個(gè)詞聽起來挺玄乎本質(zhì)上就是把表頭長什么樣這個(gè)決策時(shí)機(jī)從編譯期推遲到運(yùn)行時(shí)。你不再告訴代碼表頭永遠(yuǎn)是這三列而是讓調(diào)用方在調(diào)用導(dǎo)出方法的時(shí)候把想要的表頭結(jié)構(gòu)傳進(jìn)來。表頭想變調(diào)用方改一下傳參就行導(dǎo)出工具類一行代碼都不用改。這個(gè)思路和依賴注入其實(shí)是一個(gè)道理把變化的部分從穩(wěn)定的部分中剝離出來。穩(wěn)定的部分是我怎么生成一個(gè) Excel 文件變化的部分是表頭長什么樣、數(shù)據(jù)有哪些列。工具類負(fù)責(zé)處理穩(wěn)定的部分動(dòng)態(tài)表頭負(fù)責(zé)承載變化的部分。這樣一來任何表頭層面的調(diào)整都只是調(diào)用方的參數(shù)變化不會(huì)再波及導(dǎo)出的底層代碼。2. 需求邊界一個(gè)動(dòng)態(tài)表頭導(dǎo)出工具類到底要做到什么程度2.1 先列清楚功能需求清單動(dòng)手寫代碼之前我先把需求邊界劃清楚。如果只說支持動(dòng)態(tài)修改表頭很容易做成一個(gè)四不像所以我把工具類需要支持的能力列了個(gè)清單。表頭列表由調(diào)用方傳入不依賴實(shí)體類上的注解想導(dǎo)哪些列、列名叫什么全部由參數(shù)決定。支持多層合并表頭即一個(gè)父列下掛多個(gè)子列這是實(shí)際業(yè)務(wù)里最常用的復(fù)雜表頭形態(tài)。數(shù)據(jù)行和表頭列順序嚴(yán)格對(duì)應(yīng)調(diào)用方按表頭順序逐列給數(shù)據(jù)。支持大數(shù)據(jù)量分批寫入不能因?yàn)閷?dǎo)出 10 萬行數(shù)據(jù)就把堆內(nèi)存打滿。不綁定具體業(yè)務(wù)模型任何業(yè)務(wù)都能復(fù)用同一個(gè)工具類。有了這份清單工具類的定位就清楚了它不是一個(gè)用戶導(dǎo)出工具也不是訂單導(dǎo)出工具而是一個(gè)通用的Excel 導(dǎo)出底座。2.2 技術(shù)選型為什么選 EasyExcel 而不是原生 POI這個(gè)工具類底層我用的是阿里開源的 EasyExcel。沒有從零基于 POI 手寫原因很現(xiàn)實(shí)EasyExcel 在 POI 之上封裝了很多易用性和內(nèi)存優(yōu)化尤其是SAX模式逐行讀寫的設(shè)計(jì)能顯著降低大數(shù)據(jù)量導(dǎo)出時(shí)內(nèi)存的占用這在后文踩坑部分我會(huì)詳細(xì)對(duì)比數(shù)據(jù)。易用性上EasyExcel 天然支持把表頭定義成ListListString傳入這正好是動(dòng)態(tài)表頭需要的形態(tài)。原生 POI 要自己創(chuàng)建 Row 和 Cell 去拼表頭代碼量會(huì)翻一倍。我整理了一個(gè)簡單對(duì)比當(dāng)時(shí)就是基于這個(gè)對(duì)比鎖定的 EasyExcel對(duì)比項(xiàng)原生 POIEasyExcel表頭動(dòng)態(tài)化便利度需要手動(dòng)操作 Cell直接傳入 List 結(jié)構(gòu)開箱即用5 萬行數(shù)據(jù)的粗略內(nèi)存占用較高容易 OOM明顯更低實(shí)測比較穩(wěn)API 易用性代碼較多心智負(fù)擔(dān)重封裝度高配置清晰社區(qū)活躍度穩(wěn)定但更新慢國內(nèi)企業(yè)使用廣泛資料多2.3 動(dòng)態(tài)表頭模式的邊界條件這里有一點(diǎn)必須先說清楚動(dòng)態(tài)表頭模式下注解自動(dòng)映射的能力就廢了。你用ExcelProperty綁定實(shí)體類字段時(shí)EasyExcel 會(huì)自動(dòng)把對(duì)象屬性和列對(duì)應(yīng)起來但一旦表頭改成運(yùn)行時(shí)傳入的ListListString數(shù)據(jù)部分就必須配套改成ListListObject——外層 List 代表一行記錄內(nèi)層 List 按表頭順序存放這一行的每個(gè)單元格的值。順序一旦錯(cuò)位數(shù)據(jù)就會(huì)填到錯(cuò)誤的列下面這在第 5 部分踩坑里我會(huì)詳細(xì)展開。另外動(dòng)態(tài)表頭模式下默認(rèn)的單元格樣式會(huì)變得比較原始比如表頭沒有加粗、內(nèi)容不做居中。要處理這個(gè)問題需要額外的樣式 Handler 或者策略類并不會(huì)因?yàn)橛昧?EasyExcel 就自動(dòng)帶過來。3. 整體設(shè)計(jì)先畫清楚主流程再寫代碼3.1 工具類的核心結(jié)構(gòu)整個(gè)工具類的設(shè)計(jì)我分成三個(gè)部分一個(gè)對(duì)外暴露的靜態(tài)方法入口ExcelExportUtils、一個(gè)承載表頭結(jié)構(gòu)的元數(shù)據(jù)模型、以及底層的寫入執(zhí)行流程。沒有引入 Spring 依賴純 JDK EasyExcel這樣不管你是 Spring Boot 項(xiàng)目還是普通 Java 項(xiàng)目都能直接用。對(duì)外入口我設(shè)計(jì)成兩個(gè)重載方法。第一個(gè)方法接收完整的數(shù)據(jù)集合適合中小數(shù)據(jù)量場景一次性把表頭和數(shù)據(jù)傳給工具類第二個(gè)方法接收一個(gè)分批獲取數(shù)據(jù)的函數(shù)式接口適合大數(shù)據(jù)量場景工具類內(nèi)部按頁調(diào)用這個(gè)接口拿數(shù)據(jù)并批量寫入避免一次性把全量數(shù)據(jù)加載進(jìn)內(nèi)存。3.2 表頭數(shù)據(jù)結(jié)構(gòu)怎么定動(dòng)態(tài)表頭的核心是表頭的數(shù)據(jù)結(jié)構(gòu)。我選擇了ListListString這個(gè)結(jié)構(gòu)一開始可能有點(diǎn)繞我舉個(gè)例子。假設(shè)我要生成一個(gè)這樣的表頭| 序號(hào) | 用戶信息 | 注冊(cè)信息 | | | 姓名 | 年齡 | 注冊(cè)時(shí)間 |對(duì)應(yīng)到ListListString就是ListListString headList new ArrayList(); // 第一列只有一層占兩行 headList.add(Arrays.asList(序號(hào))); // 第二列父列用戶信息子列姓名 headList.add(Arrays.asList(用戶信息, 姓名)); // 第三列父列用戶信息子列年齡 headList.add(Arrays.asList(用戶信息, 年齡)); // 第四列父列注冊(cè)信息子列注冊(cè)時(shí)間 headList.add(Arrays.asList(注冊(cè)信息, 注冊(cè)時(shí)間));內(nèi)層 List 的長度代表這個(gè)列跨幾層同一父列下的子列 EasyExcel 會(huì)自動(dòng)幫你合并單元格。這個(gè)數(shù)據(jù)結(jié)構(gòu)是 EasyExcel 官方支持的動(dòng)態(tài)表頭寫法理解起來也不難外層一個(gè)元素是一整列內(nèi)層的字符串從上到下就是這一列從父級(jí)到子級(jí)的表頭內(nèi)容。3.3 導(dǎo)出主流程工具類內(nèi)部的主流程其實(shí)很簡潔。第一步根據(jù)文件名和響應(yīng)對(duì)象初始化ExcelWriter第二步用傳入的headList構(gòu)建WriteSheet第三步寫入數(shù)據(jù)第四步調(diào)用finish方法把緩沖區(qū)的內(nèi)容刷到輸出流并釋放資源。整個(gè)過程最難的不是代碼而是調(diào)參和防坑。在第 4 部分我會(huì)先給出完整可用的實(shí)現(xiàn)代碼第 5 部分再集中講我踩過的坑這樣你在使用的時(shí)候遇到問題可以回頭對(duì)照。4. 動(dòng)態(tài)表頭的核心實(shí)現(xiàn)直接給可落地的工具類代碼4.1 基礎(chǔ)版本一次性傳入表頭和數(shù)據(jù)先給一個(gè)最直接的版本適用于大多數(shù)中小數(shù)據(jù)量的導(dǎo)出場景。package com.example.excel; import com.alibaba.excel.EasyExcel; import com.alibaba.excel.ExcelWriter; import com.alibaba.excel.write.metadata.WriteSheet; import com.alibaba.excel.write.style.HorizontalCellStyleStrategy; import org.apache.poi.ss.usermodel.HorizontalAlignment; import org.apache.poi.ss.usermodel.IndexedColors; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import java.util.List; /** * Excel 導(dǎo)出工具類核心特性動(dòng)態(tài)表頭。 * 表頭結(jié)構(gòu)由調(diào)用方傳入 ListListString不綁定任何實(shí)體類注解。 */ public final class ExcelExportUtils { private ExcelExportUtils() { } /** * 導(dǎo)出 Excel一次性寫入全部數(shù)據(jù)適合中小數(shù)據(jù)量。 * * param response HTTP 響應(yīng)對(duì)象 * param fileName 導(dǎo)出文件名不需要帶 .xlsx 后綴 * param sheetName Sheet 名稱 * param headList 動(dòng)態(tài)表頭外層 List 是一列內(nèi)層 List 從父級(jí)到子級(jí)排列 * param dataList 數(shù)據(jù)行每行 List 的元素順序必須與 headList 的列順序一致 */ public static void exportWithData(HttpServletResponse response, String fileName, String sheetName, ListListString headList, ListListObject dataList) throws IOException { // 1. 設(shè)置 HTTP 響應(yīng)頭讓瀏覽器識(shí)別為下載 response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setCharacterEncoding(utf-8); String encodedFileName URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString()) .replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment;filename*utf-8 encodedFileName); // 2. 構(gòu)建樣式策略 HorizontalCellStyleStrategy styleStrategy buildDefaultStyleStrategy(); // 3. 寫入并釋放資源 ExcelWriter excelWriter EasyExcel.write(response.getOutputStream()).build(); WriteSheet writeSheet EasyExcel.writerSheet(sheetName).head(headList).build(); excelWriter.write(dataList, writeSheet); excelWriter.finish(); } /** * 構(gòu)建默認(rèn)樣式表頭灰底加粗居中內(nèi)容居中。 */ private static HorizontalCellStyleStrategy buildDefaultStyleStrategy() { // 表頭樣式 WriteCellStyle headStyle new WriteCellStyle(); headStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex()); headStyle.setHorizontalAlignment(HorizontalAlignment.CENTER); WriteFont headFont new WriteFont(); headFont.setBold(true); headFont.setFontHeightInPoints((short) 11); headStyle.setWriteFont(headFont); // 數(shù)據(jù)行樣式 WriteCellStyle contentStyle new WriteCellStyle(); contentStyle.setHorizontalAlignment(HorizontalAlignment.CENTER); return new HorizontalCellStyleStrategy(headStyle, contentStyle); } }這里有幾個(gè)細(xì)節(jié)需要說明一下。響應(yīng)頭里的filename*utf-8是解決中文文件名亂碼的標(biāo)準(zhǔn)寫法我一開始直接用filename加 URL 編碼后的文件名發(fā)現(xiàn)部分瀏覽器會(huì)把文件名里的%E6%9F%90這種字符直接顯示出來用filename*配合URLEncoder編碼后就正常了。另外ExcelWriter的finish()方法一定要在 finally 或者正常流程末尾調(diào)用它會(huì)觸發(fā)流資源的釋放漏掉的話會(huì)導(dǎo)致導(dǎo)出的文件損壞、打不開。4.2 大數(shù)據(jù)量版本分批拉取邊查邊寫一次性傳入所有數(shù)據(jù)雖然簡單但假如你要導(dǎo)出的是幾十萬行用戶數(shù)據(jù)把所有數(shù)據(jù)先查出來放到內(nèi)存里再傳給工具類內(nèi)存很容易扛不住。EasyExcel 的優(yōu)勢在于它可以分批寫入每批寫完就釋放內(nèi)存壓力很小。我設(shè)計(jì)了一個(gè)函數(shù)式接口DataPageProvider由調(diào)用方實(shí)現(xiàn)分批查詢邏輯FunctionalInterface public interface DataPageProvider { /** * 獲取一頁數(shù)據(jù)。 * * param pageNum 頁碼從 1 開始 * param pageSize 每頁行數(shù) * return 當(dāng)前頁數(shù)據(jù)列表如果沒有更多數(shù)據(jù)返回 null 或空集合 */ ListListObject fetch(int pageNum, int pageSize); }然后增加一個(gè)分批導(dǎo)出的重載方法public static void exportByPage(HttpServletResponse response, String fileName, String sheetName, ListListString headList, int pageSize, DataPageProvider dataPageProvider) throws IOException { response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setCharacterEncoding(utf-8); String encodedFileName URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString()) .replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment;filename*utf-8 encodedFileName); HorizontalCellStyleStrategy styleStrategy buildDefaultStyleStrategy(); ExcelWriter excelWriter EasyExcel.write(response.getOutputStream()) .registerWriteHandler(styleStrategy) .build(); WriteSheet writeSheet EasyExcel.writerSheet(sheetName).head(headList).build(); int pageNum 1; while (true) { ListListObject pageData dataPageProvider.fetch(pageNum, pageSize); if (pageData null || pageData.isEmpty()) { break; } excelWriter.write(pageData, writeSheet); pageNum; // 每批數(shù)據(jù)用完即可被 GC內(nèi)存只保留當(dāng)前批的數(shù)據(jù) } excelWriter.finish(); }這樣調(diào)用方就可以用 lambda 把 MyBatis-Plus 的分頁查詢邏輯傳進(jìn)來比如ExcelExportUtils.exportByPage(response, 用戶導(dǎo)出, 用戶, headList, 5000, (pageNum, pageSize) - { PageUserDO page userMapper.selectPage(new Page(pageNum, pageSize), null); if (page.getRecords().isEmpty()) { return null; } return page.getRecords().stream() .map(user - Arrays.asList( user.getId(), user.getName(), user.getPhone() )) .collect(Collectors.toList()); });這種方式下無論導(dǎo)出的數(shù)據(jù)量多大內(nèi)存里同一時(shí)刻只保留一個(gè) pageSize 批次的數(shù)據(jù)極大的降低了 OOM 概率。4.3 一個(gè)復(fù)雜的動(dòng)態(tài)表頭實(shí)際調(diào)用示例為了讓你對(duì)動(dòng)態(tài)表頭有一個(gè)直觀的概念我放一個(gè)真實(shí)場景的調(diào)用代碼。假設(shè)運(yùn)營后臺(tái)需要導(dǎo)出一份帶合并表頭的用戶分析表ListListString headList new ArrayList(); headList.add(Collections.singletonList(序號(hào))); headList.add(Arrays.asList(用戶信息, 姓名)); headList.add(Arrays.asList(用戶信息, 年齡)); headList.add(Arrays.asList(用戶信息, 手機(jī)號(hào))); headList.add(Arrays.asList(行為數(shù)據(jù), 最近登錄時(shí)間)); headList.add(Arrays.asList(行為數(shù)據(jù), 訂單數(shù))); ListListObject dataList new ArrayList(); dataList.add(Arrays.asList(1, 張三, 28, 138****1234, 2025-01-15 10:24:00, 12)); dataList.add(Arrays.asList(2, 李四, 32, 139****5678, 2025-01-14 22:10:00, 5)); ExcelExportUtils.exportWithData(response, 用戶分析報(bào)表, 用戶分析, headList, dataList);這段代碼導(dǎo)出的 Excel 里用戶信息和行為數(shù)據(jù)兩個(gè)父列會(huì)自動(dòng)跨行合并效果和你在 Excel 里手動(dòng)合并單元格是一樣的。運(yùn)營再提我要加一列注冊(cè)來源這個(gè)需求時(shí)你只需要在 headList 和數(shù)據(jù)列表里各加一個(gè)元素工具類一行都不用改。5. 踩坑記錄動(dòng)態(tài)表頭遠(yuǎn)沒有看起來那么簡單5.1 坑一動(dòng)態(tài)表頭下樣式和列寬全部失效第一次跑通動(dòng)態(tài)表頭導(dǎo)出時(shí)導(dǎo)出的文件確實(shí)能打開但表頭灰白的底色沒了字體也不加粗了數(shù)據(jù)全部擠在左側(cè)列寬也是默認(rèn)寬度列名都顯示不全。原因是當(dāng)你通過head(ListListString)傳入表頭時(shí)EasyExcel 不會(huì)自動(dòng)套用基于注解設(shè)計(jì)的樣式策略。解決方式就是我工具類里那套HorizontalCellStyleStrategy但這里有一個(gè)容易忽略的細(xì)節(jié)在分批導(dǎo)出版本里一定要通過excelWriter的registerWriteHandler(styleStrategy)來注冊(cè)樣式而不是在writerSheet之后才傳。我之前在測試時(shí)把樣式策略放在writerSheet(...).build()后面?zhèn)魅虢Y(jié)果數(shù)據(jù)行有樣式、表頭沒有樣式排查了半天才意識(shí)到注冊(cè)順序會(huì)影響樣式作用范圍。列寬的坑也值得一提。如果你不對(duì)列寬做任何處理動(dòng)態(tài)表頭模式下所有列寬都是默認(rèn)值中文表頭幾乎一定顯示不全。最簡單的方案是給 excelWriter 注冊(cè)一個(gè)LongestMatchColumnWidthStyleStrategy它會(huì)讓列寬自動(dòng)匹配本列最長的內(nèi)容包括表頭和數(shù)據(jù)。但這個(gè)策略在數(shù)據(jù)量大的時(shí)候會(huì)遍歷每一行的內(nèi)容來計(jì)算寬度性能有損耗。如果數(shù)據(jù)量特別大建議手動(dòng)按業(yè)務(wù)場景指定列寬而不是用自適應(yīng)策略。5.2 坑二表頭和數(shù)據(jù)列順序錯(cuò)位數(shù)據(jù)填到錯(cuò)誤的列動(dòng)態(tài)表頭模式下最容易踩的坑就是這個(gè)headList 的順序和 dataList 內(nèi)層 List 的順序必須完全一致否則數(shù)據(jù)會(huì)錯(cuò)位。這不是工具類能幫你兜底的因?yàn)楣ぞ哳惛静恢滥愕臉I(yè)務(wù)字段叫什么它只認(rèn)順序。我自己的排查經(jīng)驗(yàn)是先在調(diào)用方寫一個(gè)簡單的斷言方法確認(rèn) headList 的 size 和 dataList 每一行的 size 相等如果不相等直接拋異常不要等導(dǎo)出完才發(fā)現(xiàn)。耗時(shí)不多但能避免大量低級(jí)錯(cuò)誤。如果用到分批導(dǎo)出還需要注意每一批數(shù)據(jù)行的列數(shù)都要一致否則后續(xù)的行會(huì)發(fā)生錯(cuò)位。另外DataPageProvider 分批查詢時(shí)每一頁返回的數(shù)據(jù)行數(shù)不能超過 pageSize否則會(huì)出現(xiàn)寫入亂序的問題。這個(gè)在實(shí)現(xiàn)查詢函數(shù)時(shí)稍微注意一下就行分頁查詢框架一般不會(huì)出現(xiàn)這種問題但如果是自己寫 SQL 的就要多留個(gè)心眼。5.3 坑三單元格內(nèi)容以 或 開頭被 Excel 當(dāng)成公式導(dǎo)出用戶備注時(shí)如果用戶備注是逾期用戶或者所有人Excel 打開文件的時(shí)候會(huì)把逾期用戶解析成公式導(dǎo)致單元格報(bào)錯(cuò)或顯示異常。這個(gè)問題不是 EasyExcel 特有的用 POI 也一樣會(huì)遇到屬于 Excel 本身的安全機(jī)制。解決方式是在寫入數(shù)據(jù)前對(duì)單元格內(nèi)容做一次前導(dǎo)字符轉(zhuǎn)義。做一個(gè)簡單的字符串處理private static Object safeCellValue(Object value) { if (value instanceof String) { String str (String) value; if (str.startsWith() || str.startsWith() || str.startsWith()) { return str; } } return value; }注意這個(gè)方法只對(duì)字符串類型做處理數(shù)字、日期等類型直接原樣返回。我在工具類的 write 環(huán)節(jié)之前統(tǒng)一對(duì)數(shù)據(jù)行做一遍清洗和表頭校驗(yàn)放在一起。這個(gè)小函數(shù)幫我避免了好幾次線上數(shù)據(jù)問題。5.4 坑四ExcelWriter 的 finish() 漏調(diào)用導(dǎo)致文件損壞實(shí)際生產(chǎn)環(huán)境里如果導(dǎo)出過程中業(yè)務(wù)代碼拋了異常比如數(shù)據(jù)庫查詢超時(shí)ExcelWriter 的輸出流沒有被正確關(guān)閉用戶下載到的就是一個(gè)損壞的文件。有人會(huì)想我用 try-with-resources 不就行了但 ExcelWriter 實(shí)現(xiàn)了 Closeable 接口可以放進(jìn) try-with-resources 里不過 EasyExcel 更推薦在 finally 里調(diào)用 finish()因?yàn)?finish() 不僅僅是關(guān)閉流還會(huì)做一些收尾工作。以我的經(jīng)驗(yàn)最穩(wěn)妥的寫法是這樣ExcelWriter excelWriter null; try { excelWriter EasyExcel.write(outputStream).build(); // ... 寫入邏輯 } finally { if (excelWriter ! null) { excelWriter.finish(); } }如果是在 Web 導(dǎo)出場景異常情況下還需要在 finally 里調(diào)用 response.reset()防止已經(jīng)寫出去的部分字節(jié)導(dǎo)致瀏覽器解析錯(cuò)誤。這個(gè)細(xì)節(jié)我可以說是踩了三次才長記性。5.5 坑五動(dòng)態(tài)表頭模式下日期格式顯示成一串?dāng)?shù)字如果你在數(shù)據(jù)列表里傳的是Date類型默認(rèn)情況下 EasyExcel 會(huì)按內(nèi)置格式輸出但如果傳的是 LocalDateTime 或者時(shí)間戳字符串顯示效果就不可控。我在工具類里沒有做強(qiáng)制轉(zhuǎn)換因?yàn)橐笳{(diào)用方自己控制數(shù)據(jù)格式。但為了統(tǒng)一體驗(yàn)我在實(shí)際項(xiàng)目中會(huì)讓調(diào)用方把時(shí)間類數(shù)據(jù)先格式化成字符串這樣最簡單可控也不容易踩明明傳了時(shí)間卻顯示成數(shù)字的坑。6. 進(jìn)階玩法從動(dòng)態(tài)表頭走向表頭配置化6.1 表頭定義搬進(jìn) JSON 或 YAML 配置動(dòng)態(tài)表頭解決了不用改代碼改表頭的問題但如果你還是把 headList 的構(gòu)建邏輯寫死在調(diào)用方代碼里本質(zhì)上也只是把改注解變成了改 Java 代碼。要讓表頭變更徹底脫離開發(fā)得把表頭定義搬到配置文件中。比如在 resources 目錄下維護(hù)一個(gè)export-head.json內(nèi)容大致是{ columns: [ { title: [用戶信息, 姓名], dataIndex: name }, { title: [用戶信息, 年齡], dataIndex: age }, { title: [行為數(shù)據(jù), 訂單數(shù)], dataIndex: orderCount } ] }運(yùn)行時(shí)通過 Jackson 把這個(gè)文件讀成配置對(duì)象再轉(zhuǎn)換成 EasyExcel 需要的ListListString。數(shù)據(jù)部分也需要配套改造從寫死每列的值變成根據(jù) dataIndex 從 Map 或?qū)ο罄锶?duì)應(yīng)字段的值這一步可以結(jié)合反射或直接把查詢結(jié)果轉(zhuǎn)成 Map 來做。這樣做的好處非常明顯運(yùn)營想加一列只要告訴運(yùn)維改一下 JSON 文件重啟都不需要配合配置中心就能生效。我見過很多大廠的報(bào)表系統(tǒng)就是這么做的——前端配置列后端按配置導(dǎo)出兩邊共用同一套元數(shù)據(jù)。6.2 表頭存數(shù)據(jù)庫做成可維護(hù)的元數(shù)據(jù)比配置文件更進(jìn)一步的做法是把表頭定義存進(jìn)數(shù)據(jù)庫做成一張導(dǎo)出模板表字段大概包含模板編碼、列序號(hào)、父表頭名稱、子表頭名稱、關(guān)聯(lián)的數(shù)據(jù)字段名、是否啟用等。運(yùn)營或者管理員可以在后臺(tái)頁面維護(hù)這張表增刪列、調(diào)整順序都走可視化界面后端導(dǎo)出時(shí)根據(jù)模板編碼查出表頭定義再查數(shù)據(jù)填充。這種方式配合動(dòng)態(tài)表頭工具類非常順手因?yàn)楣ぞ哳愐呀?jīng)沒有固定結(jié)構(gòu)了天然適配從數(shù)據(jù)庫查出什么表頭就導(dǎo)出什么表頭的模式。唯一要注意的是緩存問題表頭配置不要每次都查數(shù)據(jù)庫可以加一層本地緩存配置變更時(shí)再刷新緩存。我實(shí)現(xiàn)的時(shí)候用的是 Caffeine 本地緩存熱點(diǎn)數(shù)據(jù)基本無感知。6.3 多模板管理同一份數(shù)據(jù)多個(gè)導(dǎo)出視角表頭配置化之后很自然就會(huì)進(jìn)化出多模板管理的能力。比如用戶數(shù)據(jù)導(dǎo)出這個(gè)場景可以設(shè)計(jì)用戶基礎(chǔ)信息模板、用戶行為分析模板、運(yùn)營安全審計(jì)模板三個(gè)模板它們對(duì)應(yīng)不同的列組合、不同的表頭層級(jí)。后端導(dǎo)出接口只要多接收一個(gè)模板編碼參數(shù)工具類統(tǒng)一路由到對(duì)應(yīng)模板查配置、取數(shù)據(jù)、導(dǎo)出。這樣做還有一個(gè)額外的收益權(quán)限控制變得簡單了。管理員模板可以看到手機(jī)號(hào)和身份證號(hào)普通運(yùn)營模板看不到權(quán)限校驗(yàn)只需要在返回模板配置之前做一次判斷前端導(dǎo)出按鈕的可見列隨之變化。整個(gè)體系擴(kuò)展起來非常順暢。從我個(gè)人的使用體驗(yàn)來看把表頭做成配置、把導(dǎo)出工具類做成通用底座這個(gè)方向是對(duì)的。它不僅解決了當(dāng)時(shí)運(yùn)營提的選擇性導(dǎo)出需求還讓后續(xù)幾乎所有報(bào)表導(dǎo)出需求變成了配置工作而不是編碼工作。最后再分享一個(gè)建議如果你也在做類似的重構(gòu)不用一步到位就把配置中心、數(shù)據(jù)庫模板全上了。先把工具類的動(dòng)態(tài)表頭能力做好保證它可以通過參數(shù)控制表頭結(jié)構(gòu)后面再逐步把配置來源從硬編碼升級(jí)到 JSON、再到數(shù)據(jù)庫每一步都可以獨(dú)立上線風(fēng)險(xiǎn)可控。這套工具類在我這邊已經(jīng)穩(wěn)定跑了半年多中間經(jīng)歷了多輪表頭調(diào)整一行導(dǎo)出代碼都沒改過這也是我特別想把這段經(jīng)驗(yàn)記錄下來的原因。