apache POI 万字总结：满足你对报表一切幻想

背景

国庆期间接了个兼职，处理机构的几张Excel报表。初次沟通，感觉挺简单，接入Easyexcel(FastExcel)，然后拼lamda表达式就跑出来了。不过毕竟工作了这些年，感觉没这么简单。后面找业务方详细聊了一次，将需求落到纸面上。逐行研究了下BRD，有点挠头，跑数加各种样式，兼容新老版本，老方案是不行了。综合对比，最终选了老牌的 Apache POI 实现，下面说下为啥选POI，还有POI怎么用，包含样式、公式、动态表头、安全防范、百万级数据导入导出等功能。

一、技术选型

如果实现该功能，客户端可以（装个app），服务端也可行。考虑到电脑性能和未来大量的扩展升级，首先排除客户端。服务端有各种语言可以解析excel，但是功能参差不齐，下面对比下比较熟悉的几种（像C#不熟悉，直接排除）：Apache POI (Java)，Apache POI (Java)，FastExcel (Java/Kotlin)，Python (openpyxl / pandas / xlrd/xlwt)，PHP (PhpSpreadsheet / ExcelReader)，Rust (calamine / rust_xlsxwriter)（咋还有rust？因为前面写了几篇这块文章，顺手带上）。

• 从上表可以看出Apache POI功能最全面，几乎涵盖所有功能，其他各有优劣。
• 从需求方提供的excel示例文件看，有xls和xlsx格式的，内容里面有公式。每个表数据量不大，但是样式要求高，比如宋体、10号等。文件来源也需要一些防护，毕竟是外部给的。未来可能需要支持参数校验等等。不难看出，只有apache POI能胜任。下面整理下POI入门文档，内容参考POI官网。

二、POI入门与进阶

1、添加POI依赖

本文基于springboot 2.7.18版本

1<dependency>
2        <groupId>org.apache.poi</groupId>
3        <artifactId>poi-ooxml</artifactId>
4        <version>5.2.3</version>
5</dependency>
6

2、基本使用

在POI中，Workbook代表整个Excel文件，sheet是工作表，可以有多个。

Row和Cell是单独的对象，索引都是从0开始。Cell单元格，可存字符串、数字、布尔、日期等。

下面代码中包含了增删改查基本操作。

a、新建excel的操作

注意：sheet.removeRow(row1); 不会像你直观理解的那样“把行从表格中完全移除并上移下面的行”。它会清空该 Row 对象中的所有单元格，其他行号不变。所以下面调用了封装的方法移除。

1    @Test
2    void testCreateWorkbookAndSheet() throws IOException {
3        Workbook workbook = new XSSFWorkbook();
4        Sheet sheet = workbook.createSheet("员工信息");
5
6        // 创建表头
7        Row header = sheet.createRow(0);
8        header.createCell(0).setCellValue("编号");
9        header.createCell(1).setCellValue("姓名");
10        header.createCell(2).setCellValue("薪资");
11
12        // 添加数据
13        Row row1 = sheet.createRow(1);
14        row1.createCell(0).setCellValue(1001);
15        row1.createCell(1).setCellValue("张三");
16        row1.createCell(2).setCellValue(12000);
17      
18        Row row2 = sheet.createRow(2);
19        row2.createCell(0).setCellValue(1001);
20        row2.createCell(1).setCellValue("张三");
21        row2.createCell(2).setCellValue(12000);
22
23        // 修改单元格
24        row1.getCell(2).setCellValue(13000);
25
26        // 删除一行，清空操作
27        sheet.removeRow(row1);
28       //如果上移需要使用封装的方法
29       //deleteRow(sheet, 1);
30        try (FileOutputStream fos = new FileOutputStream("basic.xlsx")) {
31            workbook.write(fos);
32        }
33        workbook.close();
34    }
35
36    /**
37     * 删除指定行，并将下面的行上移 https://stackoverflow.com/questions/21946958/how-to-remove-a-row-using-apache-poi
38     *
39     * @param sheet    目标Sheet
40     * @param rowIndex 要删除的行号（0-based）
41     */
42    public void deleteRow(Sheet sheet, int rowIndex) {
43        int lastRowNum = sheet.getLastRowNum();
44        if (rowIndex >= 0 && rowIndex < lastRowNum) {
45           sheet.shiftRows(rowIndex + 1, lastRowNum, -1);
46        }
47        if (rowIndex == lastRowNum) {
48           Row removingRow = sheet.getRow(rowIndex);
49           if (removingRow != null) {
50              sheet.removeRow(removingRow);
51           }
52        }
53    }
54

