导入模板下载

一、接口定义

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

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

二、服务层实现

@OverridepublicvoiddownloadImportTemplate(HttpServletResponseresponse)throwsIOException{try{// 1. 从 classpath 加载模板文件InputStreaminputStream=POICacheManager.getFile("dxssyjjbxxExportTemplate.xlsx");// 2. 读取为字节数组byte[]bytes=IoUtil.readBytes(inputStream);// 3. 写入 response 输出流下载CommonDownloadUtil.download("导入模板.xlsx",bytes,response);}catch(Exceptione){log.error(">>> 下载导入模板失败：",e);CommonResponseUtil.renderError(response,"下载导入模板失败");}}

调用链：Controller→JcDxssyjjbxxServiceImpl.downloadImportTemplate()
→POICacheManager.getFile()加载模板 →CommonDownloadUtil.download()输出到浏览器

三、核心方法详解

3.1 模板加载（POICacheManager）

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

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

模板文件位置：

3.2 文件下载（CommonDownloadUtil）

/** * 通用文件下载工具类 * 文件路径：/.../util/CommonDownloadUtil.java */publicstaticvoiddownload(StringfileName,byte[]fileBytes,HttpServletResponseresponse){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(IOExceptione){log.error(">>> 文件下载异常：",e);}}

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

3.3 异常处理（CommonResponseUtil）

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

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

四、使用场景

// 场景一：前端直接调用下载// GET /base/dxssyjjbxx/downloadImportTemplate// 浏览器弹出文件下载对话框，保存为 "导入模板.xlsx"// 场景二：配合导入功能// 用户先下载模板 → 按模板格式填写数据 → 调用 POST /base/dxssyjjbxx/import 上传

五、注意事项

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