Spring Boot框架中针对数据文件模板的下载总结

1.前言

在我们的日常开发中，经常会碰到注入导入Excel数据到系统中的需求，而在导入Excel数据时，一般的业务系统都会提供数据的Excel模板，只有提交的Excel数据满足业务系统要求的模板时，数据才能够正常的导入系统中。因此针对这种需求，一般我们会在系统中提供一个Excel模板的下载按钮，业务人员在使用时，可以先下载Excel模板，然后按照模板中的格式将数据填充，即可导入成功。本文主要总结目前在开发这类需求时碰到的问题。

2.解决方案

从需求上来看，目前有大致三种解决方案，针对数据文件的模板下载，分别是：

• 模板文件直接存放在前端，作为静态资源，前端直接可以发送请求进行下载
• 模板文件存服务器磁盘，提供接口下载
• 模板文件存储在项目jar包中，提供接口下载

2.1 作为静态资源直接下载

第一种方式是最简单的，将数据文件直接作为静态资源放在前端目录，前端通过请求即可进行下载

2.2 模板文件存储在服务器，提供接口下载

第二种也是我们经常使用的方法，开发人员将模板文件放在服务器中的某个目录下，通过在代码中配置存储目录的方式，并且提供下载接口，当前端发起接口请求时，服务端根据请求将文件写入到响应流中

示例代码如下：

@Value("${templateFile}")
String downloadFilePath;

@GetMapping("/download")
public void downloadExcel(HttpServletResponse response){
    logger.info("下载Excel模板");
    try {
        File file=new File(downloadFilePath);
        ServletUtil.write(response,file);
    } catch (IOException e) {
        logger.error(e.getMessage(),e);
    }
}

因为文件存储在磁盘中，并且通过Spring提供的@Value注解将文件的位置在配置文件中进行配置，因此文件对象我们可以直接通过new File的方式直接获取到文件，最终调用工具类ServletUtil将该文件写入到HttpServletResponse的流中去，实现下载的目录

2.3 模板文件存在在jar中，提供接口下载

通过上面的两种下载方式，我们基本已经能实现文件的下载，满足业务的需要，但有时候我也会思考，是否把数据模板文件直接放在Spring Boot的jar中，这种方式的优势：

• 防止模板文件存储在磁盘时被误删的操作发送
• 如果程序部署需要迁移服务器，能有效避免下载接口的容错，忘记迁移模板文件等情况会导致程序异常
• 和程序代码存储在一起更加完整

基于上面的优势，因此，针对数据模板文件，我认为应该和项目直接放在一起，这样对于程序部署等都是非常有利的。

一般，在Spring Boot的开发框架中，我们可以在resources目录下建立文件夹，然后将相应的数据文件放入目录中，再提供接口读取该文件进行下载

目录结构如下：

|---project
|--------src/main/java
|--------src/main/resources
|------------data
# 模板文件
|--------------template.xlsx

因为我们将文件放在了resources目录下，此时如果要读取该文件，我们需要利用到Spring提供的ClassPathResource类进行读取，调用代码如下：

ClassPathResource classPathResource=new ClassPathResource("data/tag_data_template.xlsx");

此时，我们的下载接口代码如下：

@GetMapping("/download")
public void downloadExcel(HttpServletResponse response){
    logger.info("下载Excel模板");
    ClassPathResource classPathResource=new ClassPathResource("data/template.xlsx");
    try {
        //创建临时文件
        File file=File.createTempFile("template",".xlsx");
        //从当前resources目录下的文件流拷贝到File中
        FileUtils.copyInputStreamToFile(classPathResource.getInputStream(),file);
        logger.info("fileName:{}",file.getName());
        //将临时文件写出到流中
        ServletUtil.write(response,file);
    } catch (IOException e) {
        logger.error(e.getMessage(),e);
    }
}

这里会有1个疑问点，就是我们既然已经使用了Spring提供的ClassPathResource进行读取文件，而该类通过继承AbstractFileResolvingResource也提供了getFile方法获取File对象，为何不直接调用?

比如下载的接口代码改成这样：

@GetMapping("/download")
public void downloadExcel(HttpServletResponse response){
    logger.info("下载Excel模板");
    ClassPathResource classPathResource=new ClassPathResource("data/template.xlsx");
    try {
        //直接获取文件
        File file=classPathResource.getFile();
        //将临时文件写出到流中
        ServletUtil.write(response,file);
    } catch (IOException e) {
        logger.error(e.getMessage(),e);
    }
}

通过源码来分析

//AbstractFileResolvingResource.getFile
@Override
public File getFile() throws IOException {
    URL url = getURL();
    if (url.getProtocol().startsWith(ResourceUtils.URL_PROTOCOL_VFS)) {
        return VfsResourceDelegate.getResource(url).getFile();
    }
    return ResourceUtils.getFile(url, getDescription());
}

