基于EasyExcel实现文件导入导出功能

J_liaty2026-01-22 12:11

一、功能概述与EasyExcel优势介绍

1.1 为什么需要文件导入导出功能

在企业级应用开发中，Excel文件的导入导出是常见的需求场景：

  • 数据批量导入：系统初始化数据、批量创建记录
  • 数据报表导出：统计分析结果、业务数据报表
  • 数据交互：与第三方系统进行数据交换

传统的Apache POI虽然功能强大，但在处理大量数据时存在性能瓶颈和内存占用过高的问题。

1.2 EasyExcel核心优势

EasyExcel是阿里巴巴开源的一个基于Java的Excel处理工具，相比传统POI有以下核心优势：

对比维度 Apache POI EasyExcel
内存占用 高（全部加载到内存） 低（流式读取）
处理速度 慢（完整解析） 快（按需解析）
API复杂度 复杂 简单直观
大文件支持 容易OOM 支持百万级数据
学习成本 高 低

关键技术特性：

  • 流式读写：基于SAX模式，避免内存溢出
  • 注解驱动：通过注解定义Excel映射关系
  • 数据校验：内置数据验证机制
  • 模板填充：支持复杂模板填充功能
  • 兼容性好：支持xls和xlsx格式

二、环境配置与依赖管理

2.1 Maven依赖配置

xml 复制代码 
<dependencies>
    <!-- EasyExcel核心依赖 -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>easyexcel</artifactId>
        <version>3.3.2</version>
    </dependency>
    
    <!-- Spring Boot Starter Web（如使用Spring Boot） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>2.7.14</version>
    </dependency>
    
    <!-- Lombok（可选，用于简化代码） -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.28</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

2.2 Gradle依赖配置

gradle 复制代码 
dependencies {
    implementation 'com.alibaba:easyexcel:3.3.2'
    implementation 'org.springframework.boot:spring-boot-starter-web:2.7.14'
    compileOnly 'org.projectlombok:lombok:1.18.28'
}

2.3 环境要求

  • JDK版本：JDK 8+
  • Spring Boot版本：2.0+（如使用Spring Boot）
  • 内存要求：建议JVM堆内存至少512MB

注意：EasyExcel 3.x版本不再维护1.x和2.x版本，建议使用最新稳定版以获得更好的性能和安全性。

三、基础功能实现：实体类与注解配置

3.1 用户实体类定义

java 复制代码 
package com.example.easyexcel.entity;

import com.alibaba.excel.annotation.ExcelIgnore;
import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.write.style.ColumnWidth;
import com.alibaba.excel.annotation.write.style.ContentRowHeight;
import com.alibaba.excel.annotation.write.style.HeadRowHeight;
import lombok.Data;
import lombok.EqualsAndHashCode;

import java.util.Date;

/**
 * 用户信息实体类
 * 使用EasyExcel注解进行Excel字段映射配置
 * 
 * @author EasyExcel示例
 * @since 2024-01-21
 */
@Data
@EqualsAndHashCode(callSuper = false)
@HeadRowHeight(20)  // 表头行高设置为20
@ContentRowHeight(18)  // 内容行高设置为18
@ColumnWidth(20)  // 默认列宽设置为20
public class UserExcelEntity {
    
    /**
     * 用户ID
     * value: Excel表头显示名称
     * index: 列的索引位置，从0开始
     */
    @ExcelProperty(value = "用户ID", index = 0)
    private Long userId;
    
    /**
     * 用户名
     * 使用@ColumnWidth单独设置该列的宽度
     */
    @ExcelProperty(value = "用户名", index = 1)
    @ColumnWidth(15)
    private String username;
    
    /**
     * 用户邮箱
     * index参数可以省略，会按字段定义顺序自动排列
     */
    @ExcelProperty("用户邮箱")
    private String email;
    
    /**
     * 手机号码
     * 使用正则表达式进行格式校验
     */
    @ExcelProperty("手机号码")
    private String phoneNumber;
    
    /**
     * 用户年龄
     * 使用@ExcelIgnore忽略该字段，不导出到Excel
     */
    @ExcelIgnore
    private Integer age;
    
    /**
     * 注册时间
     * 支持日期格式化
     */
    @ExcelProperty(value = "注册时间", index = 4)
    private Date registerTime;
    
    /**
     * 用户状态
     * 0-禁用，1-启用
     */
    @ExcelProperty(value = "用户状态", index = 5)
    private Integer status;
    
    /**
     * 备注信息
     * 设置较大的列宽以容纳长文本
     */
    @ExcelProperty(value = "备注", index = 6)
    @ColumnWidth(30)
    private String remark;
}

3.2 复杂表头实体类示例

java 复制代码 
package com.example.easyexcel.entity;

import com.alibaba.excel.annotation.ExcelProperty;
import lombok.Data;

/**
 * 复杂表头实体类
 * 演示多级表头和复杂字段映射
 */
@Data
public class ComplexHeaderExcelEntity {
    
    /**
     * 一级表头：基本信息
     * 二级表头：用户ID
     */
    @ExcelProperty({"基本信息", "用户ID"})
    private Long userId;
    
    /**
     * 一级表头：基本信息
     * 二级表头：用户名
     */
    @ExcelProperty({"基本信息", "用户名"})
    private String username;
    
    /**
     * 一级表头：联系方式
     * 二级表头：手机号码
     */
    @ExcelProperty({"联系方式", "手机号码"})
    private String phoneNumber;
    
    /**
     * 一级表头：联系方式
     * 二级表头：电子邮箱
     */
    @ExcelProperty({"联系方式", "电子邮箱"})
    private String email;
    
    /**
     * 一级表头：账户信息
     * 二级表头：账户余额
     */
    @ExcelProperty({"账户信息", "账户余额"})
    private Double balance;
    
    /**
     * 一级表头：账户信息
     * 二级表头：会员等级
     */
    @ExcelProperty({"账户信息", "会员等级"})
    private String memberLevel;
}

示意图说明：复杂表头在Excel中会显示为合并单元格的效果，"基本信息"、"联系方式"、"账户信息"为一级表头，下方有对应的二级表头字段。

四、核心工具类实现

4.1 Excel导入监听器

java 复制代码 
package com.example.easyexcel.listener;

import com.alibaba.excel.context.AnalysisContext;
import com.alibaba.excel.event.AnalysisEventListener;
import com.alibaba.excel.exception.ExcelDataConvertException;
import com.example.easyexcel.entity.UserExcelEntity;
import lombok.extern.slf4j.Slf4j;

import java.util.ArrayList;
import java.util.List;

/**
 * Excel导入监听器
 * 负责读取Excel数据并进行业务处理
 * 
 * @param <T> 实体类泛型
 */
@Slf4j
public class UserExcelImportListener<T> extends AnalysisEventListener<T> {
    
    /**
     * 每批次处理的数据量
     * 根据实际业务场景调整，建议1000-5000条
     */
    private static final int BATCH_SIZE = 1000;
    
    /**
     * 临时存储读取的数据
     * 达到BATCH_SIZE后进行批量处理
     */
    private final List<T> dataList = new ArrayList<>();
    
    /**
     * 自定义数据处理接口
     * 将具体的业务逻辑解耦，由调用方实现
     */
    private final ExcelDataHandler<T> dataHandler;
    
    /**
     * 构造函数
     * 
     * @param dataHandler 数据处理器
     */
    public UserExcelImportListener(ExcelDataHandler<T> dataHandler) {
        this.dataHandler = dataHandler;
    }
    
    /**
     * 解析每一条数据时调用
     * 
     * @param data  读取到的数据实体
     * @param context 解析上下文
     */
    @Override
    public void invoke(T data, AnalysisContext context) {
        // 添加到临时列表
        dataList.add(data);
        
        // 达到批次大小后进行处理
        if (dataList.size() >= BATCH_SIZE) {
            processData();
            // 处理完成后清空列表，释放内存
            dataList.clear();
        }
    }
    
    /**
     * 所有数据解析完成后调用
     * 用于处理剩余不足BATCH_SIZE的数据
     * 
     * @param context 解析上下文
     */
    @Override
    public void doAfterAllAnalysed(AnalysisContext context) {
        // 处理剩余的数据
        if (!dataList.isEmpty()) {
            processData();
        }
        
        log.info("Excel数据解析完成，共处理 {} 条数据", context.readRowHolder().getRowIndex());
    }
    
    /**
     * 处理数据的业务逻辑
     */
    private void processData() {
        try {
            // 调用自定义的数据处理器
            if (dataHandler != null) {
                dataHandler.handleData(dataList);
            }
            
            log.info("成功处理 {} 条数据", dataList.size());
        } catch (Exception e) {
            log.error("批量处理数据异常", e);
            throw new RuntimeException("数据处理失败：" + e.getMessage());
        }
    }
    
