Java POI API手册：从入门到精通的全方位指南

一、Java POI概述

Apache POI（Poor Obfuscation Implementation）是Apache软件基金会提供的开源Java API，用于读写Microsoft Office格式文件（如Excel、Word、PowerPoint）。其核心优势在于跨平台性和丰富的功能支持，是企业级文档处理的首选方案。

核心组件模块：

1. HSSF（Horrible SpreadSheet Format）：处理Excel 97-2003（.xls）
2. XSSF（XML SpreadSheet Format）：处理Excel 2007+（.xlsx）
3. HWPF（Horrible Word Processor Format）：处理Word 97-2003（.doc）
4. XWPF（XML Word Processor Format）：处理Word 2007+（.docx）

二、环境配置

<!-- Maven依赖配置 -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.3</version>
</dependency>
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.3</version>
</dependency>

三、Excel操作详解

1. 创建工作簿

// 创建XSSF工作簿（xlsx格式）
Workbook workbook = new XSSFWorkbook();
Sheet sheet = workbook.createSheet("数据报表");
// 设置单元格样式
CellStyle headerStyle = workbook.createCellStyle();
Font font = workbook.createFont();
font.setBold(true);
headerStyle.setFont(font);

2. 数据读写操作

// 写入数据
Row row = sheet.createRow(0);
row.createCell(0).setCellValue("ID");
row.createCell(1).setCellValue("名称");
// 读取数据
Workbook readWorkbook = WorkbookFactory.create(new File("data.xlsx"));
Sheet readSheet = readWorkbook.getSheetAt(0);
readSheet.forEach(row -> {
    row.forEach(cell -> {
        System.out.print(cell + "\t");
    });
});

四、Word文档处理

1. 创建DOCX文档

XWPFDocument document = new XWPFDocument();
XWPFParagraph paragraph = document.createParagraph();
XWPFRun run = paragraph.createRun();
run.setText("POI生成的文档内容");
run.setBold(true);
run.setFontSize(14);

2. 表格处理

XWPFTable table = document.createTable(3, 2);
table.getRow(0).getCell(0).setText("列1");
table.getRow(0).getCell(1).setText("列2");

五、高级特性

1. 内存优化：

   • 使用SXSSFWorkbook处理大数据量（基于滑动窗口机制）
   • 示例：

     SXSSFWorkbook workbook = new SXSSFWorkbook(100); // 保留100行在内存

2. 公式计算：

   cell.setCellFormula("SUM(A1:A10)");
   FormulaEvaluator evaluator = workbook.getCreationHelper().createFormulaEvaluator();
   evaluator.evaluateAll();

3. 图表生成（需要ooxml-schemas依赖）：

   XSSFSheet sheet = workbook.createSheet("ChartSheet");
   XSSFDrawing drawing = sheet.createDrawingPatriarch();
   XSSFClientAnchor anchor = drawing.createAnchor(0, 0, 0, 0, 0, 5, 10, 15);
   XSSFChart chart = drawing.createChart(anchor);

六、异常处理最佳实践

1. 常见异常类型：

   • EncryptedDocumentException：加密文档
   • InvalidFormatException：格式错误
   • IOException：流操作错误

2. 资源释放规范：

   try (Workbook workbook = new XSSFWorkbook();
        FileOutputStream out = new FileOutputStream("output.xlsx")) {
       workbook.write(out);
   } catch (Exception e) {
       logger.error("文档生成失败", e);
   }

七、性能优化指南

1. 批处理模式：

   sheet.setRandomAccessWindowSize(100); // 设置行缓存窗口

2. 样式复用：

   CellStyle sharedStyle = workbook.createCellStyle();
   // 多处单元格应用同一样式对象

3. 事件模型（适用于超大文件）：

   XSSFSheetXMLHandler.SheetContentsHandler handler = new MySheetHandler();
   XSSFReader.SheetIterator iter = (XSSFReader.SheetIterator)reader.getSheetsData();
   new XSSFSheetXMLHandler(styles, strings, handler, false);

八、版本兼容性说明

POI版本	支持Office版本	JDK要求
5.x	Office 2019+	JDK 8+
4.x	Office 2013	JDK 7+
3.x	Office 2007	JDK 6+

九、企业级应用案例

1. 财务报表自动生成系统：

   • 每日定时从数据库提取数据
   • 生成带样式和公式的xlsx文件
   • 自动邮件发送给相关部门

2. 合同批量生成工具：

   • 基于Word模板（使用XWPFDocument）
   • 动态替换占位符
   • 生成PDF副本（集成iText）

十、常见问题解答

Q: 如何处理中文乱码？
A: 确保使用UTF-8编码：

String value = new String(cell.getStringCellValue().getBytes("ISO-8859-1"), "UTF-8");

Q: 如何设置单元格自动换行？
A: 配置单元格样式：

CellStyle wrapStyle = workbook.createCellStyle();
wrapStyle.setWrapText(true);
cell.setCellStyle(wrapStyle);

本手册持续更新，建议开发者定期查阅Apache POI官方文档获取最新API变更信息。通过合理运用POI的各项功能，可显著提升企业文档自动化处理的效率与可靠性。