Apache POI 5.5.1 常用工具与 API 详解

Apache POI 5.5.1 常用工具与 API 详解：说明 POI 为纯 jar 类库无独立命令行工具、需经 Maven 引入后以 Java 代码调用，逐类速查 Workbook/XSSFWorkbook、Sheet、Row、Cell、DataFormatter、OPCPackage 核心 API 及依赖 jar 清单（13 个）与 mvn/unzip 辅助命令，含代码示例、真实回显与 FAQ，全程实测。

Apache POIApache POI2026/10/11

Apache POI 5.5.1 常用工具与 API 详解

目标：详解 Apache POI 5.5.1 的核心 API 与配套工具使用。POI 本身没有独立命令行工具，需通过 Java 代码调用其 jar 完成文档读写。本文按类速查 Workbook/XSSFWorkbook/Sheet/Row/Cell/DataFormatter 等关键类，给出依赖 jar 清单（13 个）、mvn/unzip 辅助命令、代码示例与 FAQ。所有示例在 Ubuntu 22.04.5 + OpenJDK 17 环境实测。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS
  • Java：OpenJDK 17.0.20.1（headless）
  • 构建工具：Apache Maven 3.6.3
  • POI 版本：5.5.1（poi-ooxml 入口，传递 13 个 jar）
  • 示例工程：/opt/data/poi-demo/
  • 产物文件：/tmp/demo.xlsx（3379 bytes）
  • 运行账号：root

二、工具概览

POI 以「类库 + jar」形态提供，没有 poi 命令行可执行程序；对 Excel/Word/PowerPoint 的全部操作都通过 Java API 完成。实际使用方式是把 jar 放进 classpath（Maven 依赖或 -cp），在自己的 Java 类中调用核心类：

工具/API 类别代表类作用
工作簿Workbook、XSSFWorkbook文档总入口：建表、写文件、读文件
工作表/行/单元格Sheet、Row、Cell三级结构定位与取值
格式化读取DataFormatter按显示格式把单元格转为字符串
打包访问OPCPackageOOXML 打包文件的底层访问入口
构建辅助mvn（dependency:tree / build-classpath）核对依赖树、生成运行 classpath
结构查看unzip -l、ls -l查看 xlsx 的 ZIP 内部结构与文件大小

💡 说明：POI 同时提供 HSSF（处理 .xls，OLE2 二进制格式）与 XSSF（处理 .xlsx，OOXML 格式）两套实现；本批实测以 XSSF 的 .xlsx 读写为准。

三、前置条件

已安装 JDK 17 与 Maven，并已建立最小工程、能正常编译运行（工程建立与依赖引入见《Apache POI 5.5.1 构建并运行示例应用指南》）：

cd /opt/data/poi-demo && mvn -q package

退出码 0 即构建成功。

四、核心 API 详解

4.1 Workbook 与 XSSFWorkbook（工作簿）

Workbook 是接口，XSSFWorkbook 是其 .xlsx 实现。写入用 try-with-resources 创建后经 write(OutputStream) 落盘；读取用输入流直接构造：

import org.apache.poi.ss.usermodel.*;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;

import java.io.FileInputStream;
import java.io.FileOutputStream;

// 写：内存创建工作簿并写出
try (Workbook wb = new XSSFWorkbook()) {
    Sheet sheet = wb.createSheet("Demo");
    try (FileOutputStream fos = new FileOutputStream("/tmp/demo.xlsx")) {
        wb.write(fos);
    }
}

// 读：输入流构造工作簿
try (FileInputStream fis = new FileInputStream("/tmp/demo.xlsx");
     Workbook wb = new XSSFWorkbook(fis)) {
    int count = wb.getNumberOfSheets();
}

常用方法：

方法说明
createSheet(String)创建工作表并命名
getSheetAt(int)按序号取工作表（0 起）
getSheetName(int)按序号取工作表名
getNumberOfSheets()工作表总数
write(OutputStream)把工作簿写出为 .xlsx 文件
close()释放资源（try-with-resources 自动调用）

4.2 Sheet / Row / Cell（工作表/行/单元格）

三级结构逐层创建与遍历，行号、列号均从 0 起：

Sheet sheet = wb.getSheetAt(0);
Row row = sheet.createRow(1);            // 按行号创建行
Cell cell = row.createCell(0);           // 按列号创建单元格
cell.setCellValue("Hello POI");          // 写字符串
row.createCell(1).setCellValue(42);      // 写数值（int/double）

