Android開源網絡請求框架Retrofit的介紹使用

Retrofit是Square公司開發的一款針對Android網絡請求的框架，Retrofit2底層基于OkHttp實現的，OkHttp現在已經得到Google官方認可，大量的app都采用OkHttp做網絡請求，其源碼詳見 OkHttp Github 。

本文全部是在Retrofit2.0+版本基礎上論述，所用例子全部來自豆瓣Api

首先先來看一個完整Get請求是如何實現：

1. 創建業務請求接口，具體代碼如下：

      {
       ()
       Call<BookSearchResponse> getSearchBooks(() String name, 
       		() String tag, () int start, 
       		() int count);
   }

   這里需要稍作說明，@GET注解就表示get請求，@Query表示請求參數，將會以key=value的方式拼接在url后面

2. 需要創建一個Retrofit的示例，并完成相應的配置

    retrofit = new Retrofit.Builder()
       .baseUrl()
       .addConverterFactory(GsonConverterFactory.create())
       .build();
   
    service = retrofit.create(BlueService.class);

   這里的baseUrl就是網絡請求URL相對固定的地址，一般包括請求協議（如Http）、域名或IP地址、端口號等，當然還會有很多其他的配置，下文會詳細介紹。還有addConverterFactory方法表示需要用什么轉換器來解析返回值，GsonConverterFactory.create()表示調用Gson庫來解析json返回值，具體的下文還會做詳細介紹。

3. 調用請求方法，并得到Call實例

   <BookSearchResponse>  = mBlueService.getSearchBooks(, , , );

   Call其實在Retrofit中就是行使網絡請求并處理返回值的類，調用的時候會把需要拼接的參數傳遞進去，此處最后得到的url完整地址為

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

4. 使用Call實例完成同步或異步請求

• 同步請求

  BookSearchResponse  = .().body();

  這里需要注意的是網絡請求一定要在子線程中完成，不能直接在UI線程執行，不然會crash

• 異步請求

  .enqueue( Callback<BookSearchResponse>() {
    @Override
     void onResponse(<BookSearchResponse> , 		<BookSearchResponse> ) {
    	asyncText.setText( + .body().books.().altTitle);
    }
    @Override
     void onFailure(<BookSearchResponse> , Throwable t) {
  
    }
  });

二、如何使用

首先需要在build.gradle文件中引入需要的第三包，配置如下：

compile 'com.squareup.retrofit2:retrofit:2.1.0'
compile 'com.squareup.retrofit2:converter-gson:2.1.0'
compile 'com.squareup.retrofit2:adapter-rxjava:2.1.0'

引入完第三包接下來就可以使用Retrofit來進行網絡請求了。接下來會對不同的請求方式做進一步的說明。

Get方法

1. @Query

Get方法請求參數都會以key=value的方式拼接在url后面，Retrofit提供了兩種方式設置請求參數。第一種就是像上文提到的直接在interface中添加@Query注解，還有一種方式是通過Interceptor實現，直接看如何通過Interceptor實現請求參數的添加。

  CustomInterceptor implements Interceptor {
    @Override
      intercept(Chain chain) throws IOException {
          = chain.();
        HttpUrl httpUrl = .url().newBuilder()
                .addQueryParameter(, )
                .build();
         = .newBuilder().url(httpUrl).build();
        return chain.proceed();
    }
}

addQueryParameter就是添加請求參數的具體代碼，這種方式比較適用于所有的請求都需要添加的參數，一般現在的網絡請求都會添加token作為用戶標識，那么這種方式就比較適合。

創建完成自定義的Interceptor后，還需要在Retrofit創建client處完成添加

addInterceptor( CustomInterceptor())

2. @QueryMap

如果Query參數比較多，那么可以通過@QueryMap方式將所有的參數集成在一個Map統一傳遞，還以上文中的get請求方法為例

   {
    ()
    Call<BookSearchResponse> getSearchBooks( Map<String, String> options);
}

調用的時候將所有的參數集合在統一的map中即可

Map<, > options =  HashMap<>();
map.put(, );
map.put(, );
map.put(, );
map.put(, );
<BookSearchResponse>  = mBlueService.getSearchBooks(options);

3. Query集合

假如你需要添加相同Key值，但是value卻有多個的情況，一種方式是添加多個@Query參數，還有一種簡便的方式是將所有的value放置在列表中，然后在同一個@Query下完成添加，實例代碼如下：

   {
    ()
    Call<BookSearchResponse> getSearchBooks(() List<String> name);
}

最后得到的url地址為

http//api.douban./v2/book/?q=leadership&q=beyond%feelings

4. Query非必填

如果請求參數為非必填，也就是說即使不傳該參數，服務端也可以正常解析，那么如何實現呢？其實也很簡單，請求方法定義處還是需要完整的Query注解，某次請求如果不需要傳該參數的話，只需填充null即可。

