SpringBoot 整合 FastExcel 实现 Excel 导入导出实战

3. 配置文件

仅需配置服务端口：

server:
  port: 8082

4. 定义实体类

使用注解将 Excel 列与 Java 对象属性映射。这里以用户信息为例：

package com.example.entity;

import cn.idev.excel.annotation.ExcelProperty;
import lombok.*;

@Setter
@Getter
@ToString
@AllArgsConstructor
@NoArgsConstructor
public class User {
    @ExcelProperty("编号")
    private Integer id;
    @ExcelProperty("名字")
    private String name;
    @ExcelProperty("年龄")
    private Integer age;
}

5. 编写监听器

FastExcel 内部封装了事件驱动模型。我们需要继承 AnalysisEventListener 来处理每行数据。基础监听器用于缓存数据：

package com.example.component;

import cn.idev.excel.context.AnalysisContext;
import cn.idev.excel.event.AnalysisEventListener;
import java.util.ArrayList;
import java.util.List;

public class BaseExcelListener<T> extends AnalysisEventListener<T> {
    private final List<T> dataList = new ArrayList<>();

    @Override
    public void invoke(T t, AnalysisContext analysisContext) {
        // 每读取一行数据，就将其添加到列表中
        dataList.add(t);
        System.out.println("解析到数据：" + t);
    }

    @Override
    public void doAfterAllAnalysed(AnalysisContext analysisContext) {
        System.out.println("读取完成，共读取了 " + dataList.size() + " 条数据");
    }

    public List<T> getDataList() {
        return dataList;
    }
}

6. 控制器接口

提供上传和下载两个接口进行测试：

package com.example.controller;

import cn.idev.excel.FastExcel;
import com.example.component.BaseExcelListener;
import com.example.entity.User;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.io.IOException;
import java.net.URLEncoder;
import java.util.List;

@RestController
@RequestMapping("/api/excel")
public class ExcelController {

    /**
     * Excel 导出功能
     */
    @GetMapping("/download")
    public void download(HttpServletResponse response) throws IOException {
        response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
        response.setCharacterEncoding("utf-8");
        String fileName = URLEncoder.encode("用户数据", "UTF-8");
        response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx");
        
        // 写入数据
        FastExcel.write(response.getOutputStream(), User.class)
                .sheet("用户信息")
                .doWrite(buildData());
    }

    /**
     * Excel 导入功能
     */
    @PostMapping("/upload")
    public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return ResponseEntity.badRequest().body("请选择一个文件上传！");
        }
        try {
            BaseExcelListener<User> baseExcelListener = new BaseExcelListener<>();
            FastExcel.read(file.getInputStream(), User.class, baseExcelListener)
                    .sheet()
                    .doRead();
            
            List<User> dataList = baseExcelListener.getDataList();
            System.out.println("读取到的数据：" + dataList);
            return ResponseEntity.ok("文件上传并处理成功！共处理 " + dataList.size() + " 条数据");
        } catch (IOException e) {
            return ResponseEntity.status(500).body("文件处理失败：" + e.getMessage());
        }
    }

    // 创建测试数据
    private List<User> buildData() {
        User user1 = new User();
        user1.setId(1);
        user1.setName("张三");
        user1.setAge(18);
        User user2 = new User();
        user2.setId(2);
        user2.setName("李四");
        user2.setAge(19);
        return List.of(user1, user2);
    }
}

7. 效果验证

启动工程后，访问 http://localhost:8082/api/excel/download 即可下载生成的 Excel 文件。上传接口则需配合 Postman 等工具发送文件，控制台会输出解析后的数据日志。

[图：Excel 下载效果] [图：上传接口调用日志]

8. 大数据量优化

当 Excel 数据量较大时，直接全量加载仍可能占用过多内存。建议采用分批处理模式，在监听器中设置阈值，达到一定数量后批量入库：

public class BatchExcelListener<T> extends AnalysisEventListener<T> {
    private static final int BATCH_COUNT = 1000;
    private List<T> dataList = new ArrayList<>(BATCH_COUNT);

    @Override
    public void invoke(T data, AnalysisContext context) {
        dataList.add(data);
        // 达到批次大小，执行存储逻辑
        if (dataList.size() >= BATCH_COUNT) {
            saveData();
            // 清空列表以便下一批
            dataList = new ArrayList<>(BATCH_COUNT);
        }
    }

    @Override
    public void doAfterAllAnalysed(AnalysisContext context) {
        // 确保最后剩余的数据也保存
        if (!dataList.isEmpty()) {
            saveData();
        }
        System.out.println("所有数据解析完成！");
    }

    private void saveData() {
        // 这里实现批量保存到数据库的逻辑
        System.out.println("批量保存" + dataList.size() + "条数据到数据库");
        // userService.saveBatch(dataList);
    }
}

9. 高级功能：Excel 转 PDF

FastExcel 1.0.0 版本新增了转换功能，无需额外依赖即可将 Excel 转为 PDF：

@GetMapping("/convertToPdf")
public void convertToPdf(){
    String excelPath = "D:\\data\\用户数据.xlsx";
    String pdfFilePath = "D:\\data\\用户数据.pdf";
    FastExcel.convertToPdf(new File(excelPath), new File(pdfFilePath), null, null);
    System.out.println("转换完成");
}

10. 从 EasyExcel 迁移

如果现有项目使用的是 EasyExcel，升级到 FastExcel 非常简单：

1. 修改依赖：将 com.alibaba.excel 替换为 cn.idev.excel。
2. 修改代码：全局替换包名引用。

<!-- EasyExcel -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>easyexcel</artifactId>
    <version>xxxx</version>
</dependency>

<!-- FastExcel -->
<dependency>
    <groupId>cn.idev.excel</groupId>
    <artifactId>fastexcel</artifactId>
    <version>1.0.0</version>
</dependency>

只需调整这两处，大部分业务代码无需改动即可平滑过渡。