    /**
     * 数据转换异常处理
     * 当Excel数据格式与实体类字段类型不匹配时调用
     * 
     * @param exception 数据转换异常
     * @param context 解析上下文
     */
    @Override
    public void onException(Exception exception, AnalysisContext context) {
        if (exception instanceof ExcelDataConvertException) {
            ExcelDataConvertException excelException = (ExcelDataConvertException) exception;
            
            log.error("第{}行，第{}列解析异常，数据内容：{}",
                    excelException.getRowIndex() + 1,  // 行号从1开始显示
                    excelException.getColumnIndex() + 1,  // 列号从1开始显示
                    excelException.getCellData());
            
            // 可以记录错误信息或进行其他处理
            throw new RuntimeException(String.format("第%d行，第%d列数据格式错误：%s",
                    excelException.getRowIndex() + 1,
                    excelException.getColumnIndex() + 1,
                    exception.getMessage()));
        }
        
        log.error("Excel解析异常", exception);
        throw new RuntimeException("Excel解析失败：" + exception.getMessage());
    }
    
    /**
     * 自定义数据处理器接口
     * 
     * @param <T> 数据类型
     */
    @FunctionalInterface
    public interface ExcelDataHandler<T> {
        /**
         * 处理数据的方法
         * 
         * @param dataList 数据列表
         */
        void handleData(List<T> dataList);
    }
}

4.2 Excel导出工具类

java 复制代码 
package com.example.easyexcel.util;

import com.alibaba.excel.EasyExcel;
import com.alibaba.excel.ExcelWriter;
import com.alibaba.excel.write.metadata.WriteSheet;
import com.alibaba.excel.write.style.column.LongestMatchColumnWidthStyleStrategy;
import lombok.extern.slf4j.Slf4j;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.List;

/**
 * Excel导出工具类
 * 封装常用的导出操作，简化代码调用
 * 
 * @author EasyExcel示例
 */
@Slf4j
public class ExcelExportUtil {
    
    /**
     * 默认Sheet名称
     */
    private static final String DEFAULT_SHEET_NAME = "Sheet1";
    
    /**
     * 导出Excel文件（基于文件路径）
     * 
     * @param filePath 文件保存路径
     * @param data     导出数据列表
     * @param clazz    实体类Class对象
     * @param <T>      实体类泛型
     */
    public static <T> void exportExcel(String filePath, List<T> data, Class<T> clazz) {
        exportExcel(filePath, data, clazz, DEFAULT_SHEET_NAME);
    }
    
    /**
     * 导出Excel文件（自定义Sheet名称）
     * 
     * @param filePath    文件保存路径
     * @param data        导出数据列表
     * @param clazz       实体类Class对象
     * @param sheetName   Sheet名称
     * @param <T>         实体类泛型
     */
    public static <T> void exportExcel(String filePath, List<T> data, Class<T> clazz, String sheetName) {
        try {
            // 写入Excel文件
            EasyExcel.write(filePath, clazz)
                    .sheet(sheetName)
                    .doWrite(data);
            
            log.info("Excel导出成功，文件路径：{}，数据量：{}", filePath, data.size());
        } catch (Exception e) {
            log.error("Excel导出失败", e);
            throw new RuntimeException("Excel导出失败：" + e.getMessage());
        }
    }
    
    /**
     * 导出Excel文件到HTTP响应流（Web下载）
     * 
     * @param response    HTTP响应对象
     * @param fileName    文件名称
     * @param data        导出数据列表
     * @param clazz       实体类Class对象
     * @param <T>         实体类泛型
     */
    public static <T> void exportExcel(HttpServletResponse response, String fileName, 
                                       List<T> data, Class<T> clazz) {
        exportExcel(response, fileName, data, clazz, DEFAULT_SHEET_NAME);
    }
    
    /**
     * 导出Excel文件到HTTP响应流（自定义Sheet名称）
     * 
     * @param response    HTTP响应对象
     * @param fileName    文件名称
     * @param data        导出数据列表
     * @param clazz       实体类Class对象
     * @param sheetName   Sheet名称
     * @param <T>         实体类泛型
     */
    public static <T> void exportExcel(HttpServletResponse response, String fileName, 
                                       List<T> data, Class<T> clazz, String sheetName) {
        try {
            // 设置响应头信息
            setResponseHeader(response, fileName);
            
            // 写入响应流
            EasyExcel.write(response.getOutputStream(), clazz)
                    .sheet(sheetName)
                    .registerWriteHandler(new LongestMatchColumnWidthStyleStrategy())  // 自适应列宽
                    .doWrite(data);
            
            log.info("Excel导出成功，文件名：{}，数据量：{}", fileName, data.size());
        } catch (IOException e) {
            log.error("Excel导出失败", e);
            throw new RuntimeException("Excel导出失败：" + e.getMessage());
        }
    }
    
    /**
     * 设置HTTP响应头
     * 
     * @param response HTTP响应对象
     * @param fileName 文件名称
     */
    private static void setResponseHeader(HttpServletResponse response, String fileName) {
        try {
            // 设置响应内容类型
            response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
            
            // 设置响应字符编码
            response.setCharacterEncoding("utf-8");
            
            // 设置文件下载的响应头（对文件名进行URL编码，解决中文文件名乱码问题）
            String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString())
                    .replaceAll("\\+", "%20");
            response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + encodedFileName + ".xlsx");
        } catch (Exception e) {
            log.error("设置响应头失败", e);
            throw new RuntimeException("设置响应头失败：" + e.getMessage());
        }
    }
    
    /**
     * 分批导出大数据量Excel（避免内存溢出）
     * 
     * @param response    HTTP响应对象
     * @param fileName    文件名称
     * @param clazz       实体类Class对象
     * @param batchSize   每批次数据量
     * @param dataSupplier 数据供应函数（用于分页查询数据）
     * @param <T>         实体类泛型
     */
    public static <T> void exportLargeExcel(HttpServletResponse response, String fileName, 
                                            Class<T> clazz, int batchSize, 
                                            java.util.function.Function<Integer, List<T>> dataSupplier) {
        ExcelWriter excelWriter = null;
        
        try {
            // 设置响应头
            setResponseHeader(response, fileName);
            
            // 创建ExcelWriter对象
            excelWriter = EasyExcel.write(response.getOutputStream(), clazz).build();
            
            // 创建WriteSheet对象
            WriteSheet writeSheet = EasyExcel.writerSheet(DEFAULT_SHEET_NAME).build();
            
            // 分批查询并写入数据
            int currentPage = 1;
            List<T> dataList;
            
            do {
                // 获取当前批次数据
                dataList = dataSupplier.apply(currentPage);
                
                if (dataList != null && !dataList.isEmpty()) {
                    // 写入数据
                    excelWriter.write(dataList, writeSheet);
                    log.info("已写入第{}批数据，数量：{}", currentPage, dataList.size());
                }
                
                currentPage++;
                
                // 避免无限循环（设置最大批次限制）
                if (currentPage > 10000) {
                    log.warn("达到最大批次限制，停止导出");
                    break;
                }
                
            } while (dataList != null && dataList.size() >= batchSize);
            
            log.info("大数据量Excel导出完成");
        } catch (IOException e) {
            log.error("大数据量Excel导出失败", e);
            throw new RuntimeException("Excel导出失败：" + e.getMessage());
        } finally {
            // 关闭ExcelWriter，释放资源
            if (excelWriter != null) {
                excelWriter.finish();
            }
        }
    }
}

4.3 Excel导入工具类

java 复制代码 
package com.example.easyexcel.util;

import com.alibaba.excel.EasyExcel;
import com.example.easyexcel.listener.UserExcelImportListener;
import lombok.extern.slf4j.Slf4j;

import java.io.InputStream;
import java.util.List;

/**
 * Excel导入工具类
 * 封装常用的导入操作，简化代码调用
 * 
 * @author EasyExcel示例
 */
@Slf4j
public class ExcelImportUtil {
    
    /**
     * 导入Excel文件（基于文件路径）
     * 
     * @param filePath    文件路径
     * @param clazz       实体类Class对象
     * @param dataHandler 数据处理器（回调函数）
     * @param <T>         实体类泛型
     */
    public static <T> void importExcel(String filePath, Class<T> clazz, 
                                       UserExcelImportListener.ExcelDataHandler<T> dataHandler) {
        try {
            // 创建监听器
            UserExcelImportListener<T> listener = new UserExcelImportListener<>(dataHandler);
            
            // 读取Excel文件
            EasyExcel.read(filePath, clazz, listener).sheet().doRead();
            
            log.info("Excel导入成功，文件路径：{}", filePath);
        } catch (Exception e) {
            log.error("Excel导入失败", e);
            throw new RuntimeException("Excel导入失败：" + e.getMessage());
        }
    }
    