針對文章開頭提到的get的請求，加入按以下方式調用

<BookSearchResponse>  = mBlueService.getSearchBooks(, , , );

那么得到的url地址為

https://api.douban.com/v2/book/search?q=&=&count=

5. @Path

如果請求的相對地址也是需要調用方傳遞，那么可以使用@Path注解，示例代碼如下：

()
Call<BookResponse> getBook(() String id);

業務方想要在地址后面拼接書籍id，那么通過Path注解可以在具體的調用場景中動態傳遞，具體的調用方式如下：

<BookResponse>  = mBlueService.getBook();

此時的url地址為

:

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

Post請求

1. @field

Post請求需要把請求參數放置在請求體中，而非拼接在url后面，先來看一個簡單的例子

()
Call<String> addReviews(() String bookId, () String title,
() String content, () String rating);

這里有幾點需要說明的

• @FormUrlEncoded將會自動將請求參數的類型調整為application/x-www-form-urlencoded，假如content傳遞的參數為Good Luck，那么最后得到的請求體就是

  =Good+Luck

  FormUrlEncoded不能用于Get請求

• @Field注解將每一個請求參數都存放至請求體中，還可以添加encoded參數，該參數為boolean型，具體的用法為

  (value = , encoded = )  book

  encoded參數為true的話，key-value-pair將會被編碼，即將中文和特殊字符進行編碼轉換

2. @FieldMap

上述Post請求有4個請求參數，假如說有更多的請求參數，那么通過一個一個的參數傳遞就顯得很麻煩而且容易出錯，這個時候就可以用FieldMap

()
Call<String> addReviews( Map<String, String> fields);

3. @Body

如果Post請求參數有多個，那么統一封裝到類中應該會更好，這樣維護起來會非常方便

()
Call<String> addReviews( Reviews reviews);

   {
      ;
      ;
      ;
      ;
}

其他請求方式

除了Get和Post請求，Http請求還包括Put,Delete等等，用法和Post相似，所以就不再單獨介紹了。

上傳

上傳因為需要用到Multipart，所以需要單獨拿出來介紹，先看一個具體上傳的例子

首先還是需要新建一個interface用于定義上傳方法

public interface FileUploadService {  
     上傳單個文件
    @Multipart
    @POST()
    Call<ResponseBody> uploadFile(
            @Part() RequestBody description,
            @Part MultipartBody.Part file);

     上傳多個文件
    @Multipart
    @POST()
    Call<ResponseBody> uploadMultipleFiles(
            @Part() RequestBody description,
            @Part MultipartBody.Part file1,
            @Part MultipartBody.Part file2);
}

接下來我們還需要在Activity和Fragment中實現兩個工具方法，代碼如下：

public    MULTIPART_FORM_DATA = ;


 RequestBody createPartFromString( descriptionString) {  
     RequestBody.create(
            MediaType.parse(MULTIPART_FORM_DATA), descriptionString);
}


 MultipartBody.Part prepareFilePart( partName,  fileUri) {  
    File file = FileUtils.getFile(, fileUri);

好了，接下來就是最終的上傳文件代碼了

Uri file1Uri = ...  從文件選擇器或者攝像頭中獲取 
Uri file2Uri = ... 

 創建上傳的service實例
FileUploadService service =  
        ServiceGenerator.createService(FileUploadService.class);

 創建文件的part (photo, video, ...)
MultipartBody.Part body1 = prepareFilePart(, file1Uri);  
MultipartBody.Part body2 = prepareFilePart(, file2Uri);

 添加其他的part
RequestBody description = createPartFromString();

 最后執行異步請求操作
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(, );
    }
    @Override
    public void onFailure(Call<ResponseBody> call, Throwable t) {
        Log.e(, t.getMessage());
    }
});

三、其他必須知道的事項

1. 添加自定義的header

Retrofit提供了兩個方式定義Http請求頭參數：靜態方法和動態方法，靜態方法不能隨不同的請求進行變化，頭部信息在初始化的時候就固定了。而動態方法則必須為每個請求都要單獨設置。

• 靜態方法

     {
  	()
      ()
      Call<BookSearchResponse> getSearchBooks(() String name, 
      		() String tag, () int start, 
      		() int count);
  }

  當然你想添加多個header參數也是可以的，寫法也很簡單

     {
  	({
          ,
          
      })
      ()
      Call<BookSearchResponse> getSearchBooks(() String name, 
      		() String tag, () int start, 
      		() int count);
  }

  此外也可以通過Interceptor來定義靜態請求頭

   {
      
      {
          Request original = chain.request();
          Request request = original.newBuilder()
              .header(, )
              .header(, )
              .method(original.method(), original.body())
              .build();
           chain.proceed(request);
      }
  }

  添加header參數Request提供了兩個方法，一個是 header(key, value) ，另一個是 .addHeader(key, value) ，兩者的區別是，header()如果有重名的將會覆蓋，而addHeader()允許相同key值的header存在

  然后在OkHttp創建Client實例時，添加RequestInterceptor即可

  {
      OkHttpClient.Builder()
      .addInterceptor( RequestInterceptor())
      .connectTimeout(DEFAULT_TIMEOUT, TimeUnit.SECONDS)
      .build();
  }