// 遍历：Sheet 可直接迭代 Row，Row 可直接迭代 Cell
for (Row r : sheet) {
    for (Cell c : r) {
        int rowNum = r.getRowNum();      // 行号
        int colIdx = c.getColumnIndex(); // 列号
    }
}
类/方法说明
Sheet.createRow(int)按行号创建行
Row.createCell(int)按列号创建单元格
Cell.setCellValue(String/double/boolean)写入对应类型的值
Row.getRowNum() / Cell.getColumnIndex()行号/列号（0 起）
for (Row r : sheet)Iterable 遍历，无需按下标取行

4.3 DataFormatter（格式化读取）

直接读 Cell 原始值需要区分 CellType；DataFormatter.formatCellValue(Cell) 按单元格显示格式统一输出字符串，实测数字 42、3.14 均按原样打印：

DataFormatter fmt = new DataFormatter();
String val = fmt.formatCellValue(c);
System.out.printf("[READ] R%dC%d = %s%n",
    r.getRowNum(), c.getColumnIndex(), val);
方法说明
formatCellValue(Cell)按显示格式取字符串（推荐读取方式）
new DataFormatter()无参构造，默认按单元格样式格式化

4.4 OPCPackage 与读取方式

.xlsx 本质是 ZIP 打包的 OOXML 文档，OPCPackage 是其底层打包访问入口。常用读取方式对比：

方式形态适用
new XSSFWorkbook(FileInputStream)整本载入堆小文件（本批实测方式）
new XSSFWorkbook(OPCPackage)打包句柄可控中等文件
SAX 事件解析流式读取大文件，避免整本载入内存

⚠️ OPCPackage 构造与 SAX 事件解析两种方式未在本次实测范围，选择依据来自官方使用建议。

4.5 依赖 jar 清单与辅助命令工具

依赖 jar 清单：最小工程 compile classpath 共 13 个 jar，均位于 ~/.m2/repository：

jar版本大小
poi5.5.12.9M
poi-ooxml5.5.12.0M
poi-ooxml-lite5.5.15.8M
xmlbeans5.3.02.2M
commons-compress1.28.01.1M
commons-lang33.18.0688K
commons-io2.21.0572K
commons-codec1.20.0392K
log4j-api2.24.3344K
curvesapi1.08116K
commons-math33.6.12.2M
commons-collections44.5.0见 ~/.m2
SparseBitSet1.328K

核对依赖树（mvn dependency:tree，输出即上表 jar 的组合关系）：

cd /opt/data/poi-demo && mvn dependency:tree -Dscope=compile

真实回显：

com.example:poi-demo:jar:1.0
\- org.apache.poi:poi-ooxml:jar:5.5.1:compile
   +- org.apache.poi:poi:jar:5.5.1:compile
   |  +- commons-codec:commons-codec:jar:1.20.0:compile
   |  +- org.apache.commons:commons-math3:jar:3.6.1:compile
   |  \- com.zaxxer:SparseBitSet:jar:1.3:compile
   +- org.apache.poi:poi-ooxml-lite:jar:5.5.1:compile
   +- org.apache.xmlbeans:xmlbeans:jar:5.3.0:compile
   +- org.apache.commons:commons-compress:jar:1.28.0:compile
   |  \- org.apache.commons:commons-lang3:jar:3.18.0:compile
   +- commons-io:commons-io:jar:2.21.0:compile
   +- com.github.virtuald:curvesapi:jar:1.08:compile
   +- org.apache.logging.log4j:log4j-api:jar:2.24.3:compile
   \- org.apache.commons:commons-collections4:jar:4.5.0:compile

生成运行 classpath（依赖 jar 路径写入 cp.txt，供 java -cp 直接使用）：

cd /opt/data/poi-demo && mvn -q dependency:build-classpath -Dmdep.outputFile=/opt/data/poi-demo/cp.txt

命令本身无控制台输出；执行后 cat /opt/data/poi-demo/cp.txt 的内容即上表 13 个 jar 的绝对路径列表（冒号分隔）。

查看 xlsx 内部结构（ZIP 视角验证产物）：

ls -l /tmp/demo.xlsx
unzip -l /tmp/demo.xlsx

真实回显：

-rw-r--r-- 1 root root 3379 Oct 11 11:27 /tmp/demo.xlsx   # 3379 bytes ≈ 3.3 KB

Archive:  /tmp/demo.xlsx
  Length      Date    Time    Name