sheet.removeRow(row1)效果：

deleteRow(sheet, 1)效果：

b、读取已有文件

注意：WorkbookFactory.create兼容新老板版本，推荐使用

1  @Test
2    void testReadSheet() throws Exception {
3        InputStream is = Thread.currentThread()
4                .getContextClassLoader()
5                .getResourceAsStream("daoru.xls");
6        //WorkbookFactory兼容 xls和xlsx
7        try (Workbook workbook = WorkbookFactory.create(is)) {
8
9            Sheet sheetAt = workbook.getSheetAt(0);
10            assertNotNull(sheetAt);
11
12            Row row = sheetAt.getRow(0);
13            Cell cell = row.getCell(0);
14            System.out.println("第一个单元格内容: " + getCellValue(cell));
15
16            Sheet sheet2 = workbook.getSheet("基本支出决算明细表");
17            Row row2 = sheet2.getRow(11);
18            Cell cell2 = row2.getCell(7);
19            System.out.println("第一个单元格内容: " + getCellValue(cell2));
20
21            // 遍历每个 Sheet
22            for (int i = 0; i < workbook.getNumberOfSheets() && i < 2; i++) {
23                Sheet sheet = workbook.getSheetAt(i);
24                System.out.println("She	et[" + i + "] 名称: " + sheet.getSheetName());
25
26                // 遍历行
27                for (Row r : sheet) {
28                    // 遍历单元格
29                    for (Cell c : r) {
30                        String value = getCellValue(c); // 使用工具方法获取显示值
31                        System.out.print(value + "\t");
32                    }
33                    System.out.println();
34                }
35
36                System.out.println("=================================");
37            }
38
39        }
40    }
41

c、sheet的基本操作

可以根据index，名字等获取sheet。也支持修改和排序

1 @Test
2    void testUpdateSheet() throws Exception {
3        try (Workbook workbook = createWorkbook(XLS)) {
4            // 创建新 Sheet
5            Sheet newSheet = workbook.createSheet("新建Sheet");
6
7            // 修改已有 Sheet 名称
8            workbook.setSheetName(0, "用户信息");
9            // 4️   调整 Sheet 顺序
10            workbook.setSheetOrder("用户信息", 1); // 移动到第2个位置
11            workbook.setSheetOrder("新建Sheet", 0); // 移动到第1个位置
12
13            String outputPath = "target/output" + GOV_XLS.substring(XLS.lastIndexOf('.'));
14            // 5️⃣ 导出为新文件
15            File outputFile = new File(outputPath);
16            try (FileOutputStream os = new FileOutputStream(outputFile)) {
17                workbook.write(os);
18            }
19        }
20    }
21
22

d、cell数据的简单转换和double精度问题

• cell目前有四种数据，下面有示例，公式在后续章节。
• 注意金额的处理：如果涉及到计算，可以把double转到BigDecimal处理，double是二进制浮点数，无法精确表示小数，例如0.1 + 0.2 ≠ 0.3。如果导出的数据必须是数字类型，可以使用Bigdecimal转下（不超过1516位）。数字超过 1516 位有效数字时（无论是整数还是小数），double 就不能精确表示它，只能取“最接近”的二进制数，产生舍入误差。超过15到16位的尽量用字符串。