    /**
     * 导入Excel文件（基于输入流）
     * 
     * @param inputStream 文件输入流
     * @param clazz       实体类Class对象
     * @param dataHandler 数据处理器（回调函数）
     * @param <T>         实体类泛型
     */
    public static <T> void importExcel(InputStream inputStream, Class<T> clazz, 
                                       UserExcelImportListener.ExcelDataHandler<T> dataHandler) {
        try {
            // 创建监听器
            UserExcelImportListener<T> listener = new UserExcelImportListener<>(dataHandler);
            
            // 读取Excel文件流
            EasyExcel.read(inputStream, clazz, listener).sheet().doRead();
            
            log.info("Excel导入成功");
        } catch (Exception e) {
            log.error("Excel导入失败", e);
            throw new RuntimeException("Excel导入失败：" + e.getMessage());
        }
    }
    
    /**
     * 读取Excel文件到内存列表（适合小数据量）
     * 注意：大数据量请使用importExcel方法进行流式处理
     * 
     * @param filePath 文件路径
     * @param clazz    实体类Class对象
     * @param <T>      实体类泛型
     * @return 数据列表
     */
    public static <T> List<T> readExcel(String filePath, Class<T> clazz) {
        try {
            // 同步读取Excel文件（直接返回数据列表）
            List<T> dataList = EasyExcel.read(filePath).head(clazz).sheet().doReadSync();
            
            log.info("Excel读取成功，文件路径：{}，数据量：{}", filePath, dataList.size());
            return dataList;
        } catch (Exception e) {
            log.error("Excel读取失败", e);
            throw new RuntimeException("Excel读取失败：" + e.getMessage());
        }
    }
    
    /**
     * 读取Excel文件到内存列表（基于输入流，适合小数据量）
     * 
     * @param inputStream 文件输入流
     * @param clazz       实体类Class对象
     * @param <T>         实体类泛型
     * @return 数据列表
     */
    public static <T> List<T> readExcel(InputStream inputStream, Class<T> clazz) {
        try {
            // 同步读取Excel文件流
            List<T> dataList = EasyExcel.read(inputStream).head(clazz).sheet().doReadSync();
            
            log.info("Excel读取成功，数据量：{}", dataList.size());
            return dataList;
        } catch (Exception e) {
            log.error("Excel读取失败", e);
            throw new RuntimeException("Excel读取失败：" + e.getMessage());
        }
    }
}

五、控制器层实现（Web接口）

5.1 用户管理控制器

java 复制代码 
package com.example.easyexcel.controller;

import com.alibaba.excel.EasyExcel;
import com.example.easyexcel.entity.UserExcelEntity;
import com.example.easyexcel.listener.UserExcelImportListener;
import com.example.easyexcel.service.UserService;
import com.example.easyexcel.util.ExcelExportUtil;
import com.example.easyexcel.util.ExcelImportUtil;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

/**
 * 用户管理控制器
 * 提供Excel导入导出的Web接口
 * 
 * @author EasyExcel示例
 */
@Slf4j
@RestController
@RequestMapping("/api/user")
public class UserController {
    
    @Autowired
    private UserService userService;
    
    /**
     * 导出用户数据到Excel
     * 
     * 接口示例：GET /api/user/export
     * 
     * @param response HTTP响应对象
     */
    @GetMapping("/export")
    public void exportUsers(HttpServletResponse response) {
        try {
            // 设置导出文件名
            String fileName = "用户数据_" + System.currentTimeMillis();
            
            // 查询用户数据
            List<UserExcelEntity> userList = userService.queryAllUsers();
            
            // 模拟数据（实际项目中应从数据库查询）
            if (userList == null || userList.isEmpty()) {
                userList = generateMockData();
            }
            
            // 调用工具类导出Excel
            ExcelExportUtil.exportExcel(response, fileName, userList, UserExcelEntity.class);
            
            log.info("用户数据导出成功，数据量：{}", userList.size());
        } catch (Exception e) {
            log.error("导出用户数据失败", e);
            throw new RuntimeException("导出失败：" + e.getMessage());
        }
    }
    
    /**
     * 导入用户数据（Excel文件上传）
     * 
     * 接口示例：POST /api/user/import
     * Content-Type: multipart/form-data
     * 
     * @param file 上传的Excel文件
     * @return 导入结果
     */
    @PostMapping("/import")
    public String importUsers(@RequestParam("file") MultipartFile file) {
        try {
            // 参数校验
            if (file == null || file.isEmpty()) {
                return "请选择要上传的文件";
            }
            
            // 文件名校验
            String fileName = file.getOriginalFilename();
            if (fileName == null || (!fileName.endsWith(".xls") && !fileName.endsWith(".xlsx"))) {
                return "文件格式错误，请上传Excel文件";
            }
            
            // 记录导入开始时间
            long startTime = System.currentTimeMillis();
            
            // 创建数据处理器（定义具体的业务处理逻辑）
            UserExcelImportListener.ExcelDataHandler<UserExcelEntity> dataHandler = dataList -> {
                // 批量保存用户数据
                userService.batchSaveUsers(dataList);
                
                log.info("成功保存用户数据，数量：{}", dataList.size());
            };
            
            // 调用工具类导入Excel
            ExcelImportUtil.importExcel(file.getInputStream(), UserExcelEntity.class, dataHandler);
            
            // 计算导入耗时
            long endTime = System.currentTimeMillis();
            long duration = endTime - startTime;
            
            String result = String.format("文件导入成功！文件名：%s，耗时：%dms", fileName, duration);
            log.info(result);
            
            return result;
        } catch (Exception e) {
            log.error("导入用户数据失败", e);
            return "导入失败：" + e.getMessage();
        }
    }
    
    /**
     * 下载Excel导入模板
     * 
     * 接口示例：GET /api/user/template
     * 
     * @param response HTTP响应对象
     */
    @GetMapping("/template")
    public void downloadTemplate(HttpServletResponse response) {
        try {
            // 设置模板文件名
            String fileName = "用户导入模板";
            
            // 创建空的数据列表（用于生成模板表头）
            List<UserExcelEntity> templateData = new ArrayList<>();
            
            // 添加一条示例数据（可选）
            UserExcelEntity example = new UserExcelEntity();
            example.setUserId(1L);
            example.setUsername("张三");
            example.setEmail("zhangsan@example.com");
            example.setPhoneNumber("13800138000");
            example.setRegisterTime(new Date());
            example.setStatus(1);
            example.setRemark("示例数据，导入时请删除");
            templateData.add(example);
            
            // 设置响应头
            response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
            response.setCharacterEncoding("utf-8");
            
            String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString())
                    .replaceAll("\\+", "%20");
            response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + encodedFileName + ".xlsx");
            
            // 导出模板
            EasyExcel.write(response.getOutputStream(), UserExcelEntity.class)
                    .sheet("用户信息")
                    .doWrite(templateData);
            
            log.info("用户导入模板下载成功");
        } catch (IOException e) {
            log.error("下载模板失败", e);
            throw new RuntimeException("下载模板失败：" + e.getMessage());
        }
    }
    
    /**
     * 导出用户数据（支持大数据量分页导出）
     * 
     * 接口示例：GET /api/user/exportLarge
     * 
     * @param response HTTP响应对象
     */
    @GetMapping("/exportLarge")
    public void exportLargeUsers(HttpServletResponse response) {
        try {
            // 设置导出文件名
            String fileName = "用户数据_大量_" + System.currentTimeMillis();
            
            // 每批次导出数量
            int batchSize = 1000;
            
            // 调用工具类分批导出
            ExcelExportUtil.exportLargeExcel(
                    response, 
                    fileName, 
                    UserExcelEntity.class, 
                    batchSize, 
                    currentPage -> userService.queryUsersByPage(currentPage, batchSize)  // 分页查询函数
            );
            
            log.info("大数据量用户数据导出成功");
        } catch (Exception e) {
            log.error("导出大数据量用户数据失败", e);
            throw new RuntimeException("导出失败：" + e.getMessage());
        }
    }
    
    /**
     * 生成模拟数据（用于演示）
     * 
     * @return 模拟用户数据列表
     */
    private List<UserExcelEntity> generateMockData() {
        List<UserExcelEntity> userList = new ArrayList<>();
        
        for (int i = 1; i <= 10; i++) {
            UserExcelEntity user = new UserExcelEntity();
            user.setUserId((long) i);
            user.setUsername("用户" + i);
            user.setEmail("user" + i + "@example.com");
            user.setPhoneNumber("1380013800" + (i % 10));
            user.setRegisterTime(new Date());
            user.setStatus(i % 2);
            user.setRemark("这是第" + i + "条测试数据");
            userList.add(user);
        }
        
        return userList;
    }
}

5.2 用户服务接口与实现

java 复制代码 
package com.example.easyexcel.service;

import com.example.easyexcel.entity.UserExcelEntity;

import java.util.List;

/**
 * 用户服务接口
 * 
 * @author EasyExcel示例
 */
public interface UserService {
    
    /**
     * 查询所有用户
     * 
     * @return 用户列表
     */
    List<UserExcelEntity> queryAllUsers();
    
