首页 > 软件编程 > java > Java EasyExcel导出Excel

Java使用EasyExcel导出Excel的全流程详解

2025-11-13 08:41:46 作者：代码怪兽大大作战

在 Java 后端开发中,Excel 导出是非常常见的需求,涉及报表、数据分析或业务导出,本文将结合阿里 EasyExcel 库,详细讲解 Excel 导出流程,包括工具类设计、样式、列宽策略、对象映射、输出流处理,需要的朋友可以参考下

引言

在 Java 后端开发中，Excel 导出是非常常见的需求，涉及报表、数据分析或业务导出。

本文将结合 阿里 EasyExcel 库，详细讲解 Excel 导出流程，包括工具类设计、样式、列宽策略、对象映射、输出流处理。

一、什么是 EasyExcel

EasyExcel 是阿里巴巴开源的 Java Excel 处理库，相比 Apache POI 或 JXL：

高性能

基于 SAX 流式解析和写入，内存占用低
可以轻松处理百万行数据导出，不会 OOM

易用

注解式对象映射（@ExcelProperty）
只需定义对象类即可生成 Excel 表格

样式灵活

表头样式、内容样式、列宽、合并单元格等都可自定义

Web 集成方便

可以直接输出到浏览器下载，无需先生成文件

适合企业后台系统、报表系统、统计平台等场景。

二、Maven 依赖安装

在 pom.xml 中引入 EasyExcel：

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>easyexcel</artifactId>
    <version>4.0.3</version>
</dependency>

注意事项：

EasyExcel 依赖 JDK 1.8 及以上版本。
在实际项目中，如果出现依赖冲突或版本不兼容导致导出异常，可参考该文章进行排查和解决：EasyExcel 依赖冲突解决方案。

三、Excel 导出工具类设计

3.1 设计目标与整体架构

ExportTool 工具类主要实现了两个导出方式：

简单导出：快速将数据列表写入 Excel，无样式、无列宽控制。
带样式导出：支持自定义表头样式、内容样式和列宽自适应。

核心设计特点：

泛型支持：通过 <T> + Class<T>，工具类可导出任意类型的数据对象。
流安全处理：通过 NoCloseOutputStream 包装输出流，避免 EasyExcel 自动关闭 HttpServletResponse。
策略模式：样式、列宽分别封装为独立策略，便于扩展。
日志和异常管理：导出过程中的异常统一记录并封装为 ServiceException，方便上层调用处理。

工具类结构可以理解为三层：

响应流处理 → ExcelWriter 构建 → 样式 & 列宽策略 → 数据写入

3.2 完整工具类：ExportTool.java

@Slf4j
public class ExportTool {
    /**
     * 导出 Excel 文件（简单导出）
     *
     * @param dataList  导出的数据列表
     * @param clazz     数据类型（Excel 实体类）
     * @param fileName  导出的文件名（不带扩展名）
     * @param <T>       数据泛型
     */
    public static <T> void exportExcel(List<T> dataList, Class<T> clazz, String fileName) {
        if (dataList == null || dataList.isEmpty()) {
            log.warn("[ExportTool] 导出数据为空: {}", fileName);
        }

        try {
            HttpServletResponse response = WebTool.getResponse();

            // 使用复用的响应流设置方法
            setupResponse(response, fileName + ".xlsx");

            try (ServletOutputStream out = response.getOutputStream()) {
                // 简单导出，不增加样式或列宽限制
                EasyExcel.write(out, clazz)
                        .autoCloseStream(true)
                        .sheet("数据")
                        .doWrite(dataList);
            }

            log.info("[ExportTool] 导出成功: {}, 共 {} 条记录", fileName, dataList.size());
        } catch (Exception e) {
            log.error("[ExportTool] 导出失败: {}", fileName, e);
            throw new ServiceException("导出失败，请稍后重试");
        }
    }

    /**
     * 导出 Excel 文件（带表头样式）
     *
     * @param dataList 数据列表
     * @param clazz    数据类型（Excel 实体类）
     * @param fileName 导出文件名（包含 .xlsx）
     * @param <T>      数据类型
     */
    public static <T> void exportExcelWithStyle(List<T> dataList, Class<T> clazz, String fileName) {
        HttpServletResponse response = WebTool.getResponse();
        try {
            // 设置响应头
            setupResponse(response, fileName);

            // 获取输出流并防止 EasyExcel 关闭响应流
            ServletOutputStream out = response.getOutputStream();
            NoCloseOutputStream noCloseOut = new NoCloseOutputStream(out);

            // 创建 ExcelWriter
            ExcelWriter excelWriter = EasyExcel.write(noCloseOut, clazz)
                    // 注册样式策略
                    .registerWriteHandler(new HorizontalCellStyleStrategy(createHeadStyle(), createContentStyle()))
                    // 注册列宽自适应策略
                    .registerWriteHandler(createAutoWidthStrategy())
                    .build();

            // 创建 Sheet
            WriteSheet writeSheet = EasyExcel.writerSheet("导出数据").build();

            // 写入数据
            excelWriter.write(dataList, writeSheet);

            // 完成写入
            excelWriter.finish();

            log.info("[ExportTool] 导出成功: {}", fileName);
        } catch (Exception e) {
            log.error("[ExportTool] 导出失败: {}", fileName, e);
            throw new ServiceException("导出 Excel 失败");
        }
    }

