前言
- 在
Andrroid
開發中,網路請求十分常用 - 而在
Android
網路請求庫中,Retrofit
是當下最熱的一個網路請求庫 - 如果對
Retrofit v2.0
的原始碼感興趣,可看文章:Android:手把手帶你深入剖析 Retrofit 2.0 原始碼
1. 簡介
特別注意:
- 準確來說,Retrofit 是一個 RESTful 的 HTTP 網路請求框架的封裝。
- 原因:網路請求的工作本質上是
OkHttp
完成,而 Retrofit 僅負責 網路請求介面的封裝
- App應用程式通過 Retrofit 請求網路,實際上是使用 Retrofit 介面層封裝請求引數、Header、Url 等資訊,之後由 OkHttp 完成後續的請求操作
- 在服務端返回資料之後,OkHttp 將原始的結果交給 Retrofit,Retrofit根據使用者的需求對結果進行解析
2. 與其他開源請求庫對比
除了Retrofit,如今Android中主流的網路請求框架有:
- Android-Async-Http
- volley
- OkHttp
我們通過上圖已經瞭解了它們的基本資訊下面看看他們之間的差異,明白了區別之處可以跟好的選擇在專案中該使用哪種更加適合當前專案開發。
各個網路請求庫的github地址
3. 使用介紹
使用 Retrofit 的步驟共有7個:
- 新增Retrofit庫的依賴
- 建立 接收伺服器返回資料 的類
- 建立 用於描述網路請求 的介面
- 建立 Retrofit 例項
- 建立 網路請求介面例項 並 配置網路請求引數
- 傳送網路請求(封裝了 資料轉換、執行緒切換的操作)
- 處理伺服器返回的資料
1:新增Retrofit庫的依賴
dependencies {
compile 'com.squareup.retrofit2:retrofit:2.0.2'
// Retrofit庫
compile 'com.squareup.okhttp3:okhttp:3.1.2'
// Okhttp庫
}
新增網路許可權:
<uses-permission android:name="android.permission.INTERNET"/>
複製程式碼
2:建立 接收伺服器返回資料 的類
Reception.java
public class Reception {
...
// 根據返回資料的格式和資料解析方式(Json、XML等)定義
}
複製程式碼
3:建立 用於描述網路請求 的介面
- Retrofit將 Http請求 抽象成 Java介面:採用 註解 描述網路請求引數 和配置網路請求引數
用 動態代理 動態 將該介面的註解“翻譯”成一個 Http 請求,最後再執行 Http 請求 注:介面中的每個方法的引數都需要使用註解標註,否則會報錯複製程式碼
public interface ApiManage {
@GET("blog/{id}")
Call<ResponseBody> getBlog(@Path("id") int id);
}
// @GET註解的作用:採用Get方法傳送網路請求
// getCall() = 接收網路請求資料的方法
// 其中返回型別為Call<*>,*是接收資料的類(即上面定義的Translation類)
// 如果想直接獲得Responsebody中的內容,可以定義網路請求返回值為Call<ResponseBody>
複製程式碼
註解型別
註解說明
第一類:網路請求方法
詳細說明:
a. @GET、@POST、@PUT、@DELETE、@HEAD
以上方法分別對應 HTTP中的網路請求方式
public interface GetRequest_Interface {
@GET("openapi.do?keyfrom=Yanzhikai&key=2032414398&type=data&doctype=json&version=1.1&q=car")
Call<Translation> getCall();
// @GET註解的作用:採用Get方法傳送網路請求
// getCall() = 接收網路請求資料的方法
// 其中返回型別為Call<*>,*是接收資料的類(即上面定義的Translation類)
}
複製程式碼
此處特意說明URL的組成:Retrofit把 網路請求的URL 分成了兩部分設定:
// 第1部分:在網路請求介面的註解設定
@GET("openapi.do?keyfrom=Yanzhikai&key=2032414398&type=data&doctype=json&version=1.1&q=car")
Call<Translation> getCall();
// 第2部分:在建立Retrofit例項時通過.baseUrl()設定
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("http://fanyi.youdao.com/") //設定網路請求的Url地址
.addConverterFactory(GsonConverterFactory.create()) //設定資料解析器
.build();
// 從上面看出:一個請求的URL可以通過 替換塊 和 請求方法的引數 來進行動態的URL更新。
// 替換塊是由 被{}包裹起來的字串構成
// 即:Retrofit支援動態改變網路請求根目錄
複製程式碼
- 網路請求的完整 Url =在建立Retrofit例項時通過.baseUrl()設定 +網路請求介面的註解設定(下面稱 “path“ )
- 具體整合的規則如下:
建議採用第三種方式來配置,並儘量使用同一種路徑形式。
b. @HTTP
- 作用:替換@GET、@POST、@PUT、@DELETE、@HEAD註解的作用 及 更多功能擴充
- 具體使用:通過屬性method、path、hasBody進行設定
public interface GetRequest_Interface { /** * method:網路請求的方法(區分大小寫) * path:網路請求地址路徑 * hasBody:是否有請求體 */ @HTTP(method = "GET", path = "blog/{id}", hasBody = false) Call<ResponseBody> getCall(@Path("id") int id); // {id} 表示是一個變數 // method 的值 retrofit 不會做處理,所以要自行保證準確 } 複製程式碼
第二類:標記
a. @FormUrlEncoded
- 作用:表示傳送form-encoded的資料(每個鍵值對需要用@Filed來註解鍵名,隨後的物件需要提供值。)
- 作用:表示傳送form-encoded的資料(適用於 有檔案 上傳的場景)
每個鍵值對需要用@Part來註解鍵名,隨後的物件需要提供值。 具體使用如下: GetRequest_Interface public interface GetRequest_Interface { /** *表明是一個表單格式的請求(Content-Type:application/x-www-form-urlencoded) * <code>Field("username")</code> 表示將後面的 <code>String name</code> 中name的取值作為 username 的值 */ @POST("/form") @FormUrlEncoded Call<ResponseBody> testFormUrlEncoded1(@Field("username") String name, @Field("age") int age); /** * {@link Part} 後面支援三種型別,{@link RequestBody}、{@link okhttp3.MultipartBody.Part} 、任意型別 * 除 {@link okhttp3.MultipartBody.Part} 以外,其它型別都必須帶上表單欄位({@link okhttp3.MultipartBody.Part} 中已經包含了表單欄位的資訊), */ @POST("/form") @Multipart Call<ResponseBody> testFileUpload1(@Part("name") RequestBody name, @Part("age") RequestBody age, @Part MultipartBody.Part file); } // 具體使用 GetRequest_Interface service = retrofit.create(GetRequest_Interface.class); // @FormUrlEncoded Call<ResponseBody> call1 = service.testFormUrlEncoded1("Carson", 24); // @Multipart RequestBody name = RequestBody.create(textType, "Carson"); RequestBody age = RequestBody.create(textType, "24"); MultipartBody.Part filePart = MultipartBody.Part.createFormData("file", "test.txt", file); Call<ResponseBody> call3 = service.testFileUpload1(name, age, filePart); 複製程式碼
第三類:網路請求引數
詳細說明
a. @Header & @Headers
- 作用:新增請求頭 &新增不固定的請求頭
- 具體使用如下:
// @Header
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
// @Headers
@Headers("Authorization: authorization")
@GET("user")
Call<User> getUser()
// 以上的效果是一致的。
// 區別在於使用場景和使用方式
// 1. 使用場景:@Header用於新增不固定的請求頭,@Headers用於新增固定的請求頭
// 2. 使用方式:@Header作用於方法的引數;@Headers作用於方法複製程式碼
b. @Body
- 作用:以
Post
方式 傳遞 自定義資料型別 給伺服器 - 特別注意:如果提交的是一個Map,那麼作用相當於
@Field
不過Map要經過 FormBody.Builder 類處理成為符合 Okhttp 格式的表單,如:
FormBody.Builder builder = new FormBody.Builder();
builder.add("key","value");複製程式碼
c. @Field & @FieldMap
- 作用:傳送 Post請求 時提交請求的表單欄位
- 具體使用:與
@FormUrlEncoded
註解配合使用
public interface GetRequest_Interface {
/**
*表明是一個表單格式的請求(Content-Type:application/x-www-form-urlencoded)
* <code>Field("username")</code> 表示將後面的 <code>String name</code> 中name的取值作為 username 的值
*/
@POST("/form")
@FormUrlEncoded
Call<ResponseBody> testFormUrlEncoded1(@Field("username") String name, @Field("age") int age);
/**
* Map的key作為表單的鍵
*/
@POST("/form")
@FormUrlEncoded
Call<ResponseBody> testFormUrlEncoded2(@FieldMap Map<String, Object> map);
}
// 具體使用
// @Field
Call<ResponseBody> call1 = service.testFormUrlEncoded1("Carson", 24);
// @FieldMap
// 實現的效果與上面相同,但要傳入Map
Map<String, Object> map = new HashMap<>();
map.put("username", "Carson");
map.put("age", 24);
Call<ResponseBody> call2 = service.testFormUrlEncoded2(map);
複製程式碼
d. @Part & @PartMap
作用:傳送 Post請求 時提交請求的表單欄位
與@Field的區別:功能相同,但攜帶的引數型別更加豐富,包括資料流,所以適用於 有檔案上傳 的場景 複製程式碼
- 具體使用:與
@Multipart
註解配合使用
public interface GetRequest_Interface {
/**
* {@link Part} 後面支援三種型別,{@link RequestBody}、{@link okhttp3.MultipartBody.Part} 、任意型別
* 除 {@link okhttp3.MultipartBody.Part} 以外,其它型別都必須帶上表單欄位({@link okhttp3.MultipartBody.Part} 中已經包含了表單欄位的資訊),
*/
@POST("/form")
@Multipart
Call<ResponseBody> testFileUpload1(@Part("name") RequestBody name, @Part("age") RequestBody age, @Part MultipartBody.Part file);
/**
* PartMap 註解支援一個Map作為引數,支援 {@link RequestBody } 型別,
* 如果有其它的型別,會被{@link retrofit2.Converter}轉換,如後面會介紹的 使用{@link com.google.gson.Gson} 的 {@link retrofit2.converter.gson.GsonRequestBodyConverter}
* 所以{@link MultipartBody.Part} 就不適用了,所以檔案只能用<b> @Part MultipartBody.Part </b>
*/
@POST("/form")
@Multipart
Call<ResponseBody> testFileUpload2(@PartMap Map<String, RequestBody> args, @Part MultipartBody.Part file);
@POST("/form")
@Multipart
Call<ResponseBody> testFileUpload3(@PartMap Map<String, RequestBody> args);
}
// 具體使用
MediaType textType = MediaType.parse("text/plain");
RequestBody name = RequestBody.create(textType, "Carson");
RequestBody age = RequestBody.create(textType, "24");
RequestBody file = RequestBody.create(MediaType.parse("application/octet-stream"), "這裡是模擬檔案的內容");
// @Part
MultipartBody.Part filePart = MultipartBody.Part.createFormData("file", "test.txt", file);
Call<ResponseBody> call3 = service.testFileUpload1(name, age, filePart);
ResponseBodyPrinter.printResponseBody(call3);
// @PartMap
// 實現和上面同樣的效果
Map<String, RequestBody> fileUpload2Args = new HashMap<>();
fileUpload2Args.put("name", name);
fileUpload2Args.put("age", age);
//這裡並不會被當成檔案,因為沒有檔名(包含在Content-Disposition請求頭中),但上面的 filePart 有
//fileUpload2Args.put("file", file);
Call<ResponseBody> call4 = service.testFileUpload2(fileUpload2Args, filePart); //單獨處理檔案
ResponseBodyPrinter.printResponseBody(call4);
}
複製程式碼
e. @Query和@QueryMap
作用:用於
@GET
方法的查詢引數(Query = Url 中 ‘?’ 後面的 key-value)
如:url = http://www.println.net/?cate=android,其中,Query = cate
複製程式碼
具體使用:配置時只需要在介面方法中增加一個引數即可:
@GET("/")
Call<String> cate(@Query("cate") String cate);
}
// 其使用方式同 @Field與@FieldMap,這裡不作過多描述
複製程式碼
f. @Path
- 作用:URL地址的預設值
- 具體使用:
public interface GetRequest_Interface { @GET("users/{user}/repos") Call<ResponseBody> getBlog(@Path("user") String user ); // 訪問的API是:https://api.github.com/users/{user}/repos // 在發起請求時, {user} 會被替換為方法的第一個引數 user(被@Path註解作用) } 複製程式碼
g. @Url
- 作用:直接傳入一個請求的 URL變數 用於URL設定
- 具體使用:
public interface GetRequest_Interface { @GET Call<ResponseBody> testUrlAndQuery(@Url String url, @Query("showAll") boolean showAll); // 當有URL註解時,@GET傳入的URL就可以省略 // 當GET、POST...HTTP等方法中沒有設定Url時,則必須使用 {@link Url}提供} 複製程式碼
彙總
4:建立 Retrofit 例項
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("http://fanyi.youdao.com/") // 設定網路請求的Url地址
.addConverterFactory(GsonConverterFactory.create()) // 設定資料解析器
.addCallAdapterFactory(RxJavaCallAdapterFactory.create()) // 支援RxJava平臺
.build();
複製程式碼
a. 關於資料解析器(Converter)
- Retrofit支援多種資料解析方式
- 使用時需要在Gradle新增依賴
- 資料解析器 Gradle依賴
- Gson com.squareup.retrofit2:converter-gson:2.0.2
- Jackson com.squareup.retrofit2:converter-jackson:2.0.2
- Simple XML com.squareup.retrofit2:converter-simplexml:2.0.2
- Protobuf com.squareup.retrofit2:converter-protobuf:2.0.2
- Moshi com.squareup.retrofit2:converter-moshi:2.0.2
- Wire com.squareup.retrofit2:converter-wire:2.0.2
- Scalars com.squareup.retrofit2:converter-scalars:2.0.2
b. 關於網路請求介面卡(CallAdapter)
Retrofit支援多種網路請求介面卡方式:guava、Java8和rxjava
使用時如使用的是 Android 預設的 CallAdapter,則不需要新增網路請求介面卡的依賴,否則則需要按照需求進行新增
Retrofit 提供的 CallAdapter
複製程式碼
- 使用時需要在Gradle新增依賴:
- guava com.squareup.retrofit2:adapter-guava:2.0.2
- Java8 com.squareup.retrofit2:adapter-java8:2.0.2
- rxjava com.squareup.retrofit2:adapter-rxjava:2.0.2
5:建立 網路請求介面例項
// 建立 網路請求介面 的例項
GetRequest_Interface request = retrofit.create(GetRequest_Interface.class);
//對 傳送請求 進行封裝
Call<Reception> call = request.getCall();
複製程式碼
6:傳送網路請求(非同步 / 同步)
/傳送網路請求(非同步)
call.enqueue(new Callback<Translation>() {
//請求成功時回撥
@Override
public void onResponse(Call<Translation> call, Response<Translation> response) {
//請求處理,輸出結果
response.body().show();
}
//請求失敗時候的回撥
@Override
public void onFailure(Call<Translation> call, Throwable throwable) {
System.out.println("連線失敗");
}
});
// 傳送網路請求(同步)
Response<Reception> response = call.execute();
複製程式碼
7:處理返回資料
通過response
類的 body()
對返回的資料進行處理
//傳送網路請求(非同步)
call.enqueue(new Callback<Translation>() {
//請求成功時回撥
@Override
public void onResponse(Call<Translation> call, Response<Translation> response) {
// 對返回資料進行處理
response.body().show();
}
//請求失敗時候的回撥
@Override
public void onFailure(Call<Translation> call, Throwable throwable) {
System.out.println("連線失敗");
}
});
// 傳送網路請求(同步)
Response<Reception> response = call.execute();
// 對返回資料進行處理
response.body().show();
複製程式碼