简介本资源面向Java后端开发者与需要实现数据导出功能的程序员聚焦使用Apache POI在Java中导出Excel这一常见需求。内容围绕从数据库查询数据、构建工作簿、设置表头、填充数据行到保存文件的完整流程展开并给出Maven依赖配置与实体类映射思路适合具备一定Java与JDBC基础、希望快速落地导出模块的中级开发者参考。压缩包共519个文件约567KB以xml配置、class字节码、java源码及sample示例文件为主另含少量yml、log等辅助文件整体结构便于按模块查阅与复用。目前已有388人学习下载。资源提供了可直接借鉴的导出方法实现与扩展方向如样式设置、数据验证与公式计算能帮助读者减少重复造轮子的时间快速搭建稳定的Excel导出能力。1. 从一份 poi_export_excel.zip 说起Java 导出 Excel 到底能省多少事后台管理系统里最容易被低估的活儿就是导出 Excel。产品经理一句“加个导出按钮”落到开发身上往往是一整天的折腾表头合并、单元格样式、大数据量分页、内存溢出随便一个都能让人加班到深夜。我见过不少项目导出功能上线第一天就被运营吐槽“下载下来打不开”“数字变成科学计数法”“日期全是乱码”。这份 poi_export_excel.zip 就是冲着这些痛点来的——它把 Java 生态里最成熟的 Apache POI 封装成一套可直接复用的导出工具覆盖从简单列表到复杂多级表头的常见场景。如果你正在做管理后台、报表系统或者单纯想搞清楚 POI 的 Workbook、Sheet、Cell 到底怎么配合这份源码值得拉下来跑一遍。它不依赖任何重型框架一个 main 方法就能看到导出效果对新手友好对老手也能当脚手架用。2. 技术选型与目录结构为什么是 POI 而不是 EasyExcel2.1 POI 与 EasyExcel 的取舍逻辑Java 导出 Excel 绕不开两个名字Apache POI 和阿里开源的 EasyExcel。EasyExcel 主打低内存、注解驱动写起来确实清爽但它的抽象层比较厚遇到复杂表头合并、自定义样式、公式计算时反而要绕回 POI 的 API。这份源码选择 POI 作为底层原因很直接POI 是 Excel 文件格式的“原教旨”实现HSSF 管 .xlsXSSF 管 .xlsxSXSSF 管超大文件流式写入三套 API 覆盖了从几百行到百万行的全部场景。源码里没有引入 EasyExcel就是为了让使用者看清每一行数据是怎么落到 Cell 里的而不是被注解和监听器遮住视线。常见做法是中小数据量万行以内用 XSSFWorkbook内存占用可接受数据量再大就切 SXSSFWorkbook它会在磁盘上滚动临时文件避免 OOM。这份源码把两种 Workbook 的创建逻辑都封装在工厂类里调用方只需要传一个类型枚举。2.2 目录结构一览解压后是一个标准的 Maven 工程结构不复杂但分层清晰poi_export_excel/ ├── pom.xml ├── src/main/java/ │ ├── com/example/export/ │ │ ├── ExcelExportUtil.java // 核心导出工具类 │ │ ├── ExcelExportConfig.java // 导出配置表头、样式、sheet名 │ │ ├── ExcelWorkbookFactory.java // Workbook 创建工厂 │ │ ├── ExcelStyleBuilder.java // 单元格样式构建器 │ │ └── model/ │ │ └── ExportColumn.java // 列定义模型 │ └── com/example/demo/ │ └── ExportDemo.java // 可运行的示例入口 └── src/main/resources/ └── template/ // 预留的模板文件目录pom.xml 里核心依赖只有两个org.apache.poi:poi-ooxml和org.apache.poi:poi版本建议用 5.x 系列对 .xlsx 的支持更完整。另外引入了commons-lang3做字符串判空slf4j-api做日志门面。没有 Spring、没有 MyBatis保持最小依赖方便嵌入任何项目。2.3 核心模型 ExportColumn 的设计导出功能最怕的是“列定义散落在各处”。这份源码把每一列抽象成 ExportColumn字段包括列标题、字段名对应数据对象的属性、列宽、对齐方式、是否自动换行、日期格式。这样表头顺序、样式、数据映射全部由配置驱动新增一列只需要加一个 ExportColumn 对象不用改导出逻辑。public class ExportColumn { private String title; // 表头显示文字 private String fieldName; // 数据对象中的属性名反射取值 private int width; // 列宽单位是 1/256 字符宽 private HorizontalAlignment align; // 对齐方式 private boolean wrapText; // 是否自动换行 private String dateFormat; // 日期格式化如 yyyy-MM-dd HH:mm:ss // 构造方法、getter/setter 省略 }参数说明width这个单位容易踩坑POI 里setColumnWidth传的是 1/256 个字符宽度比如想设 20 个字符宽要传20 * 256。源码里在 ExcelExportUtil 做了换算调用方直接写 20 就行。fieldName用反射取值所以数据对象可以是任意 POJO不要求实现特定接口。3. 核心导出链路从 List 到 Excel 的完整代码拆解3.1 入口方法 export 的签名与职责ExcelExportUtil 对外只暴露一个 export 方法签名如下public static T void export( ListT data, ListExportColumn columns, ExcelExportConfig config, OutputStream out) throws IOException四个参数分别对应数据列表、列定义、导出配置sheet 名、是否冻结首行、Workbook 类型、输出流。方法内部按“创建 Workbook → 创建 Sheet → 写表头 → 写数据 → 写流 → 关闭资源”的顺序执行。把 OutputStream 作为参数传入是为了让调用方自己决定写到文件还是 HTTP 响应Web 场景下直接传response.getOutputStream()即可。3.2 创建 Workbook 与 SheetWorkbook workbook ExcelWorkbookFactory.create(config.getWorkbookType()); Sheet sheet workbook.createSheet(config.getSheetName()); // 冻结首行方便滚动查看 if (config.isFreezeHeader()) { sheet.createFreezePane(0, 1); }ExcelWorkbookFactory 根据枚举返回 HSSFWorkbook、XSSFWorkbook 或 SXSSFWorkbook。SXSSFWorkbook 需要额外设置new SXSSFWorkbook(100)表示保留最近 100 行在内存其余刷到磁盘。这个 100 是经验值行数越多可以调小但太小会导致频繁 IO。冻结窗格用createFreezePane(0, 1)第一个参数是列分割第二个是行分割0,1 表示冻结第一行。3.3 写表头与样式构建表头样式通过 ExcelStyleBuilder 统一构建避免每个 Cell 重复创建 CellStylePOI 对 CellStyle 数量有限制.xls 最多 4000 个.xlsx 虽然宽松但也不宜滥用。CellStyle headerStyle ExcelStyleBuilder.buildHeaderStyle(workbook); Row headerRow sheet.createRow(0); for (int i 0; i columns.size(); i) { ExportColumn col columns.get(i); Cell cell headerRow.createCell(i); cell.setCellValue(col.getTitle()); cell.setCellStyle(headerStyle); sheet.setColumnWidth(i, col.getWidth() * 256); // 字符宽转 POI 单位 }逻辑说明表头固定在第 0 行列宽在这里一次性设置。buildHeaderStyle内部设置了加粗、居中、背景色、边框。注意 CellStyle 必须由 Workbook 创建不能跨 Workbook 复用否则会抛异常。3.4 反射填充数据行for (int rowIdx 0; rowIdx data.size(); rowIdx) { T item data.get(rowIdx); Row row sheet.createRow(rowIdx 1); // 从第 1 行开始避开表头 for (int colIdx 0; colIdx columns.size(); colIdx) { ExportColumn col columns.get(colIdx); Cell cell row.createCell(colIdx); Object value ReflectUtil.getFieldValue(item, col.getFieldName()); fillCell(cell, value, col, workbook); } }ReflectUtil.getFieldValue是源码里自己封装的反射工具支持从父类字段取值也支持嵌套属性如user.name。fillCell根据值的类型分派String 直接 setCellValueNumber 走 setCellValue(double)Date 先格式化再写入null 写空字符串。日期格式从 ExportColumn 的 dateFormat 取如果为空则用默认的yyyy-MM-dd。3.5 输出与资源关闭try { workbook.write(out); out.flush(); } finally { workbook.close(); // SXSSFWorkbook 会清理临时文件 }注意 SXSSFWorkbook 的 close 会删除磁盘临时文件不调用会导致临时文件堆积。另外workbook.write之后不要立即关 OutputStreamWeb 场景下由容器管理。如果是写文件用 try-with-resources 包住 FileOutputStream。4. 避坑与排查导出 Excel 时最容易翻车的五个点4.1 现象下载的文件打开提示“格式不正确”原因通常是 Content-Type 或文件名编码不对。Web 导出时如果响应头写成application/octet-stream但文件名含中文没做 URL 编码浏览器会截断文件名导致扩展名丢失。解决设置response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)文件名用URLEncoder.encode(fileName, UTF-8)处理并加上response.setHeader(Content-Disposition, attachment;filename encodedName)。4.2 现象大数据量导出时 OOM原因是用 XSSFWorkbook 一次性把所有行放在内存。解决数据超过 5 万行时切换到 SXSSFWorkbook并设置合适的行窗口。源码里通过 ExcelExportConfig 的 workbookType 字段控制调用方根据数据量选择。另外注意 SXSSF 不支持getRow读取已刷盘的行如果导出逻辑里有回读操作要避开。4.3 现象数字变成科学计数法或日期变成数字原因是 Cell 类型没设对。POI 默认 createCell 是 Blank 类型setCellValue(String) 会变成文本setCellValue(double) 才是数字。日期如果直接 setCellValue(Date) 而不设 DataFormatExcel 会显示成数字序列。解决在 fillCell 里对 Date 类型先cell.setCellValue(formattedString)或者设置CellStyle.setDataFormat(workbook.createDataFormat().getFormat(yyyy-MM-dd))再 setCellValue(date)。源码采用前者更直观。4.4 现象表头合并后样式错乱原因是对合并区域内的非左上角单元格也设置了样式。POI 的合并单元格addMergedRegion只保留左上角的值和样式其他单元格的值会被忽略但样式可能残留。解决合并前先创建所有单元格只给左上角设值和样式其余留空。源码里多级表头的处理逻辑是先算好合并区间再统一写值。4.5 现象SXSSFWorkbook 写完文件后临时文件没删原因是没调用workbook.dispose()或close()。SXSSF 会在java.io.tmpdir下建临时文件JVM 退出前不清理会占满磁盘。解决在 finally 块里调用workbook.close()它会触发 dispose。如果用的是 POI 4.x 以下版本需要手动调dispose()。5. 二次开发与改造把这套工具接进你的项目5.1 接入 Spring Boot 的两种姿势第一种是当工具类用把 ExcelExportUtil 和 model 包直接拷进项目在 Controller 里组装 List 和 columns 后调用 export。适合导出场景不多的项目。第二种是做成 Starter把 ExcelExportUtil 注册成 Bean通过ConfigurationProperties读取默认配置如默认 sheet 名、默认列宽再用自定义注解ExcelColumn标注在 DTO 字段上启动时扫描注解生成 ExportColumn 列表。这样业务代码只需要返回 List 导出逻辑完全解耦。5.2 扩展多级表头与合并单元格源码目前只支持单行表头。要支持多级表头需要在 ExcelExportConfig 里增加一个headerDepth字段然后改造写表头的逻辑先根据 columns 的层级关系算出每个表头单元格的起止行列再调用sheet.addMergedRegion(new CellRangeAddress(firstRow, lastRow, firstCol, lastCol))。注意合并区域的坐标是 0-based且不能重叠。一个实用技巧是把表头定义成一个树形结构每个节点带 title 和 children递归写入。5.3 用模板导出替代硬编码样式如果样式要求复杂比如带公司 logo、固定页脚、多个 sheet硬编码 CellStyle 会很痛苦。更优雅的做法是准备一个 .xlsx 模板文件用workbook WorkbookFactory.create(new FileInputStream(template))加载然后定位到指定 sheet 和起始行只填充数据不动样式。源码的 resources/template 目录就是为此预留的。改造时注意模板文件不要放在 jar 包内用getResourceAsStream读因为 POI 需要随机访问流式读取大模板可能失败建议解压到临时文件再读。5.4 验证改造是否成功的三个检查点改完之后别急着上线按这三步验一遍第一用wb.getNumberOfSheets()和sheet.getLastRowNum()确认 sheet 数和行数符合预期第二用cell.getCellType()检查关键列的类型数字列必须是 NUMERIC日期列必须是 NUMERIC 且带 DataFormat第三用 Excel 打开后按 CtrlEnd 看是否跳到了预期区域如果跳到了很远的空白单元格说明有多余的样式或空行被创建了。5.5 一个我踩过的坑早些年做报表导出为了图省事在循环里workbook.createCellStyle()结果 .xls 格式导出 3000 行就抛IllegalStateException: The maximum number of cell styles was exceeded。后来改成在循环外创建好所有样式循环内只cell.setCellStyle(style)问题消失。从那以后我每次写导出逻辑都强制把 CellStyle 的创建提到循环外并且用workbook.getNumCellStyles()打印一下数量超过 100 就警觉。希望这个习惯也能帮到你。本文还有配套的精品资源点击获取