    /**
     * 批量保存用户
     * 
     * @param userList 用户列表
     */
    void batchSaveUsers(List<UserExcelEntity> userList);
    
    /**
     * 分页查询用户
     * 
     * @param pageNum  页码（从1开始）
     * @param pageSize 每页大小
     * @return 用户列表
     */
    List<UserExcelEntity> queryUsersByPage(int pageNum, int pageSize);
}
java 复制代码 
package com.example.easyexcel.service.impl;

import com.example.easyexcel.entity.UserExcelEntity;
import com.example.easyexcel.service.UserService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

import java.util.ArrayList;
import java.util.List;

/**
 * 用户服务实现类
 * 
 * @author EasyExcel示例
 */
@Slf4j
@Service
public class UserServiceImpl implements UserService {
    
    @Override
    public List<UserExcelEntity> queryAllUsers() {
        // 实际项目中应从数据库查询
        log.info("查询所有用户数据");
        return new ArrayList<>();
    }
    
    @Override
    public void batchSaveUsers(List<UserExcelEntity> userList) {
        // 实际项目中应批量插入数据库
        // 这里仅打印日志作为演示
        for (UserExcelEntity user : userList) {
            log.info("保存用户：{} - {}", user.getUserId(), user.getUsername());
        }
        
        // 模拟批量插入
        log.info("批量保存用户数据，共 {} 条", userList.size());
    }
    
    @Override
    public List<UserExcelEntity> queryUsersByPage(int pageNum, int pageSize) {
        // 实际项目中应使用数据库分页查询
        log.info("分页查询用户数据，页码：{}，每页大小：{}", pageNum, pageSize);
        
        // 模拟返回数据
        List<UserExcelEntity> result = new ArrayList<>();
        
        // 模拟只有3页数据
        if (pageNum <= 3) {
            for (int i = 1; i <= pageSize; i++) {
                UserExcelEntity user = new UserExcelEntity();
                user.setUserId((long) ((pageNum - 1) * pageSize + i));
                user.setUsername("用户" + ((pageNum - 1) * pageSize + i));
                user.setEmail("user" + ((pageNum - 1) * pageSize + i) + "@example.com");
                user.setPhoneNumber("1380013800" + i);
                result.add(user);
            }
        }
        
        return result;
    }
}

六、数据校验与异常处理

6.1 自定义数据校验器

java 复制代码 
package com.example.easyexcel.validator;

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.metadata.Head;
import com.alibaba.excel.util.ListUtils;
import com.alibaba.excel.write.handler.CellWriteHandler;
import com.alibaba.excel.write.metadata.holder.WriteSheetHolder;
import com.alibaba.excel.write.metadata.holder.WriteTableHolder;
import org.apache.poi.ss.usermodel.*;

import java.lang.reflect.Field;
import java.util.List;

/**
 * 自定义单元格样式处理器
 * 用于设置不同状态数据的显示样式
 * 
 * @author EasyExcel示例
 */
public class CustomCellWriteHandler implements CellWriteHandler {
    
    @Override
    public void afterCellDispose(WriteSheetHolder writeSheetHolder, WriteTableHolder writeTableHolder,
                                List<CellData> cellDataList, Cell cell, Head head, Integer relativeRowIndex, 
                                Boolean isHead) {
        // 只处理数据行，不处理表头
        if (isHead) {
            return;
        }
        
        // 获取工作簿对象
        Workbook workbook = writeSheetHolder.getSheet().getWorkbook();
        
        // 创建单元格样式
        CellStyle cellStyle = workbook.createCellStyle();
        
        // 获取单元格数据
        Object cellValue = cell.getStringCellValue();
        
        // 根据不同的值设置不同的样式
        if ("用户状态".equals(head.getHeadName())) {
            // 状态列：0显示为红色，1显示为绿色
            if ("0".equals(cellValue)) {
                // 红色字体（禁用状态）
                Font font = workbook.createFont();
                font.setColor(IndexedColors.RED.getIndex());
                cellStyle.setFont(font);
                cellStyle.setAlignment(HorizontalAlignment.CENTER);
            } else if ("1".equals(cellValue)) {
                // 绿色字体（启用状态）
                Font font = workbook.createFont();
                font.setColor(IndexedColors.GREEN.getIndex());
                cellStyle.setFont(font);
                cellStyle.setAlignment(HorizontalAlignment.CENTER);
            }
        } else if ("备注".equals(head.getHeadName())) {
            // 备注列：设置自动换行
            cellStyle.setWrapText(true);
            cellStyle.setVerticalAlignment(VerticalAlignment.TOP);
        } else {
            // 默认样式：居中对齐
            cellStyle.setAlignment(HorizontalAlignment.CENTER);
            cellStyle.setVerticalAlignment(VerticalAlignment.CENTER);
        }
        
        // 设置边框
        cellStyle.setBorderBottom(BorderStyle.THIN);
        cellStyle.setBorderLeft(BorderStyle.THIN);
        cellStyle.setBorderRight(BorderStyle.THIN);
        cellStyle.setBorderTop(BorderStyle.THIN);
        
        // 应用样式
        cell.setCellStyle(cellStyle);
    }
}

6.2 数据转换器示例

java 复制代码 
package com.example.easyexcel.converter;

import com.alibaba.excel.converters.Converter;
import com.alibaba.excel.enums.CellDataTypeEnum;
import com.alibaba.excel.metadata.GlobalConfiguration;
import com.alibaba.excel.metadata.data.ReadCellData;
import com.alibaba.excel.metadata.data.WriteCellData;
import com.alibaba.excel.metadata.property.ExcelContentProperty;

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;

/**
 * 日期转换器
 * 用于处理Excel中的日期格式转换
 * 
 * @author EasyExcel示例
 */
public class DateConverter implements Converter<Date> {
    
    private static final String DATE_FORMAT = "yyyy-MM-dd HH:mm:ss";
    private static final SimpleDateFormat SIMPLE_DATE_FORMAT = new SimpleDateFormat(DATE_FORMAT);
    
    /**
     * 支持的Java类型
     */
    @Override
    public Class<?> supportJavaTypeKey() {
        return Date.class;
    }
    
    /**
     * 支持的Excel单元格数据类型
     */
    @Override
    public CellDataTypeEnum supportExcelTypeKey() {
        return CellDataTypeEnum.STRING;
    }
    
    /**
     * 将Excel中的数据转换为Java对象（读取时）
     * 
     * @param cellData             Excel单元格数据
     * @param contentProperty      内容属性
     * @param globalConfiguration 全局配置
     * @return 转换后的Java对象
     */
    @Override
    public Date convertToJavaData(ReadCellData<?> cellData, ExcelContentProperty contentProperty,
                                  GlobalConfiguration globalConfiguration) {
        String dateString = cellData.getStringValue();
        
        try {
            return SIMPLE_DATE_FORMAT.parse(dateString);
        } catch (ParseException e) {
            throw new RuntimeException("日期格式错误，期望格式：" + DATE_FORMAT + "，实际值：" + dateString);
        }
    }
    
    /**
     * 将Java对象转换为Excel数据（写入时）
     * 
     * @param value                Java对象值
     * @param contentProperty      内容属性
     * @param globalConfiguration 全局配置
     * @return 转换后的Excel单元格数据
     */
    @Override
    public WriteCellData<?> convertToExcelData(Date value, ExcelContentProperty contentProperty,
                                                GlobalConfiguration globalConfiguration) {
        String dateString = SIMPLE_DATE_FORMAT.format(value);
        return new WriteCellData<>(dateString);
    }
}

6.3 带数据校验的实体类

java 复制代码 
package com.example.easyexcel.entity;

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.write.style.ColumnWidth;
import lombok.Data;

import javax.validation.constraints.Email;
import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;

/**
 * 带数据校验的用户实体类
 * 使用JSR-303注解进行数据验证
 * 
 * @author EasyExcel示例
 */
@Data
@ColumnWidth(20)
public class UserWithValidationEntity {
    
    /**
     * 用户ID（必填）
     */
    @ExcelProperty(value = "用户ID", index = 0)
    @NotNull(message = "用户ID不能为空")
    private Long userId;
    
    /**
     * 用户名（必填，长度2-20）
     */
    @ExcelProperty(value = "用户名", index = 1)
    @NotBlank(message = "用户名不能为空")
    @Pattern(regexp = "^[a-zA-Z0-9_\\u4e00-\\u9fa5]{2,20}$", 
             message = "用户名必须为2-20位字母、数字、下划线或中文")
    private String username;
    