---------  ---------- -----   ----
     1053  2026-10-11 11:27   [Content_Types].xml
      586  2026-10-11 11:27   _rels/.rels
      183  2026-10-11 11:27   docProps/app.xml
      433  2026-10-11 11:27   docProps/core.xml
      237  2026-10-11 11:27   xl/sharedStrings.xml
      674  2026-10-11 11:27   xl/styles.xml
      347  2026-10-11 11:27   xl/workbook.xml
      564  2026-10-11 11:27   xl/_rels/workbook.xml.rels
      639  2026-10-11 11:27   xl/worksheets/sheet1.xml
---------                     -------
     4716                     9 files

五、完整最小可运行示例

把上述 API 串成一次"写入 + 读回"的完整程序（对应《Apache POI 5.5.1 构建并运行示例应用指南》篇的可执行源码），核心调用如下：

String path = "/tmp/demo.xlsx";

// 写：内存创建工作簿 → 建表/建行/建格 → 写出
try (Workbook wb = new XSSFWorkbook()) {
    Sheet sheet = wb.createSheet("Demo");
    Row header = sheet.createRow(0);
    header.createCell(0).setCellValue("Name");
    header.createCell(1).setCellValue("Value");
    Row row = sheet.createRow(1);
    row.createCell(0).setCellValue("Hello POI");
    row.createCell(1).setCellValue(42);
    Row row2 = sheet.createRow(2);
    row2.createCell(0).setCellValue("中国-测试");
    row2.createCell(1).setCellValue(3.14);
    try (FileOutputStream fos = new FileOutputStream(path)) {
        wb.write(fos);
    }
}

// 读：输入流构造工作簿 → DataFormatter 逐格打印
try (FileInputStream fis = new FileInputStream(path);
     Workbook wb = new XSSFWorkbook(fis)) {
    Sheet sheet = wb.getSheetAt(0);
    for (Row r : sheet) {
        for (Cell c : r) {
            DataFormatter fmt = new DataFormatter();
            String val = fmt.formatCellValue(c);
            System.out.printf("[READ] R%dC%d = %s%n",
                r.getRowNum(), c.getColumnIndex(), val);
        }
    }
}

运行实测输出（java -Dfile.encoding=UTF-8 -cp "target/classes:$(cat cp.txt)" PoiXlsxDemo，退出码 0）：

2026-10-11T11:27:04.652091124Z main ERROR Log4j API could not find a logging provider.
[WRITE] 已写出文件: /tmp/demo.xlsx, 大小=3379 bytes (=3.3 KB)
[READ] Sheet count=1, first sheet name="Demo"
[READ] R0C0 = Name
[READ] R0C1 = Value
[READ] R1C0 = Hello POI
[READ] R1C1 = 42
[READ] R2C0 = 中国-测试
[READ] R2C1 = 3.14
[DONE] 写读演示完成

💡 首行 Log4j 警告为 classpath 中仅有 log4j-api（无实现）时的常规提示，不影响功能。

六、注意事项

⚠️ 注意：

  1. POI 没有 poi 命令行工具，必须通过 Java 代码引入 jar 调用；mvn/unzip/ls 仅是构建与结构查看的辅助命令。
  2. POI 5.5.x 需 JDK 8+；写入与读取务必使用同一套 Workbook 实现（本文均为 XSSF/.xlsx）。
  3. poi-ooxml-lite 随 poi-ooxml 传递引入即可满足常规读写；需要冷门 schema 类型时才考虑 poi-ooxml-full（未实测）。
  4. 大文件读取优先 SAX 事件解析，避免 XSSFWorkbook 整本载入堆内存（未在本次实测范围）。

七、常见问题

Q1：POI 有命令行工具吗？ 没有。POI 是 Java 类库，全部操作经 Java API 完成；命令行侧只有构建工具 mvn 与系统辅助命令（unzip -l 查看包结构等）。

Q2：java -cp 报 ClassNotFoundException？ 确认已执行 mvn -q package 生成 target/classes，且 classpath 形如 "target/classes:$(cat cp.txt)"（先主类目录、后依赖列表，Linux 分隔符为冒号）。

Q3：读数字单元格得到浮点数（42.0）而不是 42？ Cell.getNumericCellValue() 返回 double。用 DataFormatter.formatCellValue(Cell) 按显示格式取字符串，实测输出即为 42。

Q4：写出的文件打不开或报 ZIP 异常？ write(OutputStream) 必须在 Workbook 关闭前完成且流正常关闭；推荐 try-with-resources 包裹 Workbook 与输出流，保证写出完整。

八、参考链接

  • Apache POI 官网：https://poi.apache.org/
  • Apache POI 官方发布说明：https://dlcdn.apache.org/poi/release/RELEASE-NOTES.txt
  • Maven Central poi-ooxml 版本目录：https://repo1.maven.org/maven2/org/apache/poi/poi-ooxml/