1 private static String getCellValue(Cell cell) {
2        if (cell == null) return "";
3        switch (cell.getCellType()) {
4            case STRING:
5                return cell.getStringCellValue();
6            case NUMERIC:
7                return String.valueOf(cell.getNumericCellValue());
8            case BOOLEAN:
9                return String.valueOf(cell.getBooleanCellValue());
10            case FORMULA: //单元格里存放的是公式，而不是直接的值。
11                return cell.getCellFormula();
12            case BLANK:
13                return "";
14            default:
15                return "UNKNOWN";
16        }
17    }
18

3、样式设置（字体、边框、对齐、条件格式）

以下示例展示了字体加粗等样式。

注意：

• style对象可以重复使用，同一个样式尽量只创建一次。
• POI 条件格式公式从单元格左上角开始，即 A1 为相对位置，公式可以使用 $ 绝对引用。
• 条件格式适合数据量中小的单元格，数万行大表格时条件格式多可能会影响 Excel 打开速度。

1 @Test
2    void testCreateStyledExcelWithStyleCache() throws Exception {
3        try (Workbook workbook = new XSSFWorkbook()) {
4            Sheet sheet = workbook.createSheet("样式示例");
5
6            // ========== 样式缓存 ==========
7            Map<String, CellStyle> styleCache = new HashMap<>();
8
9            int rows = 5;
10            int cols = 5;
11
12            for (int i = 0; i < rows; i++) {
13                Row row = sheet.createRow(i);
14                for (int j = 0; j < cols; j++) {
15                    Cell cell = row.createCell(j);
16                    cell.setCellValue("R" + (i + 1) + "C" + (j + 1));
17
18                    // 样式 key：行背景 + 列字体颜色 + 是否加粗
19                    String key = (i % 2) + "-" + (j % 2) + "-" + (i % 2 == 0);
20
21                    // 复用样式
22                    int finalI = i;
23                    int finalJ = j;
24                    CellStyle style = styleCache.computeIfAbsent(key, k -> createCellStyle(workbook, finalI, finalJ));
25
26                    cell.setCellStyle(style);
27                }
28            }
29
30            // 自动调整列宽
31            for (int j = 0; j < cols; j++) {
32                sheet.autoSizeColumn(j);
33            }
34
35            // 条件格式示例
36            SheetConditionalFormatting sheetCF = sheet.getSheetConditionalFormatting();
37            // 条件1：值 > 80 → 绿色
38            ConditionalFormattingRule rule1 = sheetCF.createConditionalFormattingRule(ComparisonOperator.GT, "80");
39            rule1.createPatternFormatting().setFillForegroundColor(IndexedColors.LIGHT_GREEN.getIndex());
40            rule1.getPatternFormatting().setFillPattern(FillPatternType.SOLID_FOREGROUND.getCode());
41
42            // 条件2：值 < 50 → 红色
43            ConditionalFormattingRule rule2 = sheetCF.createConditionalFormattingRule(ComparisonOperator.LT, "50");
44            rule2.createPatternFormatting().setFillForegroundColor(IndexedColors.ROSE.getIndex());
45            rule2.getPatternFormatting().setFillPattern(FillPatternType.SOLID_FOREGROUND.getCode());
46
47            // 应用到区域 B2:B100
48            sheetCF.addConditionalFormatting(
49                    new CellRangeAddress[]{CellRangeAddress.valueOf("B2:B100")},
50                    rule1, rule2
51            );
52
53            // 导出文件
54            try (FileOutputStream fos = new FileOutputStream("target/poi-style-demo-cache.xlsx")) {
55                workbook.write(fos);
56            }
57        }
58    }
59
60    /**
61     * 创建单元格样式（字体、边框、对齐、背景）
62     */
63    private CellStyle createCellStyle(Workbook workbook, int rowIndex, int colIndex) {
64        CellStyle style = workbook.createCellStyle();
65
66        // 字体
67        Font font = workbook.createFont();
68        font.setFontName("微软雅黑");
69        font.setFontHeightInPoints((short) 12);
70        font.setBold(rowIndex % 2 == 0); // 偶数行加粗
71        font.setColor(colIndex % 2 == 0 ? IndexedColors.RED.getIndex() : IndexedColors.BLUE.getIndex());
72        style.setFont(font);
73
74        // 边框
75        style.setBorderTop(BorderStyle.THIN);
76        style.setBorderBottom(BorderStyle.THIN);
77        style.setBorderLeft(BorderStyle.THIN);
78        style.setBorderRight(BorderStyle.THIN);
79
80        // 对齐
81        style.setAlignment(HorizontalAlignment.CENTER);
82        style.setVerticalAlignment(VerticalAlignment.CENTER);
83
84        // 背景
85        style.setFillForegroundColor(rowIndex % 2 == 0 ? IndexedColors.LIGHT_YELLOW.getIndex() : IndexedColors.GREY_25_PERCENT.getIndex());
86        style.setFillPattern(FillPatternType.SOLID_FOREGROUND);
87
88        return style;
89    }
90