    /**
     * 设置 HttpServletResponse 响应头
     */
    private static void setupResponse(HttpServletResponse response, String fileName) throws Exception {
        response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
        response.setCharacterEncoding("utf-8");
        String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString());
        response.setHeader("Content-Disposition", "attachment;filename=" + encodedFileName);
    }

    /**
     * 创建表头样式
     */
    private static WriteCellStyle createHeadStyle() {
        WriteCellStyle headStyle = new WriteCellStyle();

        // 设置白底（不填充颜色）
        headStyle.setFillForegroundColor(null);
        headStyle.setFillPatternType(FillPatternType.NO_FILL);

        // 设置字体
        WriteFont headFont = new WriteFont();
        headFont.setFontHeightInPoints((short) 11);
        headFont.setFontName("微软雅黑");
        headFont.setBold(true);
        headFont.setColor(IndexedColors.PALE_BLUE.getIndex());
        headStyle.setWriteFont(headFont);

        // 设置居中与自动换行
        headStyle.setHorizontalAlignment(HorizontalAlignment.CENTER);
        headStyle.setVerticalAlignment(VerticalAlignment.CENTER);
        headStyle.setWrapped(true);

        // 设置无边框
        headStyle.setBorderLeft(BorderStyle.NONE);
        headStyle.setBorderRight(BorderStyle.NONE);
        headStyle.setBorderTop(BorderStyle.NONE);
        headStyle.setBorderBottom(BorderStyle.NONE);

        return headStyle;
    }

    /**
     * 创建内容样式
     */
    private static WriteCellStyle createContentStyle() {
        WriteCellStyle contentStyle = new WriteCellStyle();

        // 设置字体
        WriteFont contentFont = new WriteFont();
        contentFont.setFontHeightInPoints((short) 11);
        contentFont.setFontName("等线");
        contentStyle.setWriteFont(contentFont);

        // 内容右对齐，垂直居中，自动换行
        contentStyle.setHorizontalAlignment(HorizontalAlignment.RIGHT);
        contentStyle.setVerticalAlignment(VerticalAlignment.CENTER);
        contentStyle.setWrapped(true);

        return contentStyle;
    }

    /**
     * 列宽自适应策略（根据内容长度自动调整列宽，限制最小 15、最大 20 字符）
     */
    private static AbstractColumnWidthStyleStrategy createAutoWidthStrategy() {
        return new AbstractColumnWidthStyleStrategy() {
            private final Map<Integer, Integer> columnWidthMap = new HashMap<>();

            @Override
            protected void setColumnWidth(WriteSheetHolder writeSheetHolder,
                                          List<WriteCellData<?>> cellDataList,
                                          Cell cell,
                                          Head head,
                                          Integer relativeRowIndex,
                                          Boolean isHead) {
                if (cell == null || cell.getCellType() != CellType.STRING) return;
                String value = cell.getStringCellValue();
                if (value == null) return;

                Sheet sheet = writeSheetHolder.getSheet();
                int columnIndex = cell.getColumnIndex();

                // 根据 UTF-8 字节长度计算列宽
                int length = value.getBytes(StandardCharsets.UTF_8).length;
                int minWidth = 15 * 256;
                int maxWidth = 20 * 256;
                int width = Math.max(minWidth, Math.min(length * 256 + 200, maxWidth));

                // 如果当前列宽大于记录的最大宽度，则更新列宽
                Integer maxWidthRecorded = columnWidthMap.getOrDefault(columnIndex, 0);
                if (width > maxWidthRecorded) {
                    columnWidthMap.put(columnIndex, width);
                    sheet.setColumnWidth(columnIndex, width);
                }

                // 设置自动换行样式
                CellStyle style = sheet.getWorkbook().createCellStyle();
                style.cloneStyleFrom(cell.getCellStyle());
                style.setWrapText(true);
                cell.setCellStyle(style);
            }
        };
    }

    /**
     * 包装 Servlet 输出流，不关闭底层流
     */
    public static class NoCloseOutputStream extends FilterOutputStream {
        public NoCloseOutputStream(OutputStream out) {
            super(out);
        }

        @Override
        public void close() throws IOException {
            flush(); // 不关闭底层流，仅刷新
        }
    }
}

3.3 核心方法分析

3.3.1 简单导出方法

public static <T> void exportExcel(List<T> dataList, Class<T> clazz, String fileName)

功能：快速生成 Excel 文件，无样式和列宽控制。