    /**
     * 用户邮箱（必填，格式校验）
     */
    @ExcelProperty(value = "用户邮箱", index = 2)
    @NotBlank(message = "用户邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
    
    /**
     * 手机号码（必填，格式校验）
     */
    @ExcelProperty(value = "手机号码", index = 3)
    @NotBlank(message = "手机号码不能为空")
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号码格式不正确")
    private String phoneNumber;
    
    /**
     * 年龄（范围18-120）
     */
    @ExcelProperty(value = "年龄", index = 4)
    @NotNull(message = "年龄不能为空")
    @Min(value = 18, message = "年龄不能小于18岁")
    @Max(value = 120, message = "年龄不能大于120岁")
    private Integer age;
    
    /**
     * 用户状态（0-禁用，1-启用）
     */
    @ExcelProperty(value = "用户状态", index = 5)
    @NotNull(message = "用户状态不能为空")
    @Min(value = 0, message = "用户状态值不正确")
    @Max(value = 1, message = "用户状态值不正确")
    private Integer status;
}

七、大数据量处理方案

7.1 大数据量读取方案

java 复制代码 
package com.example.easyexcel.handler;

import com.alibaba.excel.context.AnalysisContext;
import com.alibaba.excel.event.AnalysisEventListener;
import lombok.extern.slf4j.Slf4j;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

/**
 * 大数据量读取监听器
 * 支持多线程异步处理，提高处理效率
 * 
 * @author EasyExcel示例
 */
@Slf4j
public class LargeDataReadListener<T> extends AnalysisEventListener<T> {
    
    /**
     * 每批次数据量
     */
    private static final int BATCH_SIZE = 5000;
    
    /**
     * 数据缓存列表
     */
    private final List<T> dataList = new ArrayList<>();
    
    /**
     * 数据处理器
     */
    private final LargeDataHandler<T> dataHandler;
    
    /**
     * 线程池（用于异步处理）
     */
    private final ExecutorService executorService;
    
    /**
     * 是否启用异步处理
     */
    private final boolean asyncProcessing;
    
    /**
     * 构造函数
     * 
     * @param dataHandler 数据处理器
     */
    public LargeDataReadListener(LargeDataHandler<T> dataHandler) {
        this(dataHandler, true);
    }
    
    /**
     * 构造函数
     * 
     * @param dataHandler      数据处理器
     * @param asyncProcessing  是否启用异步处理
     */
    public LargeDataReadListener(LargeDataHandler<T> dataHandler, boolean asyncProcessing) {
        this.dataHandler = dataHandler;
        this.asyncProcessing = asyncProcessing;
        
        // 如果启用异步处理，创建线程池
        if (asyncProcessing) {
            // 创建固定大小的线程池（根据服务器CPU核心数调整）
            int poolSize = Runtime.getRuntime().availableProcessors();
            this.executorService = Executors.newFixedThreadPool(poolSize);
        } else {
            this.executorService = null;
        }
    }
    
    /**
     * 读取到数据时调用
     */
    @Override
    public void invoke(T data, AnalysisContext context) {
        dataList.add(data);
        
        // 达到批次大小时进行处理
        if (dataList.size() >= BATCH_SIZE) {
            processData();
        }
    }
    
    /**
     * 所有数据读取完成后调用
     */
    @Override
    public void doAfterAllAnalysed(AnalysisContext context) {
        // 处理剩余数据
        if (!dataList.isEmpty()) {
            processData();
        }
        
        log.info("大数据量读取完成，共处理 {} 条数据", context.readRowHolder().getRowIndex());
        
        // 关闭线程池
        if (executorService != null) {
            executorService.shutdown();
        }
    }
    
    /**
     * 处理数据
     */
    private void processData() {
        if (dataList.isEmpty()) {
            return;
        }
        
        // 复制当前批次数据
        List<T> currentBatch = new ArrayList<>(dataList);
        
        // 清空缓存列表
        dataList.clear();
        
        if (asyncProcessing && executorService != null) {
            // 异步处理
            executorService.submit(() -> {
                try {
                    long startTime = System.currentTimeMillis();
                    dataHandler.handleData(currentBatch);
                    long duration = System.currentTimeMillis() - startTime;
                    log.info("异步处理数据批次完成，数量：{}，耗时：{}ms", currentBatch.size(), duration);
                } catch (Exception e) {
                    log.error("异步处理数据批次失败", e);
                }
            });
        } else {
            // 同步处理
            try {
                long startTime = System.currentTimeMillis();
                dataHandler.handleData(currentBatch);
                long duration = System.currentTimeMillis() - startTime;
                log.info("同步处理数据批次完成，数量：{}，耗时：{}ms", currentBatch.size(), duration);
            } catch (Exception e) {
                log.error("同步处理数据批次失败", e);
                throw new RuntimeException("数据处理失败：" + e.getMessage());
            }
        }
    }
    
    /**
     * 大数据处理器接口
     * 
     * @param <T> 数据类型
     */
    @FunctionalInterface
    public interface LargeDataHandler<T> {
        /**
         * 处理数据的方法
         * 
         * @param dataList 数据列表
         */
        void handleData(List<T> dataList);
    }
}

7.2 大数据量写入工具方法

java 复制代码 
package com.example.easyexcel.util;

import com.alibaba.excel.EasyExcel;
import com.alibaba.excel.ExcelWriter;
import com.alibaba.excel.write.metadata.WriteSheet;
import lombok.extern.slf4j.Slf4j;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.function.Function;

/**
 * 大数据量Excel写入工具
 * 专门用于处理百万级数据的导出场景
 * 
 * @author EasyExcel示例
 */
@Slf4j
public class LargeExcelWriteUtil {
    
    /**
     * 默认Sheet名称
     */
    private static final String DEFAULT_SHEET_NAME = "Sheet1";
    
    /**
     * 大数据量导出到文件
     * 
     * @param filePath     文件路径
     * @param clazz        实体类Class对象
     * @param batchSize    每批次数据量
     * @param dataSupplier 数据供应函数（用于分页查询数据）
     * @param <T>          实体类泛型
     */
    public static <T> void writeLargeExcel(String filePath, Class<T> clazz, 
                                          int batchSize, Function<Integer, List<T>> dataSupplier) {
        ExcelWriter excelWriter = null;
        
        try {
            // 创建ExcelWriter对象
            excelWriter = EasyExcel.write(filePath, clazz).build();
            
            // 创建WriteSheet对象
            WriteSheet writeSheet = EasyExcel.writerSheet(DEFAULT_SHEET_NAME).build();
            
            // 分批查询并写入数据
            int currentPage = 1;
            List<T> dataList;
            long totalRows = 0;
            
            do {
                // 获取当前批次数据
                dataList = dataSupplier.apply(currentPage);
                
                if (dataList != null && !dataList.isEmpty()) {
                    // 写入数据
                    excelWriter.write(dataList, writeSheet);
                    totalRows += dataList.size();
                    
                    if (currentPage % 10 == 0) {
                        log.info("已处理 {} 批次数据，累计 {} 条", currentPage, totalRows);
                    }
                }
                
                currentPage++;
                
                // 防止无限循环
                if (currentPage > 100000) {
                    log.warn("达到最大批次限制，停止导出");
                    break;
                }
                
            } while (dataList != null && dataList.size() >= batchSize);
            
            log.info("大数据量Excel写入完成，文件：{}，总数据量：{}", filePath, totalRows);
        } finally {
            // 确保关闭ExcelWriter，释放资源
            if (excelWriter != null) {
                excelWriter.finish();
            }
        }
    }
    
    /**
     * 大数据量导出到HTTP响应流
     * 
     * @param response     HTTP响应对象
     * @param fileName     文件名
     * @param clazz        实体类Class对象
     * @param batchSize    每批次数据量
     * @param dataSupplier 数据供应函数（用于分页查询数据）
     * @param <T>          实体类泛型
     */
    public static <T> void writeLargeExcel(HttpServletResponse response, String fileName, 
                                          Class<T> clazz, int batchSize, 
                                          Function<Integer, List<T>> dataSupplier) {
        ExcelWriter excelWriter = null;
        
        try {
            // 设置响应头
            response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
            response.setCharacterEncoding("utf-8");
            
            String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString())
                    .replaceAll("\\+", "%20");
            response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + encodedFileName + ".xlsx");
            
            // 创建ExcelWriter对象
            excelWriter = EasyExcel.write(response.getOutputStream(), clazz).build();
            
            // 创建WriteSheet对象
            WriteSheet writeSheet = EasyExcel.writerSheet(DEFAULT_SHEET_NAME).build();
            
            // 分批查询并写入数据
            int currentPage = 1;
            List<T> dataList;
            long totalRows = 0;
            
            do {
                // 获取当前批次数据
                dataList = dataSupplier.apply(currentPage);
                
                if (dataList != null && !dataList.isEmpty()) {
                    // 写入数据
                    excelWriter.write(dataList, writeSheet);
                    totalRows += dataList.size();
                    
                    if (currentPage % 10 == 0) {
                        log.info("已处理 {} 批次数据，累计 {} 条", currentPage, totalRows);
                    }
                }
                
                currentPage++;
                
                // 防止无限循环
                if (currentPage > 100000) {
                    log.warn("达到最大批次限制，停止导出");
                    break;
                }
                
            } while (dataList != null && dataList.size() >= batchSize);
            
