当前位置：首页 > news >正文

Java 操作 Excel 全方位指南：从入门到避坑，基于 Apache POI

news 2025/9/6 6:19:58

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)