使用EasyExcel根據(jù)模板導(dǎo)出文件方式

更新時(shí)間：2025年09月08日 15:33:36 作者：劉火鍋

本文基于EasyExcel庫(kù)開(kāi)發(fā)ExportUtil工具類(lèi),支持模板化導(dǎo)出、列表/離散數(shù)據(jù)填充、HTTP響應(yīng)自動(dòng)配置及異常統(tǒng)一處理,實(shí)現(xiàn)結(jié)構(gòu)化報(bào)表生成與文件下載功能

概要

在企業(yè)級(jí)應(yīng)用開(kāi)發(fā)中，Excel數(shù)據(jù)導(dǎo)出是一個(gè)常見(jiàn)的需求。

本文實(shí)現(xiàn)一個(gè)基于阿里巴巴EasyExcel庫(kù)實(shí)現(xiàn)的根據(jù)模板導(dǎo)出文件的工具類(lèi)，它通過(guò)預(yù)定義的Excel模板來(lái)生成結(jié)構(gòu)化的數(shù)據(jù)報(bào)表，提高了導(dǎo)出功能的開(kāi)發(fā)效率和靈活性。

工具類(lèi)核心功能

該ExportUtil工具類(lèi)主要提供以下功能：

模板化導(dǎo)出：基于預(yù)定義的Excel模板填充數(shù)據(jù)
靈活數(shù)據(jù)支持：支持列表數(shù)據(jù)和離散對(duì)象數(shù)據(jù)的填充
自動(dòng)響應(yīng)設(shè)置：自動(dòng)處理HTTP響應(yīng)頭，實(shí)現(xiàn)文件下載
異常處理：統(tǒng)一的異常處理機(jī)制，確保導(dǎo)出過(guò)程穩(wěn)定性

核心代碼解析

類(lèi)結(jié)構(gòu)與常量定義

@Slf4j
@Component
public class ExportUtil {
    public static final String TEMPLATE_ROOT_PATH = "template";
    public static final String EXCEL_POSTFIX = "." + CommonConst.EXCEL_TYPE_XLSX;
    // ...
}

使用Lombok注解簡(jiǎn)化日志管理。定義了模板根路徑和Excel文件后綴常量（可自行定義）。

模板導(dǎo)出核心方法

public static void downloadExcelByTemplate(String templatePath, String fileName, 
                                         List<?> list, Object obj) {
    String templateFileName = TEMPLATE_ROOT_PATH + File.separator + templatePath;
    download(fileName + EXCEL_POSTFIX, outputStream -> {
        try (ExcelWriter excelWriter = EasyExcel.write(outputStream)
                .withTemplate(ExportUtil.class.getClassLoader()
                .getResourceAsStream(templateFileName)).build()) {
            WriteSheet writeSheet = EasyExcel.writerSheet().build();
            FillConfig fillConfig = FillConfig.builder().forceNewRow(Boolean.TRUE).build();
            excelWriter.fill(list, fillConfig, writeSheet);
            excelWriter.fill(obj, fillConfig, writeSheet);
        } catch (Exception e) {
            log.error("Writing template failed:{}", e.getMessage());
            throw new BusinessException(BusinessExceptionEnum.EXPORT_FAILED);
        }
    });
}

該方法接收四個(gè)參數(shù)：

templatePath: 模板文件路徑
fileName: 導(dǎo)出文件名（不含后綴）
list: 列表數(shù)據(jù)（用于填充模板中的表格區(qū)域）
obj: 離散數(shù)據(jù)（用于填充模板中的單個(gè)字段）

文件下載處理

public static void download(String fileName, Consumer<ServletOutputStream> write) {
    HttpServletResponse response = getHttpServletResponse(fileName);
    ServletOutputStream outputStream;
    try {
        outputStream = response.getOutputStream();
    } catch (IOException e) {
        log.error("Failed to read response and write stream:{}", e.getMessage());
        throw new BusinessException(BusinessExceptionEnum.EXPORT_FAILED);
    }
    write.accept(outputStream);
}

封裝了文件下載的通用邏輯，接收一個(gè)文件名和一個(gè)用于寫(xiě)入輸出流的Consumer函數(shù)式接口。

HTTP響應(yīng)設(shè)置

@SneakyThrows
public static HttpServletResponse getHttpServletResponse(String fileName) {
    ServletRequestAttributes servletRequestAttributes = 
        (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
    if (servletRequestAttributes == null || servletRequestAttributes.getResponse() == null) {
        log.error("Unable to obtain HttpServletResponse.");
        throw new BusinessException(BusinessExceptionEnum.EXPORT_FAILED);
    }
    HttpServletResponse res = servletRequestAttributes.getResponse();
    res.setContentType("application/octet-stream; charset=" + StandardCharsets.UTF_8);
    res.setHeader("Content-disposition", "attachment;filename=" + 
        URLEncoder.encode(fileName, StandardCharsets.UTF_8) + ";" + 
        "filename*=utf-8''" + URLEncoder.encode(fileName, StandardCharsets.UTF_8));
    return res;
}

負(fù)責(zé)設(shè)置HTTP響應(yīng)頭，包括內(nèi)容類(lèi)型和內(nèi)容處置頭，確保瀏覽器正確處理文件下載。使用URLEncoder對(duì)文件名進(jìn)行編碼，解決中文文件名亂碼問(wèn)題。

文件下載處理

使用示例

1. 準(zhǔn)備Excel模板

在resources/template目錄下創(chuàng)建模板文件，例如user_template.xlsx。
在模板中使用{}占位符表示離散數(shù)據(jù)，使用{.}表示列表數(shù)據(jù)。

2. 調(diào)用導(dǎo)出方法

// 準(zhǔn)備數(shù)據(jù)
UserInfo userInfo = new UserInfo("張三", "技術(shù)部");
List<Order> orders = Arrays.asList(
    new Order("訂單001", new Date(), 2999.0),
    new Order("訂單002", new Date(), 3999.0)
);

// 執(zhí)行導(dǎo)出
ExportUtil.downloadExcelByTemplate("user_template.xlsx", "用戶訂單", orders, userInfo);