Retrofit2-如何从服务器下载文件

在这篇博客中，将会讲述使用Retrofit十分需要的一个功能：怎么去下载文件，下面会展示一些下载文件需要写的代码片段，从小的 png 图片到大的 zip文件。

原文地址

Retrofit 2 — How to Download Files from Server

怎么指定一个Retrofit请求

如果你刚刚开始阅读这篇文章并且以前没有写过任何关于Retrofit请求的代码，可以先看一下前面翻译的Retrofit系列的文章。对于已经用过的人来说，下载文件的请求和其他的请求看起来是差不多的。

// option 1: a resource relative to your base URL
@GET("/resource/example.zip")
Call<ResponseBody> downloadFileWithFixedUrl();

// option 2: using a dynamic URL
@GET
Call<ResponseBody> downloadFileWithDynamicUrlSync(@Url String fileUrl);  

如果你想下载的文件资源是静态的（资源一直在同一个地址）并且和你的base URL相关联，可以使用第一种方式。正如你所看到的，这看起来就像是Retrofit 2的一般的请求，值得注意的是，我们指定了 ResponseBody 来作为返回的类型。你不应该使用任何其他的类型，否则Retrofit会尝试去解析和映射转换，在下载任务的时候这些操作都是没有意义的。
第二种方式是Retrofit 2新加的，你现在可以轻松的通过一个动态的URL作为请求的参数，这个特性在下载文件的时候是格外有用的，因为一般url都是根据参数，使用者，和时间所决定的，你可以动态的去构建完整的请求URL。如果你还没有使用过动态URL，可以回头去看我已经翻译的另一篇文章：Retrofit2-如何在请求时使用动态URL。
你可以自己选择使用哪一种方法，然后我们接着看下一步。

怎么调用这个请求方法

当我们声明了一个方法后，我们需要去调用它，代码如下：

FileDownloadService downloadService = ServiceGenerator.create(FileDownloadService.class);

Call<ResponseBody> call = downloadService.downloadFileWithDynamicUrlSync(fileUrl);

call.enqueue(new Callback<ResponseBody>() {  
    @Override
    public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {
        if (response.isSuccess()) {
            Log.d(TAG, "server contacted and has file");

            boolean writtenToDisk = writeResponseBodyToDisk(response.body());

            Log.d(TAG, "file download was a success? " + writtenToDisk);
        } else {
            Log.d(TAG, "server contact failed");
        }
    }

    @Override
    public void onFailure(Call<ResponseBody> call, Throwable t) {
        Log.e(TAG, "error");
    }
});

如果你对 ServiceGenerator.create() 感到迷惑，可以回头看我翻译的系列第一篇文章 Retrofit-开始并创建一个Android客户端，一旦我们创建了这个service，就可以像其他请求一样来调用这个请求，当然这只是第一步，真正重要的功能是 writeResponseBodyToDisk() 将返回的 ResponseBoby写到磁盘中。

怎么保存文件

这个 writeResponseBodyToDisk() 方法拿到了 ResponseBody 对象，然后从里面读流并写到磁盘中，这个代码只是看起来比较复杂。

private boolean writeResponseBodyToDisk(ResponseBody body) {  
    try {
        // todo change the file location/name according to your needs
        File futureStudioIconFile = new File(getExternalFilesDir(null) + File.separator + "Future Studio Icon.png");

        InputStream inputStream = null;
        OutputStream outputStream = null;

        try {
            byte[] fileReader = new byte[4096];

            long fileSize = body.contentLength();
            long fileSizeDownloaded = 0;

            inputStream = body.byteStream();
            outputStream = new FileOutputStream(futureStudioIconFile);

            while (true) {
                int read = inputStream.read(fileReader);

                if (read == -1) {
                    break;
                }

                outputStream.write(fileReader, 0, read);

                fileSizeDownloaded += read;

                Log.d(TAG, "file download: " + fileSizeDownloaded + " of " + fileSize);
            }

            outputStream.flush();

            return true;
        } catch (IOException e) {
            return false;
        } finally {
            if (inputStream != null) {
                inputStream.close();
            }

            if (outputStream != null) {
                outputStream.close();
            }
        }
    } catch (IOException e) {
        return false;
    }
}

大部分的代码只是 Java I/O的模板代码，你可能需要去自己改变第一行文件保存的地址和文件保存的名字。当你做完这些后，已经算是准备好了使用Retrofit来下载文件，但是，仍然还有一些事情没有解决，比如一个主要的问题：默认情况下，Retrofit会将服务器的返回全部放到内存之中，这个操作在返回JSON或者XML时是OK的，因为这些都比较小，但是大文件就非常容易导致 Out-of-Memory-Errors。
如果你的应用需要下载一些大的文件，我们强烈建议阅读下面这一段。

谨防大文件：使用 @Streaming

如果你在下载一个大的文件，Retrofit默认会将整个文件移到内存中，为了避免这种情况，我们需要为这种请求加一个特殊的注解：

@Streaming
@GET
Call<ResponseBody> downloadFileWithDynamicUrlAsync(@Url String fileUrl);  

加入这个 @Streaming 声明后并不是将整个文件全部放入内存中，而是实时的返回字节码。值得注意的是，如果你在添加了 @Streaming声明的情况下依然使用上面的方式来进行下载，Android就会抛出一个溢出 android.os.NetworkOnMainThreadException。
所以，最后一步就是把请求包装到一个另外的线程中，比如使用 AsyncTask

final FileDownloadService downloadService =  
                ServiceGenerator.create(FileDownloadService.class);

new AsyncTask<Void, Long, Void>() {  
   @Override
   protected Void doInBackground(Void... voids) {
       Call<ResponseBody> call = downloadService.downloadFileWithDynamicUrlSync(fileUrl);
       call.enqueue(new Callback<ResponseBody>() {
           @Override
           public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {
               if (response.isSuccess()) {
                   Log.d(TAG, "server contacted and has file");

                   boolean writtenToDisk = writeResponseBodyToDisk(response.body());

                   Log.d(TAG, "file download was a success? " + writtenToDisk);
               }
               else {
                   Log.d(TAG, "server contact failed");
               }
           }
       return null;
   }
}.execute(); 

如果你记住了一个 @Streaming 声明和上面这一段，你就能用Retrofit来有效的下载大文件而不是出现内存溢出的问题。