下面是导出的效果图:

4、多级表头与合并单元格

a、多级表头动态读取

EasyExcel读取多表头存在问题，必须写死index才有数据，对于需要动态映射的，则没法处理。使用POI可以模仿EasyExcel注解，写个数据解析类。

注解和实体类如下:

1import java.lang.annotation.Retention;
2import java.lang.annotation.RetentionPolicy;
3
4@Retention(RetentionPolicy.RUNTIME)
5public @interface ExcelProperty {
6		//多级表头，用数组
7    String[] value();
8}
9
10@Data
11public class ExcelBudgetData implements Serializable {
12
13    @ExcelProperty(value = "预算项目")
14    private String budgetProject;
15
16    // "完成数"下面的“支付数”
17    @ExcelProperty(value = {"完成数", "支付数"})
18    private String completedPaymentAmount;
19
20    @ExcelProperty(value = "项目类别")
21    private String projectCategory;
22
23}
24

表头读取工具如下，注意跨列的解析方式：

1import org.apache.poi.ss.usermodel.*;
2import org.apache.poi.ss.util.CellRangeAddress;
3
4import java.util.ArrayList;
5import java.util.List;
6
7public class ExcelHeaderUtil {
8
9    /**
10     * 读取多级表头，支持跨列合并
11     *
12     * @param sheet        Excel sheet
13     * @param headRowStart 表头起始行 (0-based)
14     * @param headRowEnd   表头结束行 (0-based)
15     * @return 拼接后的多级表头列表（用 - 连接）
16     */
17    public static List<String> readMultiLevelHeader(Sheet sheet, int headRowStart, int headRowEnd) {
18        List<List<String>> headerRows = new ArrayList<>();
19        int maxCol = 0;
20
21        // 读取每一行表头内容
22        for (int r = headRowStart; r <= headRowEnd; r++) {
23            Row row = sheet.getRow(r);
24            List<String> rowData = new ArrayList<>();
25            if (row != null) {
26                int lastCol = row.getLastCellNum();
27                maxCol = Math.max(maxCol, lastCol);
28                for (int c = 0; c < lastCol; c++) {
29                    String value = getMergedCellValue(sheet, r, c);
30                    rowData.add(value == null ? "" : value.trim());
31                }
32            }
33            headerRows.add(rowData);
34        }
35
36        // 拼接多级表头
37        List<String> finalHeaders = new ArrayList<>();
38        for (int c = 0; c < maxCol; c++) {
39            StringBuilder sb = new StringBuilder();
40            for (List<String> headerRow : headerRows) {
41                String val = c < headerRow.size() ? headerRow.get(c) : "";
42                if (!val.isEmpty()) {
43                    if (sb.length() > 0) {
44                        sb.append("-");
45                    }
46                    sb.append(val);
47                }
48            }
49            finalHeaders.add(sb.toString());
50        }
51
52        return finalHeaders;
53    }
54
55    private static String getMergedCellValue(Sheet sheet, int rowIndex, int colIndex) {
56        for (int i = 0; i < sheet.getNumMergedRegions(); i++) {
57            CellRangeAddress range = sheet.getMergedRegion(i);
58            if (range.isInRange(rowIndex, colIndex)) {
59                if (range.getFirstRow() != rowIndex) {
60                    return "";
61                }
62                Row firstRow = sheet.getRow(range.getFirstRow());
63                Cell firstCell = firstRow.getCell(range.getFirstColumn());
64                return getCellStringValue(firstCell);
65            }
66        }
67        Row row = sheet.getRow(rowIndex);
68        if (row == null) {
69            return null;
70        }
71        Cell cell = row.getCell(colIndex);
72        return getCellStringValue(cell);
73    }
74		//公式等没处理，可以自行添加
75    private static String getCellStringValue(Cell cell) {
76        if (cell == null) {
77            return null;
78        }
79        switch (cell.getCellType()) {
80            case STRING:
81                return cell.getStringCellValue();
82            case NUMERIC:
83                return String.valueOf(cell.getNumericCellValue());
84            case BOOLEAN:
85                return String.valueOf(cell.getBooleanCellValue());
86            default:
87                return null;
88        }
89    }
90}
91