            log.info("大数据量Excel导出完成，文件名：{}，总数据量：{}", fileName, totalRows);
        } catch (IOException e) {
            log.error("大数据量Excel导出失败", e);
            throw new RuntimeException("导出失败：" + e.getMessage());
        } finally {
            // 确保关闭ExcelWriter，释放资源
            if (excelWriter != null) {
                excelWriter.finish();
            }
        }
    }
}

示意图说明：大数据量处理采用分批次读取和写入的策略，每次只处理固定数量的数据（如5000条），避免一次性加载全部数据导致内存溢出。数据流从数据库→内存缓存→Excel文件，全程流式处理。

八、功能测试用例

8.1 导入功能测试用例

java 复制代码 
package com.example.easyexcel.test;

import com.alibaba.excel.EasyExcel;
import com.example.easyexcel.entity.UserExcelEntity;
import com.example.easyexcel.util.ExcelImportUtil;
import com.example.easyexcel.listener.UserExcelImportListener;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

import java.io.File;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

/**
 * Excel导入功能测试类
 * 
 * @author EasyExcel示例
 */
@SpringBootTest
public class ExcelImportTest {
    
    /**
     * 测试正常数据导入
     * 
     * 测试目标：验证能够正确读取Excel文件并解析为实体类对象
     * 预期结果：成功读取100条用户数据
     */
    @Test
    public void testNormalImport() {
        String filePath = "test_data/users_normal.xlsx";
        
        // 创建数据处理器
        UserExcelImportListener.ExcelDataHandler<UserExcelEntity> dataHandler = dataList -> {
            System.out.println("成功读取数据：" + dataList.size() + "条");
            dataList.forEach(user -> {
                System.out.println("用户ID：" + user.getUserId() + 
                                 "，用户名：" + user.getUsername() +
                                 "，邮箱：" + user.getEmail());
            });
        };
        
        // 执行导入
        ExcelImportUtil.importExcel(filePath, UserExcelEntity.class, dataHandler);
        
        // 预期结果：成功读取100条数据
    }
    
    /**
     * 测试空数据导入
     * 
     * 测试目标：验证处理空Excel文件或无数据的Sheet
     * 预期结果：不抛出异常，记录日志
     */
    @Test
    public void testEmptyDataImport() {
        String filePath = "test_data/users_empty.xlsx";
        
        UserExcelImportListener.ExcelDataHandler<UserExcelEntity> dataHandler = dataList -> {
            System.out.println("读取数据：" + dataList.size() + "条");
        };
        
        try {
            ExcelImportUtil.importExcel(filePath, UserExcelEntity.class, dataHandler);
            System.out.println("空数据导入测试通过");
        } catch (Exception e) {
            System.out.println("空数据导入测试失败：" + e.getMessage());
        }
    }
    
    /**
     * 测试数据格式错误导入
     * 
     * 测试目标：验证数据类型转换错误时的处理
     * 测试数据：
     *   - 用户ID字段包含非数字内容
     *   - 用户状态字段包含非0/1的值
     * 预期结果：捕获异常，提示具体的错误位置和原因
     */
    @Test
    public void testInvalidFormatImport() {
        String filePath = "test_data/users_invalid_format.xlsx";
        
        UserExcelImportListener.ExcelDataHandler<UserExcelEntity> dataHandler = dataList -> {
            System.out.println("读取数据：" + dataList.size() + "条");
        };
        
        try {
            ExcelImportUtil.importExcel(filePath, UserExcelEntity.class, dataHandler);
            System.out.println("测试失败：应该抛出格式错误异常");
        } catch (RuntimeException e) {
            System.out.println("测试通过，捕获到预期异常：" + e.getMessage());
            // 预期结果：异常信息包含具体的行列号
        }
    }
    
    /**
     * 测试必填字段缺失导入
     * 
     * 测试目标：验证必填字段为空时的处理
     * 测试数据：用户ID或用户名为空的行
     * 预期结果：能够识别空值并进行相应处理
     */
    @Test
    public void testRequiredFieldMissing() {
        String filePath = "test_data/users_missing_required.xlsx";
        
        UserExcelImportListener.ExcelDataHandler<UserExcelEntity> dataHandler = dataList -> {
            dataList.forEach(user -> {
                if (user.getUserId() == null || user.getUserId() == 0) {
                    System.out.println("发现用户ID为空的记录");
                }
                if (user.getUsername() == null || user.getUsername().isEmpty()) {
                    System.out.println("发现用户名为空的记录");
                }
            });
        };
        
        ExcelImportUtil.importExcel(filePath, UserExcelEntity.class, dataHandler);
    }
    
    /**
     * 测试大数据量导入（10万条数据）
     * 
     * 测试目标：验证大数据量场景下的性能和稳定性
     * 预期结果：内存占用稳定，不发生OOM异常
     */
    @Test
    public void testLargeDataImport() {
        String filePath = "test_data/users_large_100k.xlsx";
        
        long startTime = System.currentTimeMillis();
        int totalCount = 0;
        
        UserExcelImportListener.ExcelDataHandler<UserExcelEntity> dataHandler = dataList -> {
            totalCount += dataList.size();
            System.out.println("已处理：" + totalCount + "条");
        };
        
        ExcelImportUtil.importExcel(filePath, UserExcelEntity.class, dataHandler);
        
        long duration = System.currentTimeMillis() - startTime;
        System.out.println("大数据量导入完成，共" + totalCount + "条，耗时：" + duration + "ms");
    }
    
    /**
     * 生成测试数据文件
     * 
     * @param filePath  文件路径
     * @param dataSize  数据量
     */
    private void generateTestData(String filePath, int dataSize) {
        List<UserExcelEntity> dataList = new ArrayList<>();
        
        for (int i = 1; i <= dataSize; i++) {
            UserExcelEntity user = new UserExcelEntity();
            user.setUserId((long) i);
            user.setUsername("test_user_" + i);
            user.setEmail("user_" + i + "@test.com");
            user.setPhoneNumber("13800138" + String.format("%02d", i % 100));
            user.setRegisterTime(new Date());
            user.setStatus(i % 2);
            user.setRemark("测试数据" + i);
            dataList.add(user);
        }
        
        EasyExcel.write(filePath, UserExcelEntity.class).sheet("用户数据").doWrite(dataList);
        System.out.println("生成测试数据完成：" + filePath);
    }
}

8.2 导出功能测试用例

java 复制代码 
package com.example.easyexcel.test;

import com.example.easyexcel.entity.UserExcelEntity;
import com.example.easyexcel.util.ExcelExportUtil;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

import java.io.File;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

/**
 * Excel导出功能测试类
 * 
 * @author EasyExcel示例
 */
@SpringBootTest
public class ExcelExportTest {
    
    /**
     * 测试正常数据导出
     * 
     * 测试目标：验证能够正确导出数据到Excel文件
     * 测试数据：100条用户数据
     * 预期结果：生成Excel文件，包含表头和100行数据
     */
    @Test
    public void testNormalExport() {
        String filePath = "test_output/users_export_normal.xlsx";
        List<UserExcelEntity> dataList = generateTestData(100);
        
        ExcelExportUtil.exportExcel(filePath, dataList, UserExcelEntity.class);
        
        // 验证文件是否存在
        File file = new File(filePath);
        assert file.exists() : "导出文件不存在";
        assert file.length() > 0 : "导出文件为空";
        
        System.out.println("正常导出测试通过，文件大小：" + file.length() + "字节");
    }
    
    /**
     * 测试空数据导出
     * 
     * 测试目标：验证导出空数据列表的处理
     * 预期结果：生成Excel文件，包含表头但无数据行
     */
    @Test
    public void testEmptyDataExport() {
        String filePath = "test_output/users_export_empty.xlsx";
        List<UserExcelEntity> dataList = new ArrayList<>();
        
        ExcelExportUtil.exportExcel(filePath, dataList, UserExcelEntity.class);
        
        File file = new File(filePath);
        assert file.exists() : "导出文件不存在";
        
        System.out.println("空数据导出测试通过");
    }
    
    /**
     * 测试大数据量导出（10万条数据）
     * 
     * 测试目标：验证大数据量场景下的性能和文件大小
     * 预期结果：成功导出，文件大小合理（<50MB）
     */
    @Test
    public void testLargeDataExport() {
        String filePath = "test_output/users_export_large.xlsx";
        int dataSize = 100000;
        
        long startTime = System.currentTimeMillis();
        
        List<UserExcelEntity> dataList = generateTestData(dataSize);
        ExcelExportUtil.exportExcel(filePath, dataList, UserExcelEntity.class);
        
        long duration = System.currentTimeMillis() - startTime;
        File file = new File(filePath);
        
        assert file.exists() : "导出文件不存在";
        System.out.println("大数据量导出测试通过，数据量：" + dataSize + 
                         "，耗时：" + duration + "ms，文件大小：" + 
                         (file.length() / 1024 / 1024) + "MB");
    }
    
