Java 操作 Excel 全方位指南：从入门到避坑，基于 Apache POI
Java 操作 Excel 全方位指南：从入门到避坑，基于 Apache POI
在现代企业级应用开发中，与 Microsoft Excel 文件进行交互是一项极其常见的需求。无论是数据导出生成报表、批量导入数据到系统，还是解析用户上传的 Excel 模板，Java 开发者都需要一套强大而可靠的工具库。Apache POI 项目正是为此而生的事实标准。本文将深入探讨如何使用 Apache POI 的两个核心组件 poi-ooxml 和 poi-ooxml-schemas，从原理到实战，为你全面解析 Java 操作 Excel 的方方面面。
一、依赖简介：POI、poi-ooxml 与 poi-ooxml-schemas
在开始编码之前，我们首先要理清 Apache POI 项目下的几个核心依赖及其关系。
1.1 Apache POI 项目概览
Apache POI（Poor Obfuscation Implementation）是一个开源的 Apache 项目，提供了一系列 Java API 来操作各种 Microsoft Office 格式文件，包括 Word、Excel、PowerPoint、Visio、Outlook 等。
对于 Excel 文件，POI 主要支持两种格式：
- HSSF (Horrible SpreadSheet Format)：用于操作 Excel 97(-2007) 的
.xls格式。 - XSSF (XML SpreadSheet Format) 和 SXSSF (Streaming Usermodel for XSSF)：用于操作 Excel 2007 OOXML (.xlsx) 及更高版本的格式。
1.2 核心依赖辨析
在我们的 pom.xml 中，通常会看到以下依赖：
<!-- 核心POI功能，包含HSSF用于操作旧的.xls格式 -->
<dependency><groupId>org.apache.poi</groupId><artifactId>poi</artifactId><version>5.2.3</version> <!-- 请使用最新版本 -->
</dependency><!-- 用于操作新的.xlsx格式 (XSSF和SXSSF) -->
<dependency><groupId>org.apache.poi</groupId><artifactId>poi-ooxml</artifactId><version>5.2.3</version> <!-- 请使用最新版本 -->
</dependency><!-- （通常自动传递依赖，无需显式声明） -->
<!-- <dependency><groupId>org.apache.poi</groupId><artifactId>poi-ooxml-schemas</artifactId><version>5.2.3</version>
</dependency> -->
poi：这是核心 Artifact，包含了操作所有 OLE2 格式文件（如.xls,.doc）的类（如HSSFWorkbook,HSSFSheet）。poi-ooxml：这个依赖是本文的重点。它包含了操作 OOXML 格式文件（如.xlsx,.docx）的类（如XSSFWorkbook,XSSFSheet）。关键点在于：poi-ooxml本身依赖于poi和poi-ooxml-schemas。所以你通常只需要声明poi-ooxml即可。poi-ooxml-schemas：这个依赖包含了完整的 OOXML 架构定义（大量的.xsd文件）。它提供了 Excel 文件底层 XML 结构的 Java 映射。poi-ooxml在运行时需要它来理解和生成符合规范的.xlsx文件。在绝大多数情况下，Maven/Gradle 的依赖传递机制会自动引入它，我们无需在pom.xml中显式声明。
总结：如果你只需要处理旧的 .xls 格式，引入 poi 即可；如果需要处理新的 .xlsx 格式，引入 poi-ooxml 就够了，它会自动帮你搞定其他依赖。
二、实战场景：生成一个复杂的 Excel 报表
让我们从一个真实的业务场景出发：将数据库中的用户信息列表导出为一个格式美观的 .xlsx 报表。
假设我们有一个 User 实体类：
@Data // Lombok 注解
public class User {private Long id;private String username;private String email;private Integer age;private String department;private LocalDateTime createTime;
}
我们的目标是生成一个包含标题、表头、数据行和合计行的 Excel 文件，并设置一些简单的样式。
2.1 基础步骤：创建工作簿、工作表、行和单元格
所有操作都围绕 Workbook -> Sheet -> Row -> Cell 这个层次结构进行。
import org.apache.poi.ss.usermodel.*;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;
import java.io.FileOutputStream;
import java.io.IOException;
import java.time.LocalDateTime;
import java.util.List;public class ExcelExporter {public void exportUsersToExcel(List<User> userList, String filePath)