使用方式如下：

1private List<ExcelBudgetData> parseExcel(Sheet sheet) throws IllegalAccessException {
2        // 1️⃣ 读取多级表头
3        final int headRowStart = 3;
4        final int headRowEnd = 4;
5        List<String> headers = ExcelHeaderUtil.readMultiLevelHeader(sheet, headRowStart, headRowEnd);
6        // 2️⃣ 映射列到实体字段
7        Map<Integer, Field> colFieldMap = new HashMap<>();
8        Field[] fields = ExcelBudgetData.class.getDeclaredFields();
9        for (int i = 0; i < headers.size(); i++) {
10            String header = headers.get(i);
11            for (Field field : fields) {
12                ExcelProperty prop = field.getAnnotation(ExcelProperty.class);
13                if (prop != null) {
14                    String joined = String.join("-", prop.value()).trim();
15                    if (joined.equals(header)) {
16                        field.setAccessible(true);
17                        colFieldMap.put(i, field);
18                        break;
19                    }
20                }
21            }
22        }
23
24
25        List<ExcelBudgetData> result = new ArrayList<>();
26        for (int r = headRowEnd + 1; r <= sheet.getLastRowNum(); r++) {
27            Row row = sheet.getRow(r);
28            if (row == null) {
29                continue;
30            }
31            ExcelBudgetData obj = new ExcelBudgetData();
32
33            for (Map.Entry<Integer, Field> entry : colFieldMap.entrySet()) {
34                int c = entry.getKey();
35                Field field = entry.getValue();
36                Cell cell = row.getCell(c);
37                Object value = getCellValue(cell, field.getType());
38                field.set(obj, value);
39            }
40
41            result.add(obj);
42        }
43        return result;
44
45    }
46

b、写入时跨列

下面是一个跨行和跨列的表头例子

1@Test
2    void testMultiHeader() throws Exception {
3        Workbook workbook = new XSSFWorkbook();
4        Sheet sheet = workbook.createSheet("多级表头");
5
6        // 第一行表头
7        Row row1 = sheet.createRow(0);
8        row1.createCell(0).setCellValue("部门");
9        row1.createCell(1).setCellValue("销售额");
10        row1.createCell(3).setCellValue("利润");
11
12        // 第二行子表头
13        Row row2 = sheet.createRow(1);
14        row2.createCell(1).setCellValue("Q1");
15        row2.createCell(2).setCellValue("Q2");
16        row2.createCell(3).setCellValue("Q1");
17        row2.createCell(4).setCellValue("Q2");
18
19        // 合并表头单元格
20        sheet.addMergedRegion(new CellRangeAddress(0, 1, 0, 0)); // 部门
21        sheet.addMergedRegion(new CellRangeAddress(0, 0, 1, 2)); // 销售额
22        sheet.addMergedRegion(new CellRangeAddress(0, 0, 3, 4)); // 利润
23
24        try (FileOutputStream out = new FileOutputStream("target/multi-header-demo.xlsx")) {
25            workbook.write(out);
26        }
27        workbook.close();
28    }
29

5、公式处理

示例数据如下，C列为公式，对A和B列求和。