//ResourceUtils
/** URL protocol for a file in the file system: "file". */
public static final String URL_PROTOCOL_FILE = "file";
//ResourceUtils.getFile
public static File getFile(URL resourceUrl, String description) throws FileNotFoundException {
    Assert.notNull(resourceUrl, "Resource URL must not be null");
    if (!URL_PROTOCOL_FILE.equals(resourceUrl.getProtocol())) {
        throw new FileNotFoundException(
            description + " cannot be resolved to absolute file path " +
            "because it does not reside in the file system: " + resourceUrl);
    }
    try {
        return new File(toURI(resourceUrl).getSchemeSpecificPart());
    }
    catch (URISyntaxException ex) {
        // Fallback for URLs that are not valid URIs (should hardly ever happen).
        return new File(resourceUrl.getFile());
    }
}

在最终的ResourceUtils.getFile方法获取File对象时，Spring会对当前URL对象的协议进行判断,如果文件的协议不是file，则会抛出异常，提示

 class path resource [data/tag_data_template.xlsx] cannot be resolved to absolute file path because it does not reside in the file system: jar:file:/home/app.jar/BOOT-INF/classes!/data/template.xlsx

大致的意思就是该文件不在文件系统中，既然Spring不允许这么干，那么我们只能通过获取该文件的输入流的方式，将流写到临时文件中去，最终将该临时文件写出。

//FileUtils.copyInputStreamToFile方法
//commons-io 包中提供的方法
public static void copyInputStreamToFile(InputStream source, File destination) throws IOException {
    try {
        FileOutputStream output = openOutputStream(destination);
        try {
            IOUtils.copy(source, output);
            output.close(); // don't swallow close Exception if copy completes normally
        } finally {
            IOUtils.closeQuietly(output);
        }
    } finally {
        IOUtils.closeQuietly(source);
    }
}

以上的操作完成后，我们可能还会碰到部署时，代码还是会抛异常的问题，说文件找不到，这种情况一般会和我们项目的maven打包配置有关，我们需要在项目的maven配置中将模板文件也一起打包进去，例如增加配置如下：

<resources>
    <resource>
        <directory>src/main/resources</directory>
        <includes>
		   <!--包含data目录下的所有文件一起打包-->
            <include>**/data/**</include>
        </includes>
        <filtering>false</filtering>
    </resource>
</resources>

至此，就大功告成了！！！

3.附录

3.1 ServletUtil.write方法

ServletUtil工具类是引用的开源项目Hutool中的一个关于Servlet的工具类封装.

write方法提供了将文件写入到流中的封装，来看具体的源码：

封装了我们工作中基础的写出流的操作，我们在代码中也可以通过调用此方法简化我们的代码。

/** 默认缓存大小 8192*/
public static final int DEFAULT_BUFFER_SIZE = 2 << 12;
/**
 * 返回文件给客户端
 * 
 * @param response 响应对象{@link HttpServletResponse}
 * @param file 写出的文件对象
 * @since 4.1.15
*/
public static void write(HttpServletResponse response, File file) {
    final String fileName = file.getName();
    //根据文件名称获取文件的响应类型，如果没有则默认application/octet-stream
    final String contentType = ObjectUtil.defaultIfNull(FileUtil.getMimeType(fileName),"application/octet-stream");
    BufferedInputStream in = null;
    try {
        in = FileUtil.getInputStream(file);
        //再次调用，写出Header等信息
        write(response, in, contentType, fileName);
    } finally {
        IoUtil.close(in);
    }
}

/**
 * 返回数据给客户端
 * 
 * @param response 响应对象{@link HttpServletResponse}
 * @param in 需要返回客户端的内容
 * @param contentType 返回的类型
 * @param fileName 文件名
 * @since 4.1.15
*/
public static void write(HttpServletResponse response, InputStream in, String contentType, String fileName) {
    final String charset = ObjectUtil.defaultIfNull(response.getCharacterEncoding(), CharsetUtil.UTF_8);
    response.setHeader("Content-Disposition", StrUtil.format("attachment;filename={}", URLUtil.encode(fileName, charset)));
    response.setContentType(contentType);
    //写出
    write(response, in);
}

/**
 * 返回数据给客户端
 * 
 * @param response 响应对象{@link HttpServletResponse}
 * @param in 需要返回客户端的内容
*/
public static void write(HttpServletResponse response, InputStream in) {
	write(response, in, IoUtil.DEFAULT_BUFFER_SIZE);
}

/**
 * 返回数据给客户端
 * 
 * @param response 响应对象{@link HttpServletResponse}
 * @param in 需要返回客户端的内容
 * @param bufferSize 缓存大小
*/
public static void write(HttpServletResponse response, InputStream in, int bufferSize) {
    ServletOutputStream out = null;
    try {
        out = response.getOutputStream();
        IoUtil.copy(in, out, bufferSize);
    } catch (IOException e) {
        throw new UtilException(e);
    } finally {
        IoUtil.close(out);
        IoUtil.close(in);
    }
}