导入模板下载

一、接口定义

java 复制代码

@ApiOperationSupport(order = 6)
@ApiOperation("下载导入模板")
@CommonLog("下载导入模板")
@GetMapping(value = "/base/dxssyjjbxx/downloadImportTemplate",
            produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
public void downloadImportTemplate(HttpServletResponse response) throws IOException {
    jcDxssyjjbxxService.downloadImportTemplate(response);
}

请求方式： GET
参数： 无
返回： application/octet-stream 文件流（模板 Excel）

二、服务层实现

java 复制代码

@Override
public void downloadImportTemplate(HttpServletResponse response) throws IOException {
    try {
        // 1. 从 classpath 加载模板文件
        InputStream inputStream = POICacheManager.getFile("dxssyjjbxxExportTemplate.xlsx");

        // 2. 读取为字节数组
        byte[] bytes = IoUtil.readBytes(inputStream);

        // 3. 写入 response 输出流下载
        CommonDownloadUtil.download("导入模板.xlsx", bytes, response);

    } catch (Exception e) {
        log.error(">>> 下载导入模板失败：", e);
        CommonResponseUtil.renderError(response, "下载导入模板失败");
    }
}

调用链： Controller → JcDxssyjjbxxServiceImpl.downloadImportTemplate()

→ POICacheManager.getFile() 加载模板 → CommonDownloadUtil.download() 输出到浏览器

三、核心方法详解

3.1 模板加载（POICacheManager）

java 复制代码

// EasyPoi 的 POICacheManager 从 classpath 加载文件
InputStream inputStream = POICacheManager.getFile("dxssyjjbxxExportTemplate.xlsx");

逻辑： POICacheManager（EasyPoi 内置类）从 classpath 根目录加载文件，带缓存机制。同名文件只加载一次，后续读取从缓存返回。

模板文件位置：

模块	路径
	`src/main/resources/dxssyjjbxxExportTemplate.xlsx`

3.2 文件下载（CommonDownloadUtil）

java 复制代码

/**
 * 通用文件下载工具类
 * 文件路径：/.../util/CommonDownloadUtil.java
 */
public static void download(String fileName, byte[] fileBytes, HttpServletResponse response) {
    try {
        response.setHeader("Content-Disposition",
            "attachment;filename=" + URLUtil.encode(fileName));
        response.addHeader("Content-Length", "" + fileBytes.length);
        response.setHeader("Access-Control-Allow-Origin", "*");
        response.setHeader("Access-Control-Expose-Headers", "Content-Disposition");
        response.setContentType("application/octet-stream;charset=UTF-8");
        IoUtil.write(response.getOutputStream(), true, fileBytes);
    } catch (IOException e) {
        log.error(">>> 文件下载异常：", e);
    }
}

逻辑： 设置 HTTP 响应头（Content-Disposition 附件下载、Content-Length、CORS），然后将字节数组写入 response 输出流。

3.3 异常处理（CommonResponseUtil）

java 复制代码

CommonResponseUtil.renderError(response, "下载导入模板失败");

当模板加载或下载异常时，通过此方法向 response 写入错误信息，而非抛出异常中断请求。

四、使用场景

java 复制代码

// 场景一：前端直接调用下载
// GET /base/dxssyjjbxx/downloadImportTemplate
// 浏览器弹出文件下载对话框，保存为 "导入模板.xlsx"

// 场景二：配合导入功能
// 用户先下载模板 → 按模板格式填写数据 → 调用 POST /base/dxssyjjbxx/import 上传

五、注意事项

模板文件路径 --- dxssyjjbxxExportTemplate.xlsx 必须放在 resources 目录下，POICacheManager 从 classpath 根目录查找，找不到会抛异常。
文件名编码 --- CommonDownloadUtil 中使用 URLUtil.encode(fileName) 对中文文件名进行 URL 编码，避免浏览器下载时文件名乱码。
CORS 头 --- 设置了 Access-Control-Allow-Origin: * 和 Access-Control-Expose-Headers: Content-Disposition，支持跨域下载。