执行流程：

数据判空：日志告警数据为空情况。
获取响应流：通过 WebTool.getResponse() 获取 HttpServletResponse。
设置响应头：设置 MIME 类型和 Content-Disposition，保证浏览器下载文件。
EasyExcel 写入：调用 EasyExcel.write(out, clazz).sheet("数据").doWrite(dataList)，直接写入数据列表。
异常处理：统一捕获异常，抛出 ServiceException。

特点：

接口简单，使用泛型可适配任意实体类
无额外样式处理，适合数据量大或快速导出场景

3.3.2 带样式导出方法

public static <T> void exportExcelWithStyle(List<T> dataList, Class<T> clazz, String fileName)

功能：在 Excel 中生成 自定义表头、内容样式，并自动调整列宽。

执行流程：

获取响应流并设置响应头。
包装输出流：使用 NoCloseOutputStream 防止 EasyExcel 自动关闭底层流。
构建 ExcelWriter：
- 注册 表头样式 + 内容样式 (HorizontalCellStyleStrategy)
- 注册 列宽自适应策略 (AbstractColumnWidthStyleStrategy)
创建 Sheet：定义名称，例如 "导出数据"。
写入数据：excelWriter.write(dataList, writeSheet)
完成写入：调用 excelWriter.finish() 完成 Excel 写入流程。
异常处理：统一日志记录，抛出 ServiceException。

特点：

样式和列宽可独立调整，便于复用和扩展
保证浏览器端下载体验不受影响
对长文本和数字型列提供自动换行和右对齐

3.4 样式策略分析

3.4.1 表头样式

WriteCellStyle headStyle = createHeadStyle();

特点：

字体：微软雅黑，加粗，颜色淡蓝
对齐方式：水平居中、垂直居中
自动换行，保证多行表头显示完整
无边框、白底，视觉简洁

设计思路：

独立封装表头样式，便于在多个导出场景中复用
样式可通过 HorizontalCellStyleStrategy 与内容样式统一管理

3.4.2 内容样式

WriteCellStyle contentStyle = createContentStyle();

特点：

字体：等线
水平右对齐（适合数字、金额）、垂直居中
自动换行，保证长文本显示
与表头样式区分，形成信息层次感

设计思路：

独立封装内容样式，提高可维护性
通过策略模式应用于 ExcelWriter，无需重复设置

3.5 列宽自适应策略

AbstractColumnWidthStyleStrategy autoWidthStrategy = createAutoWidthStrategy();

实现逻辑：

遍历每个单元格内容，获取 UTF-8 字节长度。
根据长度计算列宽，设置最小 15、最大 20 字符。
对比历史最大列宽，确保列宽不会缩小。
设置单元格自动换行，保证内容完整显示。

优点：

避免手动设置每列宽度
支持中英文混合内容，保证可读性
与样式策略解耦，可独立替换或增强

注意：UTF-8 字节长度计算对不同字符可能略有偏差，中英文混合时列宽可能需微调

3.6 输出流包装策略

public static class NoCloseOutputStream extends FilterOutputStream

作用：

EasyExcel 在 finish() 默认关闭流
包装流后仅执行 flush()，不关闭底层 HttpServletResponse
保证浏览器下载文件正常，不中断响应

优点：

简单、安全
兼容大多数 Web 导出场景

3.7 ExcelWriter 构建与写入

ExcelWriter excelWriter = EasyExcel.write(noCloseOut, clazz)
        .registerWriteHandler(styleStrategy)
        .registerWriteHandler(autoWidthStrategy)
        .build();

分析：

解耦样式和列宽策略，便于单独扩展
批量写入数据，可适配大数据场景
支持自定义 Sheet 名称
可进一步扩展：冻结首行、单元格合并、插入公式等

四、导出对象类设计

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ExportUserVO {

    @ExcelProperty("姓名")
    private String userName;

    @ExcelProperty("ID")
    private Long id;

    @ExcelProperty("使用个数")
    private Integer useCount;

}

每个字段使用 @ExcelProperty 注解列名
数据类型支持 String、Integer、Double、Long 等常用类型
对象类清晰定义列名和数据结构

五、示例 Controller 导出方法

@GetMapping("/export")
public void exportUserExcel(HttpServletResponse response) {
    List<ExportUserVO> exportList = Arrays.asList(
        new ExportUserVO("张三", 1001L, 5),
        new ExportUserVO("李四", 1002L, 3)
    );

    String fileName = "用户导出.xlsx";

    ExportTool.exportExcelWithStyle(response, exportList, ExportUserVO.class, fileName);
}

浏览器访问 /export 即可直接下载 Excel
充分体现工具类的通用性和可复用性

导出Excel效果：

以上就是Java使用EasyExcel导出Excel的全流程详解的详细内容，更多关于Java EasyExcel导出Excel的资料请关注脚本之家其它相关文章！