Android開源網(wǎng)絡(luò)請(qǐng)求框架Retrofit的介紹使用

Retrofit是Square公司開發(fā)的一款針對(duì)Android網(wǎng)絡(luò)請(qǐng)求的框架，Retrofit2底層基于OkHttp實(shí)現(xiàn)的，OkHttp現(xiàn)在已經(jīng)得到Google官方認(rèn)可，大量的app都采用OkHttp做網(wǎng)絡(luò)請(qǐng)求，其源碼詳見 OkHttp Github 。

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

首先先來看一個(gè)完整Get請(qǐng)求是如何實(shí)現(xiàn)：

1. 創(chuàng)建業(yè)務(wù)請(qǐng)求接口，具體代碼如下：

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

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

2. 需要?jiǎng)?chuàng)建一個(gè)Retrofit的示例，并完成相應(yīng)的配置

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

   這里的baseUrl就是網(wǎng)絡(luò)請(qǐng)求URL相對(duì)固定的地址，一般包括請(qǐng)求協(xié)議（如Http）、域名或IP地址、端口號(hào)等，當(dāng)然還會(huì)有很多其他的配置，下文會(huì)詳細(xì)介紹。還有addConverterFactory方法表示需要用什么轉(zhuǎn)換器來解析返回值，GsonConverterFactory.create()表示調(diào)用Gson庫(kù)來解析json返回值，具體的下文還會(huì)做詳細(xì)介紹。

3. 調(diào)用請(qǐng)求方法，并得到Call實(shí)例

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

   Call其實(shí)在Retrofit中就是行使網(wǎng)絡(luò)請(qǐng)求并處理返回值的類，調(diào)用的時(shí)候會(huì)把需要拼接的參數(shù)傳遞進(jìn)去，此處最后得到的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實(shí)例完成同步或異步請(qǐng)求

• 同步請(qǐng)求

  BookSearchResponse  = .().body();

  這里需要注意的是網(wǎng)絡(luò)請(qǐng)求一定要在子線程中完成，不能直接在UI線程執(zhí)行，不然會(huì)crash

• 異步請(qǐng)求

  .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來進(jìn)行網(wǎng)絡(luò)請(qǐng)求了。接下來會(huì)對(duì)不同的請(qǐng)求方式做進(jìn)一步的說明。

Get方法

1. @Query

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

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

addQueryParameter就是添加請(qǐng)求參數(shù)的具體代碼，這種方式比較適用于所有的請(qǐng)求都需要添加的參數(shù)，一般現(xiàn)在的網(wǎng)絡(luò)請(qǐng)求都會(huì)添加token作為用戶標(biāo)識(shí)，那么這種方式就比較適合。

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

addInterceptor( CustomInterceptor())

2. @QueryMap

如果Query參數(shù)比較多，那么可以通過@QueryMap方式將所有的參數(shù)集成在一個(gè)Map統(tǒng)一傳遞，還以上文中的get請(qǐng)求方法為例

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

調(diào)用的時(shí)候?qū)⑺械膮?shù)集合在統(tǒng)一的map中即可

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

3. Query集合

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

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

最后得到的url地址為

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

4. Query非必填

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

針對(duì)文章開頭提到的get的請(qǐng)求，加入按以下方式調(diào)用

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

那么得到的url地址為

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

5. @Path

如果請(qǐng)求的相對(duì)地址也是需要調(diào)用方傳遞，那么可以使用@Path注解，示例代碼如下：

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

業(yè)務(wù)方想要在地址后面拼接書籍id，那么通過Path注解可以在具體的調(diào)用場(chǎng)景中動(dòng)態(tài)傳遞，具體的調(diào)用方式如下：

<BookResponse>  = mBlueService.getBook();

此時(shí)的url地址為

:

@Path可以用于任何請(qǐng)求方式，包括Post，Put，Delete等等

Post請(qǐng)求

1. @field

Post請(qǐng)求需要把請(qǐng)求參數(shù)放置在請(qǐng)求體中，而非拼接在url后面，先來看一個(gè)簡(jiǎn)單的例子

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

這里有幾點(diǎn)需要說明的

