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%20feelings
1

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";

@NonNull
private RequestBody createPartFromString(String descriptionString) {  
    return RequestBody.create(
            MediaType.parse(MULTIPART_FORM_DATA), descriptionString);
}

@NonNull
private 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);

// 添加其他的part
RequestBody 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
@GET
Call<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需要在所有參數之前：

@POST
Call<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 GMT
D/OkHttp: Content-Type: application/json; charset=utf-8
D/OkHttp: Transfer-Encoding: chunked
D/OkHttp: Connection: keep-alive
D/OkHttp: Keep-Alive: timeout=30
D/OkHttp: Vary: Accept-Encoding
D/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMT
D/OkHttp: Pragma: no-cache
D/OkHttp: Cache-Control: must-revalidate, no-cache, private
D/OkHttp: Set-Cookie: bid=D6UtQR5N9I4; Expires=Sun, 06-Aug-17 14:26:03 GMT; Domain=.douban.com; Path=/
D/OkHttp: X-DOUBAN-NEWBID: D6UtQR5N9I4
D/OkHttp: X-DAE-Node: dis17
D/OkHttp: X-DAE-App: book
D/OkHttp: Server: dae
D/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-alive
D/OkHttp: Date: Sat, 06 Aug 2016 14:29:11 GMT
D/OkHttp: Keep-Alive: timeout=30
D/OkHttp: Content-Type: application/json; charset=utf-8
D/OkHttp: Vary: Accept-Encoding
D/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMT
D/OkHttp: Transfer-Encoding: chunked
D/OkHttp: Pragma: no-cache
D/OkHttp: Connection: keep-alive
D/OkHttp: Cache-Control: must-revalidate, no-cache, private
D/OkHttp: Keep-Alive: timeout=30
D/OkHttp: Set-Cookie: bid=ESnahto1_Os; Expires=Sun, 06-Aug-17 14:29:11 GMT; Domain=.douban.com; Path=/
D/OkHttp: Vary: Accept-Encoding
D/OkHttp: X-DOUBAN-NEWBID: ESnahto1_Os
D/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMT
D/OkHttp: X-DAE-Node: dis5
D/OkHttp: Pragma: no-cache
D/OkHttp: X-DAE-App: book
D/OkHttp: Cache-Control: must-revalidate, no-cache, private
D/OkHttp: Server: dae
D/OkHttp: Set-Cookie: bid=5qefVyUZ3KU; Expires=Sun, 06-Aug-17 14:29:11 GMT; Domain=.douban.com; Path=/
D/OkHttp: X-DOUBAN-NEWBID: 5qefVyUZ3KU
D/OkHttp: X-DAE-Node: dis17
D/OkHttp: X-DAE-App: book
D/OkHttp: Server: dae
D/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)