Retrofit用法詳解
Retrofit是Square公司開發的一款針對Android網絡請求的框架，Retrofit2底層基于OkHttp實現的，OkHttp現在已經得到Google官方認可，大量的app都采用OkHttp做網絡請求，其源碼詳見OkHttp Github。
本文全部是在Retrofit2.0+版本基礎上論述，所用例子全部來自豆瓣Api
首先先來看一個完整Get請求是如何實現：
創建業務請求接口，具體代碼如下：
publicinterfaceBlueService{
@GET("book/search")
CallgetSearchBooks(@Query("q") String name,
@Query("tag") String tag,@Query("start") int start,
@Query("count") int count);
}
這里需要稍作說明，@GET注解就表示get請求，@Query表示請求參數，將會以key=value的方式拼接在url后面
需要創建一個Retrofit的示例，并完成相應的配置
Retrofitretrofit = new Retrofit.Builder()
.baseUrl("https://api.douban.com/v2/")
.addConverterFactory(GsonConverterFactory.create())
.build();
BlueServiceservice = retrofit.create(BlueService.class);
這里的baseUrl就是網絡請求URL相對固定的地址，一般包括請求協議（如Http）、域名或IP地址、端口號等，當然還會有很多其他的配置，下文會詳細介紹。還有addConverterFactory方法表示需要用什么轉換器來解析返回值，GsonConverterFactory.create()表示調用Gson庫來解析json返回值，具體的下文還會做詳細介紹。
調用請求方法，并得到Call實例
Callcall= mBlueService.getSearchBooks("小王子","",0,3);
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
使用Call實例完成同步或異步請求
同步請求
BookSearchResponse response =call.execute().body();
這里需要注意的是網絡請求一定要在子線程中完成，不能直接在UI線程執行，不然會crash
異步請求
call.enqueue(newCallback() {
@Override
publicvoid onResponse(Callcall,Responseresponse) {
asyncText.setText("異步請求結果: "+response.body().books.get(0).altTitle);
}
@Override
publicvoid onFailure(Callcall, 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方法請求參數都會以key=value的方式拼接在url后面，Retrofit提供了兩種方式設置請求參數。第一種就是像上文提到的直接在interface中添加@Query注解，還有一種方式是通過Interceptor實現，直接看如何通過Interceptor實現請求參數的添加。
publicclassCustomInterceptor implements Interceptor {
@Override
publicResponseintercept(Chain chain) throws IOException {
Requestrequest= chain.request();
HttpUrl httpUrl =request.url().newBuilder()
.addQueryParameter("token","tokenValue")
.build();
request=request.newBuilder().url(httpUrl).build();
return chain.proceed(request);
}
}
addQueryParameter就是添加請求參數的具體代碼，這種方式比較適用于所有的請求都需要添加的參數，一般現在的網絡請求都會添加token作為用戶標識，那么這種方式就比較適合。
創建完成自定義的Interceptor后，還需要在Retrofit創建client處完成添加
addInterceptor(newCustomInterceptor())
如果Query參數比較多，那么可以通過@QueryMap方式將所有的參數集成在一個Map統一傳遞，還以上文中的get請求方法為例
public interface BlueService{
@GET("book/search")
CallgetSearchBooks(@QueryMapMap options);
}
調用的時候將所有的參數集合在統一的map中即可
Mapoptions=newHashMap<>();
map.put("q","小王子");
map.put("tag", null);
map.put("start","0");
map.put("count","3");
Callcall= mBlueService.getSearchBooks(options);
假如你需要添加相同Key值，但是value卻有多個的情況，一種方式是添加多個@Query參數，還有一種簡便的方式是將所有的value放置在列表中，然后在同一個@Query下完成添加，實例代碼如下：
public interfaceBlueService{
@GET("book/search")
CallgetSearchBooks(@Query("q") List name);
}
最后得到的url地址為
https://api.douban.com/v2/book/search?q=leadership&q=beyond%20feelings
如果請求參數為非必填，也就是說即使不傳該參數，服務端也可以正常解析，那么如何實現呢？其實也很簡單，請求方法定義處還是需要完整的Query注解，某次請求如果不需要傳該參數的話，只需填充null即可。
針對文章開頭提到的get的請求，加入按以下方式調用
Callcall= 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
如果請求的相對地址也是需要調用方傳遞，那么可以使用@Path注解，示例代碼如下：
@GET("book/{id}")
CallgetBook(@Path("id") String id);
業務方想要在地址后面拼接書籍id，那么通過Path注解可以在具體的調用場景中動態傳遞，具體的調用方式如下：
Callcall= mBlueService.getBook("1003078");
此時的url地址為
https://api.douban.com/v2/book/1003078
@Path可以用于任何請求方式，包括Post，Put，Delete等等
Post請求需要把請求參數放置在請求體中，而非拼接在url后面，先來看一個簡單的例子
@FormUrlEncoded
@POST("book/reviews")
CalladdReviews(@Field("book") String bookId,@Field("title") String title,
@Field("content") String content,@Field("rating") String rating);
這里有幾點需要說明的
@FormUrlEncoded將會自動將請求參數的類型調整為application/x-www-form-urlencoded，假如content傳遞的參數為Good Luck，那么最后得到的請求體就是
content=Good+Luck
FormUrlEncoded不能用于Get請求
@Field注解將每一個請求參數都存放至請求體中，還可以添加encoded參數，該參數為boolean型，具體的用法為
@Field(value ="book", encoded =true)Stringbook
encoded參數為true的話，key-value-pair將會被編碼，即將中文和特殊字符進行編碼轉換
上述Post請求有4個請求參數，假如說有更多的請求參數，那么通過一個一個的參數傳遞就顯得很麻煩而且容易出錯，這個時候就可以用FieldMap
@FormUrlEncoded
@POST("book/reviews")
CalladdReviews(@FieldMapMap fields);
如果Post請求參數有多個，那么統一封裝到類中應該會更好，這樣維護起來會非常方便
@FormUrlEncoded
@POST("book/reviews")
Call addReviews(@Body Reviews reviews);
publicclassReviews {
publicStringbook;
publicStringtitle;
publicStringcontent;
publicStringrating;
}
除了Get和Post請求，Http請求還包括Put,Delete等等，用法和Post相似，所以就不再單獨介紹了。
上傳因為需要用到Multipart，所以需要單獨拿出來介紹，先看一個具體上傳的例子
首先還是需要新建一個interface用于定義上傳方法
publicinterfaceFileUploadService{
// 上傳單個文件
@Multipart
@POST("upload")
CalluploadFile(
@Part("description") RequestBody description,
@PartMultipartBody.Part file);
// 上傳多個文件
@Multipart
@POST("upload")
CalluploadMultipleFiles(
@Part("description") RequestBody description,
@PartMultipartBody.Part file1,
@PartMultipartBody.Part file2);
}
接下來我們還需要在Activity和Fragment中實現兩個工具方法，代碼如下：
publicstaticfinalString MULTIPART_FORM_DATA ="multipart/form-data";
@NonNull
privateRequestBodycreatePartFromString(String descriptionString){
returnRequestBody.create(
MediaType.parse(MULTIPART_FORM_DATA), descriptionString);
}
@NonNull
privateMultipartBody.PartprepareFilePart(String partName, Uri fileUri){
File file = FileUtils.getFile(this, fileUri);
// 為file建立RequestBody實例
RequestBody requestFile =
RequestBody.create(MediaType.parse(MULTIPART_FORM_DATA), file);
// MultipartBody.Part借助文件名完成最終的上傳
returnMultipartBody.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
RequestBodydescription= createPartFromString("hello, this is description speaking");
// 最后執行異步請求操作
Callcall= service.uploadMultipleFiles(description, body1, body2);
call.enqueue(newCallback() {
@Override
publicvoidonResponse(Callcall,
Response response) {
Log.v("Upload","success");
}
@Override
publicvoidonFailure(Callcall, Throwable t) {
Log.e("Upload error:", t.getMessage());
}
});
Retrofit提供了兩個方式定義Http請求頭參數：靜態方法和動態方法，靜態方法不能隨不同的請求進行變化，頭部信息在初始化的時候就固定了。而動態方法則必須為每個請求都要單獨設置。
靜態方法
publicinterfaceBlueService{
@Headers("Cache-Control: max-age=640000")
@GET("book/search")
CallgetSearchBooks(@Query("q") String name,
@Query("tag") String tag,@Query("start") int start,
@Query("count") int count);
}
當然你想添加多個header參數也是可以的，寫法也很簡單
publicinterfaceBlueService{
@Headers({
"Accept: application/vnd.yourapi.v1.full+json",
"User-Agent: Your-App-Name"
})
@GET("book/search")
CallgetSearchBooks(@Query("q") String name,
@Query("tag") String tag,@Query("start") int start,
@Query("count") int count);
}
此外也可以通過Interceptor來定義靜態請求頭
public classRequestInterceptorimplementsInterceptor{
@Override
publicResponseintercept(Chainchain) throwsIOException{
Requestoriginal = chain.request();
Requestrequest = original.newBuilder()
.header("User-Agent","Your-App-Name")
.header("Accept","application/vnd.yourapi.v1.full+json")
.method(original.method(), original.body())
.build();
returnchain.proceed(request);
}
}
添加header參數Request提供了兩個方法，一個是header(key, value)，另一個是.addHeader(key, value)，兩者的區別是，header()如果有重名的將會覆蓋，而addHeader()允許相同key值的header存在
然后在OkHttp創建Client實例時，添加RequestInterceptor即可
privatestaticOkHttpClientgetNewClient(){
returnnewOkHttpClient.Builder()
.addInterceptor(newRequestInterceptor())
.connectTimeout(DEFAULT_TIMEOUT, TimeUnit.SECONDS)
.build();
}
動態方法
publicinterfaceBlueService{
@GET("book/search")
CallgetSearchBooks(
@Header("Content-Range") String contentRange,
@Query("q") String name,@Query("tag") String tag,
@Query("start") int start,@Query("count") int count);
}
調試網絡請求的時候經常需要關注一下請求參數和返回值，以便判斷和定位問題出在哪里，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(newCustomInterceptor())
.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.1200OK (543ms, -1-byte body)
Headers
打印返回請求和返回值的頭部信息，請求類型，URL以及返回值狀態碼
<--200OKhttps://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,06Aug201614:26:03GMT
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,1Jan200601:00:00GMT
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信息
<--200OKhttps://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,06Aug201614:29:11GMT
D/OkHttp:Keep-Alive:timeout=30
D/OkHttp: Content-Type: application/json; charset=utf-8
D/OkHttp:Vary:Accept-Encoding
D/OkHttp:Expires:Sun,1Jan200601:00:00GMT
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,1Jan200601:00:00GMT
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-bytebody)
? 假如說你的某一個請求不是以base_url開頭該怎么辦呢？別著急，辦法很簡單，看下面這個例子你就懂了
publicinterfaceBlueService{
@GET
publicCall profilePicture(@UrlString url);
}
Retrofit retrofit = Retrofit.Builder()
.baseUrl("https://your.api.url/");
.build();
BlueService service = retrofit.create(BlueService.class);
service.profilePicture("https://s3.amazon.com/profile-picture/path");
? 直接用@Url注解的方式傳遞完整的url地址即可。
Call提供了cancel方法可以取消請求，前提是該請求還沒有執行
StringfileUrl ="http://futurestud.io/test.mp4";
Callcall=
downloadService.downloadFileWithDynamicUrlSync(fileUrl);
call.enqueue(new Callback() {
@Override
public void onResponse(Callcall, Response response) {
Log.d(TAG,"request success");
}
@Override
public void onFailure(Callcall, Throwable t) {
if(call.isCanceled()) {
Log.e(TAG,"request was cancelled");
}else{
Log.e(TAG,"other larger issue, i.e. no network connection?");
}
}
});
}
// 觸發某個動作，例如用戶點擊了取消請求的按鈕
call.cancel();
}
