是Square公司開發(fā)的一款針對Android網(wǎng)絡(luò)請求的框架点楼,Retrofit2底層基于OkHttp實現(xiàn)的,現(xiàn)在已經(jīng)得到Google官方認(rèn)可悴品,大量的app都采用OkHttp做網(wǎng)絡(luò)請求禀综,其源碼詳見[OkHttp Github]。
一他匪、首先先來看一個完整Get請求是如何實現(xiàn):
1菇存、創(chuàng)建業(yè)務(wù)請求接口,具體代碼如下:
public interface ApiService {
@GET("book/search")
Call<BookSearch> getSearchBooks(@Query("name") String name);
}
** 這里需要稍作說明邦蜜,@GET注解就表示get請求依鸥,@Query表示請求參數(shù),將會以key=value的方式拼接在url后面
2悼沈、需要創(chuàng)建一個Retrofit的示例贱迟,并完成相應(yīng)的配置
Retrofit retrofit = new Retrofit.Builder()
.baseUrl(UrisServerDefine.API_BASE_URL)
.addConverterFactory(GsonConverterFactory.create())
.build();
ApiService service = retrofit.create(ApiService.class);
**這里的baseUrl就是網(wǎng)絡(luò)請求URL相對固定的地址,一般包括請求協(xié)議(如Http)絮供、域名或IP地址衣吠、端口號等,當(dāng)然還會有很多其他的配置壤靶,下文會詳細(xì)介紹缚俏。還有addConverterFactory方法表示需要用什么轉(zhuǎn)換器來解析返回值,GsonConverterFactory.create()表示調(diào)用Gson庫來解析json返回值贮乳,具體的下文還會做詳細(xì)介紹忧换。
3、調(diào)用請求方法向拆,并得到Call實例
Call<BookSearch> call = service.getSearchBooks("小王子");
4亚茬、使用Call實例完成同步或異步請求
1、同步請求
BookSearch response = call.execute().body();
**這里需要注意的是網(wǎng)絡(luò)請求一定要在子線程中完成浓恳,不能直接在UI線程執(zhí)行刹缝,不然會crash
2碗暗、異步請求
call.enqueue(new Callback<BookSearch>() {
@Override
public void onResponse(Call<BookSearch> call,Response<BookSearch> response) {
asyncText.setText("異步請求結(jié)果: " + response.body().books.get(0).altTitle);
}
@Override
public void onFailure(Call<BookSearchResponse> call, Throwable t){
}
});
二、如何使用
首先需要在build.gradle文件中引入需要的第三包梢夯,配置如下:
1 compile 'com.squareup.retrofit2:retrofit:2.1.0'
2 compile 'com.squareup.retrofit2:converter-gson:2.1.0'
3 compile 'com.squareup.retrofit2:adapter-rxjava:2.1.0'
**引入完第三包接下來就可以使用Retrofit來進(jìn)行網(wǎng)絡(luò)請求了言疗。接下來會對不同的請求方式做進(jìn)一步的說明。
Get 方法
- @Query
Get方法請求參數(shù)都會以key=value的方式拼接在url后面厨疙,Retrofit提供了兩種方式設(shè)置請求參數(shù)洲守。第一種就是像上文提到的直接在interface中添加@Query注解疑务,還有一種方式是通過Interceptor實現(xiàn)沾凄,直接看如何通過Interceptor實現(xiàn)請求參數(shù)的添加。
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就是添加請求參數(shù)的具體代碼知允,這種方式比較適用于所有的請求都需要添加的參數(shù)撒蟀,一般現(xiàn)在的網(wǎng)絡(luò)請求都會添加token作為用戶標(biāo)識,那么這種方式就比較適合温鸽。
創(chuàng)建完成自定義的Interceptor后保屯,還需要在Retrofit創(chuàng)建client處完成添加。
1 addInterceptor(new CustomInterceptor())
-
@QueryMap
如果Query參數(shù)比較多涤垫,那么可以通過@QueryMap方式將所有的參數(shù)集成在一個Map統(tǒng)一傳遞姑尺,還以上文中的get請求方法為例public interface ApiService { @GET("book/search") Call<BookSearchResponse> getSearchBooks(@QueryMap Map<String, String> options); }
調(diào)用的時候?qū)⑺械膮?shù)集合在統(tǒng)一的map中即可
Map<String, String> options = new HashMap<>(); map.put("name", "小王子"); Call<BookSearch> call = service.getSearchBooks(options);
調(diào)用的時候?qū)⑺械膮?shù)集合在統(tǒng)一的map中即可
Map<String, String> options = new HashMap<>(); map.put("name", "小王子"); Call<BookSearch> call = service.getSearchBooks(options);
-
Query集合
假如你需要添加相同Key值,但是value卻有多個的情況蝠猬,一種方式是
添加多個@Query參數(shù)切蟋,還有一種簡便的方式是將所有的value放置在
列表中,然后在同一個@Query下完成添加榆芦,實例代碼如下:public interface ApiService { @GET("book/search") Call<BookSearch> getSearchBooks(@Query("name") List<String> name); }
-
Query非必填
如果請求參數(shù)為非必填柄粹,也就是說即使不傳該參數(shù),服務(wù)端也可以正 常解析匆绣,那么如何實現(xiàn)呢驻右?其實也很簡單,請求方法定義處還是需要完整的Query注解崎淳,某次請求如果不需要傳該參數(shù)的話堪夭,只需填充null即可。針對文章開頭提到的get的請求拣凹,加入按以下方式調(diào)用Call<BookSearch> call = service.getSearchBooks("小王子");
-
@Path
如果請求的相對地址也是需要調(diào)用方傳遞森爽,那么可以使用@Path注解,示例代碼如下:@GET("book/{id}") Call<BookResponse> getBook(@Path("id") String id);
業(yè)務(wù)方想要在地址后面拼接書籍id咐鹤,那么通過Path注解可以在具體的調(diào)用場景中動態(tài)傳遞拗秘,具體的調(diào)用方式如下:
Call<BookResponse> call =service.getBook("1003078");
@Path可以用于任何請求方式,包括Post祈惶,Put雕旨,Delete等等
Post請求
-
@field
Post請求需要把請求參數(shù)放置在請求體中扮匠,而非拼接在url后面,先來看一個簡單的例子@FormUrlEncoded @POST("book/reviews") Call<String> addReviews(@Field("book") String bookId, @Field("title") String title, @Field("content") String content, @Field("rating") String rating);
這里有幾點(diǎn)需要說明的
@FormUrlEncoded將會自動將請求參數(shù)的類型調(diào)整為application/x-www-form-urlencoded凡涩,假如content傳遞的參數(shù)為Good Luck棒搜,那么最后得到的請求體就是 content=Good+LuckFormUrlEncoded不能用于Get請求
@Field注解將每一個請求參數(shù)都存放至請求體中,還可以添加encoded參數(shù)活箕,該參數(shù)為boolean型力麸,具體的用法為
@Field(value = "book", encoded = true) String book
encoded參數(shù)為true的話,key-value-pair將會被編碼育韩,即將中文和特殊字符進(jìn)行編碼轉(zhuǎn)換
-
@FieldMap
上述Post請求有4個請求參數(shù)克蚂,假如說有更多的請求參數(shù),那么通過一個一個的參數(shù)傳遞就顯得很麻煩而且容易出錯筋讨,這個時候就可以用FieldMap@FormUrlEncoded @POST("book/reviews") Call<String> addReviews(@FieldMap Map<String, String> fields);
-
@Body
如果Post請求參數(shù)有多個埃叭,那么統(tǒng)一封裝到類中應(yīng)該會更好,這樣維護(hù)起來會非常方便@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相似,所以就不再單獨(dú)介紹了壁袄。上傳
上傳因為需要用到Multipart类早,所以需要單獨(dú)拿出來介紹,先看一個具體上傳的例子首先還是需要新建一個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中實現(xiàn)兩個工具方法嗜逻,代碼如下: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 = ... // 創(chuàng)建上傳的service實例 FileUploadService service = ServiceGenerator.createService(FileUploadService.class); // 創(chuàng)建文件的part (photo, video, ...) MultipartBody.Part body1 = prepareFilePart("video", file1Uri); MultipartBody.Part body2 = prepareFilePart("thumbnail", file2Uri); // 添加其他的part RequestBody description = createPartFromString("hello, this is description speaking"); // 最后執(zhí)行異步請求操作 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()); } });
三、其他必須知道的事項
-
添加自定義的header
Retrofit提供了兩個方式定義Http請求頭參數(shù):靜態(tài)方法和動態(tài)方法变泄,靜態(tài)方法不能隨不同的請求進(jìn)行變化令哟,頭部信息在初始化的時候就固定了。而動態(tài)方法則必須為每個請求都要單獨(dú)設(shè)置妨蛹。靜態(tài)方法
public interface ApiService { @Headers("Cache-Control: max-age=640000") @GET("book/search") Call<BookSearch> getSearchBooks(@Query("name") String name); }
當(dāng)然你想添加多個header參數(shù)也是可以的屏富,寫法也很簡單
public interface ApiService { @Headers("Accept: application/vnd.yourapi.v1.full+json", "User-Agent: Your-App-Name }) @GET("book/search") Call<BookSearch> getSearchBooks(@Query("name") String name); }
此外也可以通過Interceptor來定義靜態(tài)請求頭
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); } }
添加header參數(shù)Request提供了兩個方法,一個是header(key, value)蛙卤,另一個是.addHeader(key, value)狠半,兩者的區(qū)別是,header()如果有重名的將會覆蓋颤难,而addHeader()允許相同key值的header存在然后在OkHttp創(chuàng)建Client實例時神年,添加RequestInterceptor即可
private static OkHttpClient getNewClient(){ return new OkHttpClient.Builder() .addInterceptor(new RequestInterceptor()) .connectTimeout(DEFAULT_TIMEOUT, TimeUnit.SECONDS) .build(); }
動態(tài)方法
public interface ApiService { @GET("book/search") Call<BookSearch> getSearchBooks( @Header("Content-Range") String contentRange, @Query("name") String name); }
-
網(wǎng)絡(luò)請求日志
調(diào)試網(wǎng)絡(luò)請求的時候經(jīng)常需要關(guān)注一下請求參數(shù)和返回值,以便判斷和定位問題出在哪里行嗤,Retrofit官方提供了一個很方便查看日志的Interceptor已日,你可以控制你需要的打印信息類型,使用方法也很簡單栅屏。
首先需要在build.gradle文件中引入logging-interceptorcompile 'com.squareup.okhttp3:logging-interceptor:3.4.1'
同上文提到的CustomInterceptor和RequestInterceptor一樣飘千,添加到OkHttpClient創(chuàng)建處即可堂鲜,完整的示例代碼如下:
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霉旗,接下來分別來說一下相應(yīng)的打印信息類型痴奏。
NONE
沒有任何日志信息
Basic
打印請求類型,URL厌秒,請求體大小读拆,返回值狀態(tài)以及返回值的大小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以及返回值狀態(tài)碼<-- 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)
-
為某個請求設(shè)置完整的URL
假如說你的某一個請求不是以base_url開頭該怎么辦呢?別著急屠列,辦法很簡單啦逆,看下面這個例子你就懂了public interface ApiService { @GET public Call<ResponseBody> profilePicture(@Url String url); } Retrofit retrofit = Retrofit.Builder() .baseUrl("https://your.api.url/"); .build(); ApiService service = retrofit.create(ApiService.class); service.profilePicture("https://s3.amazon.com/profile-picture/path")
直接用@Url注解的方式傳遞完整的url地址即可。
4. 取消請求
Call提供了cancel方法可以取消請求笛洛,前提是該請求還沒有執(zhí)行String fileUrl = "http://futurestud.io/test.mp4"; Call<ResponseBody> call = downloadService.downloadFileWithDynamicUrlSync(fileUrl); call.enqueue(new Callback<ResponseBody>() { @Override public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) { Log.d(TAG, "request success"); } @Override public void onFailure(Call<ResponseBody> call, Throwable t) { if (call.isCanceled()) { Log.e(TAG, "request was cancelled"); } else { Log.e(TAG, "other larger issue, i.e. no network connection?"); } } }); } // 觸發(fā)某個動作夏志,例如用戶點(diǎn)擊了取消請求的按鈕 call.cancel(); }
-
-