JSF 環境下基於 POI 實現 Excel 導出下載完整代碼實戰

需求背景

B/S 系統中大量報表導出 Excel 是剛需。技術成熟但在 JSF 架構下較繞 (資源少、學習曲線陡)。項目需求驅動，改造大量代碼後實現 JSF 下生成 Excel 並客戶端下載。使用 Apache POI (Jakarta 子項目，處理 OLE2)。

核心工具類 ExcelUtils 設計

• 構造函數創建 HSSFWorkbook。
• outputExcel(String excelName, List list, String[] firstRowValue)：創建表頭、填充數據、下載。
• createSheet()：建 Sheet、表頭行、粗體樣式、UTF-16 編碼寫入表頭。
• setValueToRow()：遍歷 List 填充數據行，獲取 JSF/Servlet 上下文取絕對路徑寫入文件。
• downloadFile() 關鍵改造：通過 FacesContext 獲取 HttpServletResponse，設置 Header (Content-disposition: attachment)、Content-Length、Content-Type，流式輸出文件字節，最後 FacesContext.responseComplete() 終止 JSF 生命周期防止頁面渲染干擾。

代碼關鍵點註解

// 獲取 JSF 上下文
FacesContext context = FacesContext.getCurrentInstance();
// 獲取 ServletContext 取絕對路徑
ServletContext servletContext = (ServletContext) context.getExternalContext().getContext();
String excelName = servletContext.getRealPath("/UploadFile") + "/" + fileName;

// 寫入文件
FileOutputStream fileOut = new FileOutputStream(excelName);
wb.write(fileOut);

// 下載響應
HttpServletResponse response = (HttpServletResponse) FacesContext.getCurrentInstance().getExternalContext().getResponse();
ServletOutputStream out = response.getOutputStream();
response.setHeader("Content-disposition", "attachment; filename=" + fileName);
response.setContentLength((int) file.length());
response.setContentType("application/x-download");
// 流式複製
byte[] buffer = new byte[1024];
FileInputStream fis = new FileInputStream(file);
int len;
while ((len = fis.read(buffer)) > 0) out.write(buffer, 0, len);
// 關鍵：終止 JSF 渲染
FacesContext.getCurrentInstance().responseComplete();

已知不足與改進方向

• 文件名不支持中文：Header 中 filename 參數需 URL 編碼 (如 URLEncoder.encode(fileName, "UTF-8")) 並處理瀏覽器差異 (IE/Edge 需特殊處理)。
• 臨時文件寫磁盤再讀出，可改用 ByteArrayOutputStream 內存流直接輸出，避免 I/O 開銷與臨時文件清理。
• 大數據量導出應考慮 SXSSF (流式 API) 防 OOM。

完整代碼結構

包含 package、import、類定義、構造器、公共導出方法、私有輔助方法、下載方法、異常處理。可直接複製到項目 mj.util.Excel 包下使用。