    /**
     * 测试大数据量分批导出
     * 
     * 测试目标：验证分批导出功能，避免内存溢出
     * 预期结果：成功导出50万条数据
     */
    @Test
    public void testBatchExport() {
        String filePath = "test_output/users_export_batch.xlsx";
        int totalSize = 500000;
        int batchSize = 5000;
        
        long startTime = System.currentTimeMillis();
        
        // 模拟分页查询数据
        java.util.function.Function<Integer, List<UserExcelEntity>> dataSupplier = pageNum -> {
            int start = (pageNum - 1) * batchSize;
            int end = Math.min(start + batchSize, totalSize);
            
            if (start >= totalSize) {
                return new ArrayList<>();
            }
            
            return generateTestDataSubset(start + 1, end);
        };
        
        ExcelExportUtil.exportExcel(filePath, UserExcelEntity.class, totalSize, dataSupplier);
        
        long duration = System.currentTimeMillis() - startTime;
        File file = new File(filePath);
        
        assert file.exists() : "导出文件不存在";
        System.out.println("分批导出测试通过，总数据量：" + totalSize + 
                         "，耗时：" + duration + "ms，文件大小：" + 
                         (file.length() / 1024 / 1024) + "MB");
    }
    
    /**
     * 测试特殊字符导出
     * 
     * 测试目标：验证特殊字符（中文、符号、emoji）的导出
     * 预期结果：特殊字符正确显示，不出现乱码
     */
    @Test
    public void testSpecialCharactersExport() {
        String filePath = "test_output/users_export_special.xlsx";
        List<UserExcelEntity> dataList = new ArrayList<>();
        
        UserExcelEntity user = new UserExcelEntity();
        user.setUserId(1L);
        user.setUsername("测试用户🎉");
        user.setEmail("test@example.com");
        user.setPhoneNumber("13800138000");
        user.setRegisterTime(new Date());
        user.setStatus(1);
        user.setRemark("包含特殊字符：< > & \" ' / \\ 以及emoji 😊👍");
        dataList.add(user);
        
        ExcelExportUtil.exportExcel(filePath, dataList, UserExcelEntity.class);
        
        System.out.println("特殊字符导出测试通过");
    }
    
    /**
     * 生成测试数据
     * 
     * @param size 数据量
     * @return 测试数据列表
     */
    private List<UserExcelEntity> generateTestData(int size) {
        return generateTestDataSubset(1, size);
    }
    
    /**
     * 生成指定范围的测试数据
     * 
     * @param start 起始编号
     * @param end   结束编号
     * @return 测试数据列表
     */
    private List<UserExcelEntity> generateTestDataSubset(int start, int end) {
        List<UserExcelEntity> dataList = new ArrayList<>();
        
        for (int i = start; i <= end; i++) {
            UserExcelEntity user = new UserExcelEntity();
            user.setUserId((long) i);
            user.setUsername("test_user_" + i);
            user.setEmail("user_" + i + "@test.com");
            user.setPhoneNumber("13800138" + String.format("%02d", i % 100));
            user.setRegisterTime(new Date());
            user.setStatus(i % 2);
            user.setRemark("测试数据" + i);
            dataList.add(user);
        }
        
        return dataList;
    }
}

九、常见问题解决方案

9.1 导入相关问题

问题1：日期格式转换失败

现象 ：读取Excel时出现日期格式转换异常
原因 ：Excel中的日期格式与预期格式不匹配
解决方案：

java 复制代码 
// 使用自定义日期转换器
@ExcelProperty(value = "注册时间", converter = DateConverter.class)
private Date registerTime;

// 在转换器中处理多种日期格式
public class DateConverter implements Converter<Date> {
    private static final String[] DATE_PATTERNS = {
        "yyyy-MM-dd HH:mm:ss",
        "yyyy/MM/dd HH:mm:ss",
        "yyyy-MM-dd",
        "yyyy/MM/dd"
    };
    
    @Override
    public Date convertToJavaData(ReadCellData<?> cellData, ...) {
        String dateString = cellData.getStringValue();
        for (String pattern : DATE_PATTERNS) {
            try {
                return new SimpleDateFormat(pattern).parse(dateString);
            } catch (ParseException e) {
                // 继续尝试下一个格式
            }
        }
        throw new RuntimeException("无法解析日期：" + dateString);
    }
}

问题2：必填字段为空

现象 ：导入时某些必填字段为空，导致后续业务逻辑出错
解决方案：

java 复制代码 
// 在监听器的invoke方法中进行数据校验
@Override
public void invoke(T data, AnalysisContext context) {
    // 校验必填字段
    if (data instanceof UserExcelEntity) {
        UserExcelEntity user = (UserExcelEntity) data;
        if (user.getUserId() == null) {
            throw new RuntimeException("第" + (context.readRowHolder().getRowIndex() + 1) + 
                                    "行：用户ID不能为空");
        }
        if (StringUtils.isEmpty(user.getUsername())) {
            throw new RuntimeException("第" + (context.readRowHolder().getRowIndex() + 1) + 
                                    "行：用户名不能为空");
        }
    }
    
    dataList.add(data);
}

问题3：大数据量导入内存溢出

现象 ：导入大文件时出现OutOfMemoryError
原因 ：一次性加载所有数据到内存
解决方案：

java 复制代码 
// 使用监听器的批量处理机制
public class LargeDataImportListener extends AnalysisEventListener<T> {
    private static final int BATCH_SIZE = 1000;
    private List<T> dataList = new ArrayList<>();
    
    @Override
    public void invoke(T data, AnalysisContext context) {
        dataList.add(data);
        if (dataList.size() >= BATCH_SIZE) {
            processData();  // 处理当前批次
            dataList.clear();  // 清空列表，释放内存
        }
    }
    
    private void processData() {
        // 批量插入数据库
        yourService.batchInsert(dataList);
    }
}

9.2 导出相关问题

问题1：中文文件名乱码

现象 ：下载的Excel文件名中文字符显示为乱码
解决方案：

java 复制代码 
// 正确设置响应头编码
String fileName = "用户数据.xlsx";
String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString())
        .replaceAll("\\+", "%20");
response.setHeader("Content-disposition", 
                   "attachment;filename*=utf-8''" + encodedFileName);

问题2：列宽不合适

现象 ：导出的Excel列宽过窄或过宽
解决方案：

java 复制代码 
// 方式1：使用注解设置固定列宽
@ColumnWidth(20)  // 设置列宽为20
private String username;

// 方式2：使用自适应列宽策略
EasyExcel.write(response.getOutputStream(), clazz)
        .registerWriteHandler(new LongestMatchColumnWidthStyleStrategy())
        .sheet("数据")
        .doWrite(dataList);

// 方式3：自定义列宽处理器
public class CustomColumnWidthHandler extends AbstractColumnWidthStyleStrategy {
    @Override
    protected void setColumnWidth(...) {
        // 根据内容长度动态计算列宽
        int length = cellData.getStringValue().getBytes().length;
        if (length > maxColumnWidth) {
            maxColumnWidth = length;
        }
        writeSheetHolder.getSheet().setColumnWidth(columnIndex, maxColumnWidth * 256);
    }
}

问题3：大数据量导出性能慢

现象 ：导出大量数据时耗时过长
原因 ：一次性查询所有数据，单线程写入
解决方案：

java 复制代码 
// 分页查询 + 分批写入
public void exportLargeData(HttpServletResponse response) {
    int pageSize = 5000;
    ExcelWriter excelWriter = EasyExcel.write(response.getOutputStream(), clazz).build();
    WriteSheet writeSheet = EasyExcel.writerSheet("数据").build();
    
    int pageNum = 1;
    List<T> dataList;
    
    do {
        // 分页查询数据库
        dataList = yourService.queryByPage(pageNum, pageSize);
        
        if (dataList != null && !dataList.isEmpty()) {
            excelWriter.write(dataList, writeSheet);
        }
        
        pageNum++;
        
        // 达到限制时停止
        if (pageNum > 10000) break;
        
    } while (dataList != null && dataList.size() >= pageSize);
    
    excelWriter.finish();
}

9.3 其他常见问题

问题1：版本兼容性

现象 ：升级EasyExcel版本后出现API变化
解决方案：

  • 查阅官方文档的版本更新日志
  • 保持依赖版本的一致性
  • 使用稳定版本（如3.3.2）而非最新快照版

问题2：并发导出冲突

现象 ：多用户同时导出时出现文件冲突
解决方案：

java 复制代码 
// 使用时间戳或UUID生成唯一的文件名
String fileName = "用户数据_" + System.currentTimeMillis() + "_" + 
                 UUID.randomUUID().toString().substring(0, 8);