• 動態方法

     {
      ()
      Call<BookSearchResponse> getSearchBooks(
      () String contentRange, 
      () String name, () String tag, 
      () int start, () int count);
  }

2. 網絡請求日志

調試網絡請求的時候經常需要關注一下請求參數和返回值，以便判斷和定位問題出在哪里，Retrofit官方提供了一個很方便查看日志的Interceptor，你可以控制你需要的打印信息類型，使用方法也很簡單。

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

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

同上文提到的CustomInterceptor和RequestInterceptor一樣，添加到OkHttpClient創建處即可，完整的示例代碼如下：

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

HttpLoggingInterceptor提供了4中控制打印信息類型的等級，分別是NONE，BASIC，HEADERS，BODY，接下來分別來說一下相應的打印信息類型。

• NONE

  沒有任何日志信息

• Basic

  打印請求類型，URL，請求體大小，返回值狀態以及返回值的大小

  Dupload HTTP
   <-- HTTP/  OK (ms, - body)

• Headers

  打印返回請求和返回值的頭部信息，請求類型，URL以及返回值狀態碼

  <--  OK https:api.douban.combook
  OkHttp: Date: Sat,  Aug  :: GMT
  Djson; charset=utf-
  D
  OkHttp: Connection: keep-alive
  D
  OkHttp: Vary: Accept-Encoding
  D
  OkHttp: Pragma: no-cache
  D
  OkHttp: Set-Cookie: bid=D6UtQR5N9I4; Expires=Sun, -Aug- :: GMT; Domain=.douban.com; Path=
  OkHttp: X-DOUBAN-NEWBID: D6UtQR5N9I4
  D
  OkHttp: X-DAE-App: book
  D
  OkHttp: <--  HTTP

• Body

  打印請求和返回值的頭部和body信息

  <--  OK https:api.douban.combook
  OkHttp: Connection: keep-alive
  D
  OkHttp: Keep-Alive: timeout=
  Djson; charset=utf-
  D
  OkHttp: Expires: Sun,  Jan  :: GMT
  D
  OkHttp: Pragma: no-cache
  D
  OkHttp: Cache-Control: must-revalidate, no-cache, private
  D
  OkHttp: Set-Cookie: bid=ESnahto1_Os; Expires=Sun, -Aug- :: GMT; Domain=.douban.com; Path=
  OkHttp: Vary: Accept-Encoding
  D
  OkHttp: Expires: Sun,  Jan  :: GMT
  D
  OkHttp: Pragma: no-cache
  D
  OkHttp: Cache-Control: must-revalidate, no-cache, private
  D
  OkHttp: Set-Cookie: bid=qefVyUZ3KU; Expires=Sun, -Aug- :: GMT; Domain=.douban.com; Path=
  OkHttp: X-DOUBAN-NEWBID: qefVyUZ3KU
  D
  OkHttp: X-DAE-App: book
  D
  OkHttp: {:,:,:,:[{:{:,:,:,:},:,:[],:,:[{:,:,:},{:,:,:},{:,:,:}
  D

3. 為某個請求設置完整的URL

假如說你的某一個請求不是以base_url開頭該怎么辦呢？別著急，辦法很簡單，看下面這個例子你就懂了

 {  
    
     Call<ResponseBody> profilePicture( String url);
}

Retrofit retrofit = Retrofit.Builder()  
    .baseUrl();
    .build();

BlueService service = retrofit.create(BlueService.);  
service.profilePicture();

直接用@Url注解的方式傳遞完整的url地址即可。

4. 取消請求

Call提供了cancel方法可以取消請求，前提是該請求還沒有執行

String fileUrl = ;  
<ResponseBody>  =  
    downloadService.downloadFileWithDynamicUrlSync(fileUrl);
.enqueue( Callback<ResponseBody>() {  
    @Override
      onResponse(<ResponseBody> , Response<ResponseBody> response) {
        Log.d(TAG, );
    }

    @Override
      onFailure(<ResponseBody> , Throwable t) {
         (.isCanceled()) {
        	Log.e(TAG, );
        }  {
        	Log.e(TAG, );
        }
    }
});
    }

四、結語

關于Retrofit常用的方法基本上已經介紹完了，有些請求由于工作保密性的原因，所以就沒有放出來，但是基本的方法和操作都是有的，仿照文中提到的代碼就可以實現你想要的功能。參考了 國外的一則系列教程 和liangfei的一篇文章 圖解 Retrofit - ServiceMethod ，由于本人能力有限，有錯誤或者表述不準確的地方還望多多留言指正