Retrofit教程(1)

RxJava 与 Retrofit 结合的最佳实践

一. 简介

   Retrofit是Square公司开发的一款针对Android网络请求的框架，Retrofit2底层基于OkHttp实现的，OkHttp现在已经得到Google官方认可，大量的app都采用OkHttp做网络请求。[Retrofit github地址](https://github.com/square/retrofit)。[Retrofit官网](http://square.github.io/retrofit/)。

二. 这里主要介绍get、post、上传、下载

1.get方法

1. @Query

Get方法请求参数都会以key=value的方式拼接在url后面，Retrofit提供了两种方式设置请求参数。第一种就是像上文提到的直接在interface中添加@Query注解，还有一种方式是通过Interceptor实现，直接看如何通过Interceptor实现请求参数的添加。

public class CustomInterceptor implements Interceptor {    @Override    public Response intercept(Chain chain) throws IOException {        Request request = chain.request();        HttpUrl httpUrl = request.url().newBuilder()                .addQueryParameter("token", "tokenValue")                .build();        request = request.newBuilder().url(httpUrl).build();        return chain.proceed(request);    }}

addQueryParameter就是添加请求参数的具体代码，这种方式比较适用于所有的请求都需要添加的参数，一般现在的网络请求都会添加token作为用户标识，那么这种方式就比较适合。

addInterceptor(new CustomInterceptor())

2. @QueryMap

如果Query参数比较多，那么可以通过@QueryMap方式将所有的参数集成在一个Map统一传递，还以上文中的get请求方法为例

public interface BlueService {    @GET("book/search")    Call<BookSearchResponse> getSearchBooks(@QueryMap Map<String, String> options);}

调用的时候将所有的参数集合在统一的map中即可

Map<String, String> options = new HashMap<>();map.put("q", "小王子");map.put("tag", null);map.put("start", "0");map.put("count", "3");Call<BookSearchResponse> call = mBlueService.getSearchBooks(options);

3. Query集合

假如你需要添加相同Key值，但是value却有多个的情况，一种方式是添加多个@Query参数，还有一种简便的方式是将所有的value放置在列表中，然后在同一个@Query下完成添加，实例代码如下：

public interface BlueService {    @GET("book/search")    Call<BookSearchResponse> getSearchBooks(@Query("q") List<String> name);}

最后得到的url地址为

https://api.douban.com/v2/book/search?q=leadership&q=beyond%20feelings1

4. Query非必填

如果请求参数为非必填，也就是说即使不传该参数，服务端也可以正常解析，请求方法定义处还是需要完整的Query注解，某次请求如果不需要传该参数的话，只需填充null即可。

针对文章开头提到的get的请求，加入按以下方式调用

Call<BookSearchResponse> call = mBlueService.getSearchBooks("小王子", null, 0, 3);

那么得到的url地址为

https://api.douban.com/v2/book/search?q=%E5%B0%8F%E7%8E%8B%E5%AD%90&start=0&count=3

5. @Path

如果请求的相对地址也是需要调用方传递，那么可以使用@Path注解，示例代码如下：

@GET("book/{id}")Call<BookResponse> getBook(@Path("id") String id);

业务方想要在地址后面拼接书籍id，那么通过Path注解可以在具体的调用场景中动态传递，具体的调用方式如下：

Call<BookResponse> call = mBlueService.getBook("1003078");

此时的url地址为

https://api.douban.com/v2/book/1003078

@Path可以用于任何请求方式，包括Post，Put，Delete等等

Post请求

1. @field

Post请求需要把请求参数放置在请求体中，而非拼接在url后面，先来看一个简单的例子

@FormUrlEncoded @POST("book/reviews") Call<String> addReviews(@Field("book") String bookId, @Field("title") String title, @Field("content") String content, @Field("rating") String rating);

这里有几点需要说明的
1. @FormUrlEncoded将会自动将请求参数的类型调整为application/x-www-form-urlencoded，假如content传递的参数为Good Luck，那么最后得到的请求体就是content=Good+Luck
2. @Field注解将每一个请求参数都存放至请求体中，还可以添加encoded参数，该参数为boolean型，具体的用法为

@Field(value = "book", encoded = true) String book

encoded参数为true的话，key-value-pair将会被编码，即将中文和特殊字符进行编码转换

2.@FieldMap

上述Post请求有4个请求参数，假如说有更多的请求参数，那么通过一个一个的参数传递就显得很麻烦而且容易出错，这个时候就可以用FieldMap

3. @Body

如果Post请求参数有多个，那么统一封装到类中应该会更好，这样维护起来会非常方便

@FormUrlEncoded@POST("book/reviews")Call<String> addReviews(@Body Reviews reviews);public class Reviews {    public String book;    public String title;    public String content;    public String rating;}

除了Get和Post请求，Http请求还包括Put,Delete等等，用法和Post相似，所以就不再单独介绍了。

文件上传

上传因为需要用到Multipart，所以需要单独拿出来介绍，先看一个具体上传的例子
首先还是需要新建一个interface用于定义上传方法

public interface FileUploadService {      // 上传单个文件    @Multipart    @POST("upload")    Call<ResponseBody> uploadFile(            @Part("description") RequestBody description,            @Part MultipartBody.Part file);    // 上传多个文件    @Multipart    @POST("upload")    Call<ResponseBody> uploadMultipleFiles(            @Part("description") RequestBody description,            @Part MultipartBody.Part file1,            @Part MultipartBody.Part file2);}

接下来我们还需要在Activity和Fragment中实现两个工具方法，代码如下：

public static final String MULTIPART_FORM_DATA = "multipart/form-data";@NonNullprivate RequestBody createPartFromString(String descriptionString) {      return RequestBody.create(            MediaType.parse(MULTIPART_FORM_DATA), descriptionString);}@NonNullprivate MultipartBody.Part prepareFilePart(String partName, Uri fileUri) {      File file = FileUtils.getFile(this, fileUri);    // 为file建立RequestBody实例    RequestBody requestFile =        RequestBody.create(MediaType.parse(MULTIPART_FORM_DATA), file);    // MultipartBody.Part借助文件名完成最终的上传    return MultipartBody.Part.createFormData(partName, file.getName(), requestFile);}

好了，接下来就是最终的上传文件代码了

Uri file1Uri = ... // 从文件选择器或者摄像头中获取 Uri file2Uri = ... // 创建上传的service实例FileUploadService service =          ServiceGenerator.createService(FileUploadService.class);// 创建文件的part (photo, video, ...)MultipartBody.Part body1 = prepareFilePart("video", file1Uri);  MultipartBody.Part body2 = prepareFilePart("thumbnail", file2Uri);// 添加其他的partRequestBody description = createPartFromString("hello, this is description speaking");// 最后执行异步请求操作Call<ResponseBody> call = service.uploadMultipleFiles(description, body1, body2);  call.enqueue(new Callback<ResponseBody>() {      @Override    public void onResponse(Call<ResponseBody> call,            Response<ResponseBody> response) {        Log.v("Upload", "success");    }    @Override    public void onFailure(Call<ResponseBody> call, Throwable t) {        Log.e("Upload error:", t.getMessage());    }});

文件下载

文件下载我们需要使用@Url和 @Streaming ，@Url动态Url正好非常适合我们的场景，而使用@Streaming注解可以让我们下载非常大的文件时，避免Retrofit将整个文件读进内存，否则可能造成OOM现象。

    @Streaming    @GET    Call<ResponseBody> downloadFileByDynamicUrlAsync(@Url String downloadUrl);

需要注意的是我们需要使用Retrofitcall.execute同步获取ResponseBody，那么我们就需要放进一个单独的工作线程中:

new AsyncTask<Void, Long, Void>() {         @Override            protected Void doInBackground(Void... voids) {                Call<ResponseBody> call = myTestApiService.downloadFileByDynamicUrlAsync(API_BASE_URL.concat("/res/atom-amd64.deb"));              try {                    Response<ResponseBody> response = call.execute();                    boolean writtenToDisk = writeResponseBodyToDisk(response.body());                    Log.d(TAG, "下载文件 " + writtenToDisk);                } catch (IOException e) {                    e.printStackTrace();                }                return null;            }            @Override            protected void onPreExecute() {                super.onPreExecute();            }        }.execute();

最后我们需要将文件写入磁盘根目录中：

//写入到磁盘根目录    private boolean writeResponseBodyToDisk(ResponseBody body) {        try {            File futureStudioIconFile = new File(Environment.getExternalStorageDirectory() + File.separator + "atom.deb");            InputStream inputStream = null;            OutputStream outputStream = null;            try {                byte[] fileReader = new byte[4096];                final 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);                    final long finalFileSizeDownloaded = fileSizeDownloaded;                    runOnUiThread(new Runnable() {                        @Override                        public void run() {                            resultTextView.setText("file download: " + finalFileSizeDownloaded + " 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;        }    }

这样我们就可以非常高效的下载大文件了，最后友情提醒(如果是6.0以上另外再申请权限)：

<uses-permission android:name="android.permission.INTERNET" />    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

其它注解

1. @Headers

@Headers：用于在方法添加请求头：

    @POST("test/sayHi")    @Headers("Accept-Encoding: application/json")    Call<ResultBean> postSayHi(@Body UserBean userBean, @Header("city") String city);

2. @Streaming

如果您正在下载一个大文件，Retrofit2将尝试将整个文件移动到内存中。为了避免这种，我们必须向请求声明中添加一个特殊的注解@Streaming

@Streaming@GETCall<ResponseBody> downloadFileByDynamicUrlAsync(@Url String fileUrl);

3.@Header

用于在方法参数里动态添加请求头：

Call<ResultBean> postSayHi(@Header("city") String city);

public class RequestInterceptor implements Interceptor {  @Override  public Response intercept(Chain chain) throws IOException {      Request original = chain.request();      Request request = original.newBuilder()          .header("User-Agent", "Your-App-Name")          .header("Accept", "application/vnd.yourapi.v1.full+json")          .method(original.method(), original.body())          .build();      return chain.proceed(request);  }}

4. @Url

使用动态的请求的网址，会复写之前的baseUrl，值得注意的是@Url需要在所有参数之前：

@POSTCall<ResultBean> postSayHelloByURL(@Url String url,@Query("username") String username, @Query("age") String age);

5. @Part

6. @PartMap

这两个用于上传文件，与@MultiPart注解结合使用

    @Multipart    @POST("test/upload")    Call<ResultBean> upload(@Part("file\"; filename=\"launcher_icon.png") RequestBody file);

添加日志

调试网络请求的时候经常需要关注一下请求参数和返回值，以便判断和定位问题出在哪里，Retrofit官方提供了一个很方便查看日志的Interceptor，你可以控制你需要的打印信息类型，使用方法也很简单。

首先需要在build.gradle文件中引入logging-interceptor

compile 'com.squareup.okhttp3:logging-interceptor:3.4.1'

同上文提到的CustomInterceptor和RequestInterceptor一样，添加到OkHttpClient创建处即可，完整的示例代码如下：

private static OkHttpClient getNewClient(){    HttpLoggingInterceptor logging = new HttpLoggingInterceptor();    logging.setLevel(HttpLoggingInterceptor.Level.BODY);    return new OkHttpClient.Builder()           .addInterceptor(new CustomInterceptor())           .addInterceptor(logging)           .connectTimeout(DEFAULT_TIMEOUT, TimeUnit.SECONDS)           .build();}

HttpLoggingInterceptor提供了4中控制打印信息类型的等级，分别是NONE，BASIC，HEADERS，BODY，接下来分别来说一下相应的打印信息类型。
-NONE
没有任何日志信息
-Basic
打印请求类型，URL，请求体大小，返回值状态以及返回值的大小

D/HttpLoggingInterceptor$Logger: --> POST /upload HTTP/1.1 (277-byte body)  D/HttpLoggingInterceptor$Logger: <-- HTTP/1.1 200 OK (543ms, -1-byte body)  

-Headers
打印返回请求和返回值的头部信息，请求类型，URL以及返回值状态码

<-- 200 OK https://api.douban.com/v2/book/search?q=%E5%B0%8F%E7%8E%8B%E5%AD%90&start=0&count=3&token=tokenValue (3787ms)D/OkHttp: Date: Sat, 06 Aug 2016 14:26:03 GMTD/OkHttp: Content-Type: application/json; charset=utf-8D/OkHttp: Transfer-Encoding: chunkedD/OkHttp: Connection: keep-aliveD/OkHttp: Keep-Alive: timeout=30D/OkHttp: Vary: Accept-EncodingD/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMTD/OkHttp: Pragma: no-cacheD/OkHttp: Cache-Control: must-revalidate, no-cache, privateD/OkHttp: Set-Cookie: bid=D6UtQR5N9I4; Expires=Sun, 06-Aug-17 14:26:03 GMT; Domain=.douban.com; Path=/D/OkHttp: X-DOUBAN-NEWBID: D6UtQR5N9I4D/OkHttp: X-DAE-Node: dis17D/OkHttp: X-DAE-App: bookD/OkHttp: Server: daeD/OkHttp: <-- END HTTP

-Body
打印请求和返回值的头部和body信息

<-- 200 OK https://api.douban.com/v2/book/search?q=%E5%B0%8F%E7%8E%8B%E5%AD%90&tag=&start=0&count=3&token=tokenValue (3583ms)D/OkHttp: Connection: keep-aliveD/OkHttp: Date: Sat, 06 Aug 2016 14:29:11 GMTD/OkHttp: Keep-Alive: timeout=30D/OkHttp: Content-Type: application/json; charset=utf-8D/OkHttp: Vary: Accept-EncodingD/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMTD/OkHttp: Transfer-Encoding: chunkedD/OkHttp: Pragma: no-cacheD/OkHttp: Connection: keep-aliveD/OkHttp: Cache-Control: must-revalidate, no-cache, privateD/OkHttp: Keep-Alive: timeout=30D/OkHttp: Set-Cookie: bid=ESnahto1_Os; Expires=Sun, 06-Aug-17 14:29:11 GMT; Domain=.douban.com; Path=/D/OkHttp: Vary: Accept-EncodingD/OkHttp: X-DOUBAN-NEWBID: ESnahto1_OsD/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMTD/OkHttp: X-DAE-Node: dis5D/OkHttp: Pragma: no-cacheD/OkHttp: X-DAE-App: bookD/OkHttp: Cache-Control: must-revalidate, no-cache, privateD/OkHttp: Server: daeD/OkHttp: Set-Cookie: bid=5qefVyUZ3KU; Expires=Sun, 06-Aug-17 14:29:11 GMT; Domain=.douban.com; Path=/D/OkHttp: X-DOUBAN-NEWBID: 5qefVyUZ3KUD/OkHttp: X-DAE-Node: dis17D/OkHttp: X-DAE-App: bookD/OkHttp: Server: daeD/OkHttp: {"count":3,"start":0,"total":778,"books":[{"rating":{"max":10,"numRaters":202900,"average":"9.0","min":0},"subtitle":"","author":["[法] 圣埃克苏佩里"],"pubdate":"2003-8","tags":[{"count":49322,"name":"小王子","title":"小王子"},{"count":41381,"name":"童话","title":"童话"},{"count":19773,"name":"圣埃克苏佩里","title":"圣埃克苏佩里"}D/OkHttp: <-- END HTTP (13758-byte body)