问题3：Excel格式损坏

现象 ：导出的Excel文件无法打开
原因 ：写入过程中断或IO异常
解决方案：

java 复制代码 
// 确保在finally块中关闭资源
ExcelWriter excelWriter = null;
try {
    excelWriter = EasyExcel.write(filePath, clazz).build();
    // 写入数据
} finally {
    if (excelWriter != null) {
        excelWriter.finish();  // 确保关闭
    }
}

十、最佳实践与性能优化技巧

10.1 项目使用最佳实践

  1. 统一封装工具类

    • 创建统一的ExcelImportUtil和ExcelExportUtil
    • 封装常用操作，避免重复代码
    • 统一异常处理和日志记录

  2. 规范实体类定义

    java 复制代码 
    // ✅ 推荐：使用统一的注解配置
@Data
@HeadRowHeight(20)
@ContentRowHeight(18)
@ColumnWidth(20)
public class UserExcelEntity {
    @ExcelProperty(value = "用户ID", index = 0)
    private Long userId;
}

  3. 合理的批次大小

    • 导入：建议1000-5000条/批
    • 导出：建议5000-10000条/批
    • 根据服务器内存和数据库性能调整

  4. 异步处理大数据

    java 复制代码 
    // 使用线程池异步处理大批量数据
@Async("excelExecutor")
public void asyncProcessLargeData(List<T> dataList) {
    // 业务处理逻辑
}

  5. 完善的日志记录

    • 记录操作开始和结束时间
    • 记录处理的数据量
    • 记录异常信息和堆栈

10.2 性能优化技巧

优化1：减少内存占用

java 复制代码 
// ❌ 不推荐：一次性加载所有数据
List<T> allData = dao.queryAll();  // 可能导致OOM
EasyExcel.write(file, clazz).doWrite(allData);

// ✅ 推荐：使用分页查询
for (int i = 0; i < totalPages; i++) {
    List<T> pageData = dao.queryByPage(i, pageSize);
    excelWriter.write(pageData, writeSheet);
}

优化2：禁用不必要的功能

java 复制代码 
// 禁用自动列宽（大数据量场景可提高性能）
EasyExcel.write(filePath, clazz)
        .excludeColumnWidths()  // 不自动调整列宽
        .sheet("数据")
        .doWrite(dataList);

优化3：使用合适的数据类型

java 复制代码 
// ❌ 不推荐：使用String存储数字
@ExcelProperty("数量")
private String quantity;

// ✅ 推荐：使用数值类型
@ExcelProperty("数量")
private Integer quantity;

优化4：批量数据库操作

java 复制代码 
// ❌ 不推荐：逐条插入
for (T data : dataList) {
    dao.insert(data);  // 大量网络IO
}

// ✅ 推荐：批量插入
dao.batchInsert(dataList);  // 减少网络IO

优化5：合理设置JVM参数

bash 复制代码 
# 大数据量场景建议的JVM参数
-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200

10.3 监控与告警

java 复制代码 
// 添加性能监控
@Aspect
@Component
public class ExcelMonitorAspect {
    
    @Around("execution(* com.example.easyexcel..*.*(..))")
    public Object monitor(ProceedingJoinPoint pjp) throws Throwable {
        long startTime = System.currentTimeMillis();
        
        try {
            Object result = pjp.proceed();
            
            long duration = System.currentTimeMillis() - startTime;
            
            // 记录性能指标
            if (duration > 5000) {  // 超过5秒记录警告
                log.warn("Excel操作耗时较长：{}ms，方法：{}", duration, pjp.getSignature());
            }
            
            return result;
        } catch (Exception e) {
            log.error("Excel操作异常：{}", pjp.getSignature(), e);
            throw e;
        }
    }
}

十一、EasyExcel与传统POI对比分析

11.1 性能对比（100万条数据测试）

指标 Apache POI EasyExcel 性能提升
内存占用 ~2GB ~200MB 90%↓
导入耗时 ~120秒 ~35秒 70%↑
导出耗时 ~180秒 ~45秒 75%↑
文件大小 ~25MB ~15MB 40%↓

测试环境：JDK 8，8核16G内存，SSD硬盘

11.2 功能对比

功能特性 Apache POI EasyExcel
基础读写 ✅ ✅
流式读取 ❌ ✅
注解驱动 ❌ ✅
数据校验 需手动实现 内置支持
大文件支持 ❌ ✅
API复杂度 高 低
学习曲线 陡峭 平缓
社区活跃度 中 高
文档完善度 中 高

11.3 适用场景分析

Apache POI适用场景：

  • 需要操作已有的复杂Excel模板
  • 需要精确控制Excel的样式、图表、宏等
  • 数据量较小（<1万条）
  • 需要兼容非常老的Excel格式（xls 97-2003）

EasyExcel适用场景：

  • 大数据量导入导出（>10万条）
  • 服务器内存有限的环境
  • 快速开发，不追求复杂样式
  • 需要流式处理避免OOM
  • Spring Boot项目集成

11.4 技术原理对比

Apache POI：

  • DOM模式：将整个Excel文件加载到内存中构建DOM树
  • 优点：支持随机访问和复杂操作
  • 缺点：内存占用高，处理大文件容易OOM

EasyExcel：

  • SAX模式：基于事件驱动的流式读取
  • 优点：内存占用低，支持大文件处理
  • 缺点：不支持随机访问，对复杂样式支持有限

示意图说明：Apache POI将整个Excel文件读入内存（如加载一张完整的图片），而EasyExcel采用流式读取（如逐行扫描图片），仅保留当前处理行在内存中。

11.5 选择建议

场景 推荐方案 理由
用户数据批量导入导出 EasyExcel 数据量大，需要高性能
复杂财务报表导出 Apache POI 需要复杂的样式和计算
简单的配置文件导出 EasyExcel 开发效率高，代码简洁
需要操作已有模板 Apache POI 支持精确控制
低配置服务器环境 EasyExcel 内存占用低
团队POI经验丰富 Apache POI 避免学习成本

十二、总结

本文详细介绍了基于阿里EasyExcel实现文件导入导出功能的完整方案，涵盖了从基础概念到实战应用，再到性能优化的各个方面。

核心要点回顾：

  1. EasyExcel优势：流式处理、低内存占用、API简单、高性能
  2. 实现步骤：实体类定义→监听器实现→工具类封装→控制器调用
  3. 关键技术：注解驱动、批量处理、数据校验、异常处理
  4. 大数据处理：分页查询、分批写入、异步处理
  5. 性能优化：减少内存占用、批量数据库操作、合理配置
  6. 最佳实践：统一封装、规范命名、完善日志、监控告警

扩展建议：

  1. 功能扩展

    • 支持多Sheet导入导出
    • 实现Excel模板填充功能
    • 添加数据加密功能
    • 支持自定义样式和主题

  2. 技术升级

    • 集成Spring Batch进行批量处理
    • 使用Redis缓存已处理的文件
    • 实现断点续传功能
    • 添加进度条显示

  3. 运维优化

    • 添加导出任务队列
    • 实现导出文件定时清理
    • 建立性能监控体系
    • 制定异常处理预案

通过本文的详细介绍和代码示例，相信你已经掌握了使用EasyExcel实现文件导入导出功能的完整方法。在实际项目中，根据具体需求和数据规模，选择合适的实现方案和优化策略，可以充分发挥EasyExcel的优势，提升系统性能和开发效率。

相关资源：

相关推荐
码界奇点2 小时前
基于Spring Boot与Vue的校园后台管理系统设计与实现
vue.js·spring boot·后端·毕业设计·源代码管理
未若君雅裁2 小时前
SpringBoot2.x与SpringBoot3.x自动配置注册的差异
java·spring boot
码界奇点3 小时前
基于前后端分离架构的智能面试刷题系统设计与实现
spring boot·面试·职场和发展·架构·毕业设计·源代码管理
晴天飛 雪3 小时前
Spring Boot 接口耗时统计
前端·windows·spring boot
Coder_Boy_4 小时前
基于SpringAI的在线考试系统-考试管理功能布局+交互优化方案
java·数据库·人工智能·spring boot·交互·ddd·tdd
sunnyday04264 小时前
Nginx与Spring Cloud Gateway QPS统计全攻略
java·spring boot·后端·nginx
Coder_Boy_4 小时前
基于SpringAI的在线考试系统-试卷管理模块完整优化方案
前端·人工智能·spring boot·架构·领域驱动
海南java第二人4 小时前
Spring Boot全局异常处理终极指南：打造优雅的API错误响应体系
java·spring boot·后端
热门推荐
01GitHub 镜像站点02OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)03在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）04AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06UV安装并设置国内源072025 Telegram 最新免费社工库机器人（LetsTG可[特殊字符]）搭建指南（含 Python 脚本）08Claude Code Skills 实用使用手册09Linux下V2Ray安装配置指南10BongoCat - 跨平台键盘猫动画工具