• @FormUrlEncoded將會(huì)自動(dòng)將請(qǐng)求參數(shù)的類型調(diào)整為application/x-www-form-urlencoded，假如content傳遞的參數(shù)為Good Luck，那么最后得到的請(qǐng)求體就是

  =Good+Luck

  FormUrlEncoded不能用于Get請(qǐng)求

• @Field注解將每一個(gè)請(qǐng)求參數(shù)都存放至請(qǐng)求體中，還可以添加encoded參數(shù)，該參數(shù)為boolean型，具體的用法為

  (value = , encoded = )  book

  encoded參數(shù)為true的話，key-value-pair將會(huì)被編碼，即將中文和特殊字符進(jìn)行編碼轉(zhuǎn)換

2. @FieldMap

上述Post請(qǐng)求有4個(gè)請(qǐng)求參數(shù)，假如說有更多的請(qǐng)求參數(shù)，那么通過一個(gè)一個(gè)的參數(shù)傳遞就顯得很麻煩而且容易出錯(cuò)，這個(gè)時(shí)候就可以用FieldMap

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

3. @Body

如果Post請(qǐng)求參數(shù)有多個(gè)，那么統(tǒng)一封裝到類中應(yīng)該會(huì)更好，這樣維護(hù)起來會(huì)非常方便

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

   {
      ;
      ;
      ;
      ;
}

其他請(qǐng)求方式

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

上傳

上傳因?yàn)樾枰玫組ultipart，所以需要單獨(dú)拿出來介紹，先看一個(gè)具體上傳的例子

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

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

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

接下來我們還需要在Activity和Fragment中實(shí)現(xiàn)兩個(gè)工具方法，代碼如下：

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 = ... 

 創(chuàng)建上傳的service實(shí)例
FileUploadService service =  
        ServiceGenerator.createService(FileUploadService.class);

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

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

 最后執(zhí)行異步請(qǐng)求操作
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());
    }
});

三、其他必須知道的事項(xiàng)

1. 添加自定義的header

Retrofit提供了兩個(gè)方式定義Http請(qǐng)求頭參數(shù)：靜態(tài)方法和動(dòng)態(tài)方法，靜態(tài)方法不能隨不同的請(qǐng)求進(jìn)行變化，頭部信息在初始化的時(shí)候就固定了。而動(dòng)態(tài)方法則必須為每個(gè)請(qǐng)求都要單獨(dú)設(shè)置。

• 靜態(tài)方法

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

  當(dāng)然你想添加多個(gè)header參數(shù)也是可以的，寫法也很簡(jiǎn)單

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

  此外也可以通過Interceptor來定義靜態(tài)請(qǐng)求頭

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

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

  然后在OkHttp創(chuàng)建Client實(shí)例時(shí)，添加RequestInterceptor即可

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

• 動(dòng)態(tài)方法

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

2. 網(wǎng)絡(luò)請(qǐng)求日志

調(diào)試網(wǎng)絡(luò)請(qǐng)求的時(shí)候經(jīng)常需要關(guān)注一下請(qǐng)求參數(shù)和返回值，以便判斷和定位問題出在哪里，Retrofit官方提供了一個(gè)很方便查看日志的Interceptor，你可以控制你需要的打印信息類型，使用方法也很簡(jiǎn)單。

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

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

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

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

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

• NONE

  沒有任何日志信息

• Basic

  打印請(qǐng)求類型，URL，請(qǐng)求體大小，返回值狀態(tài)以及返回值的大小

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

• Headers

  打印返回請(qǐng)求和返回值的頭部信息，請(qǐng)求類型，URL以及返回值狀態(tài)碼

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

  打印請(qǐng)求和返回值的頭部和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. 為某個(gè)請(qǐng)求設(shè)置完整的URL

假如說你的某一個(gè)請(qǐng)求不是以base_url開頭該怎么辦呢？別著急，辦法很簡(jiǎn)單，看下面這個(gè)例子你就懂了

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

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

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

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

4. 取消請(qǐng)求

Call提供了cancel方法可以取消請(qǐng)求，前提是該請(qǐng)求還沒有執(zhí)行

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, );
        }
    }
});
    }

四、結(jié)語

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