Retrofit用法詳解
一、簡介
Retrofit是Square公司開發的一款針對Android網絡請求的框架,Retrofit2底層基於OkHttp實現的,OkHttp現在已經得到Google官方認可,大量的app都采用OkHttp做網絡請求,其源碼詳見OkHttp Github。
本文全部是在Retrofit2.0+版本基礎上論述,所用例子全部來自豆瓣Api
首先先來看一個完整Get請求是如何實現:
-
創建業務請求接口,具體代碼如下:
1
2
3
4
5
6public interface BlueService {
@GET("book/search")
Call<BookSearchResponse> getSearchBooks(@Query("q") String name,
@Query("tag") String tag, @Query("start") int start,
@Query("count") int count);
}這里需要稍作說明,@GET注解就表示get請求,@Query表示請求參數,將會以key=value的方式拼接在url后面
-
需要創建一個Retrofit的示例,並完成相應的配置
1
2
3
4
5
6Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.douban.com/v2/")
.addConverterFactory(GsonConverterFactory.create())
.build();
BlueService service = retrofit.create(BlueService.class);這里的baseUrl就是網絡請求URL相對固定的地址,一般包括請求協議(如Http)、域名或IP地址、端口號等,當然還會有很多其他的配置,下文會詳細介紹。還有addConverterFactory方法表示需要用什么轉換器來解析返回值,GsonConverterFactory.create()表示調用Gson庫來解析json返回值,具體的下文還會做詳細介紹。
-
調用請求方法,並得到Call實例
1
Call<BookSearchResponse> call = 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實例完成同步或異步請求
-
同步請求
1
BookSearchResponse response = call.execute().body();
這里需要注意的是網絡請求一定要在子線程中完成,不能直接在UI線程執行,不然會crash
-
異步請求
1
2
3
4
5
6
7
8
9
10call.enqueue(new Callback<BookSearchResponse>() {
@Override
public void onResponse(Call<BookSearchResponse> call, Response<BookSearchResponse> response) {
asyncText.setText("異步請求結果: " + 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' |
引入完第三包接下來就可以使用Retrofit來進行網絡請求了。接下來會對不同的請求方式做進一步的說明。
Get方法
1. @Query
Get方法請求參數都會以key=value的方式拼接在url后面,Retrofit提供了兩種方式設置請求參數。第一種就是像上文提到的直接在interface中添加@Query注解,還有一種方式是通過Interceptor實現,直接看如何通過Interceptor實現請求參數的添加。
1 |
public class CustomInterceptor implements Interceptor { |
addQueryParameter就是添加請求參數的具體代碼,這種方式比較適用於所有的請求都需要添加的參數,一般現在的網絡請求都會添加token作為用戶標識,那么這種方式就比較適合。
創建完成自定義的Interceptor后,還需要在Retrofit創建client處完成添加
1 |
addInterceptor(new CustomInterceptor()) |
2. @QueryMap
如果Query參數比較多,那么可以通過@QueryMap方式將所有的參數集成在一個Map統一傳遞,還以上文中的get請求方法為例
1 |
public interface BlueService { |
調用的時候將所有的參數集合在統一的map中即可
1 |
Map<String, String> options = new HashMap<>(); |
3. Query集合
假如你需要添加相同Key值,但是value卻有多個的情況,一種方式是添加多個@Query參數,還有一種簡便的方式是將所有的value放置在列表中,然后在同一個@Query下完成添加,實例代碼如下:
1 |
public interface BlueService { |
最后得到的url地址為
1 |
https://api.douban.com/v2/book/search?q=leadership&q=beyond%20feelings |
4. Query非必填
如果請求參數為非必填,也就是說即使不傳該參數,服務端也可以正常解析,那么如何實現呢?其實也很簡單,請求方法定義處還是需要完整的Query注解,某次請求如果不需要傳該參數的話,只需填充null即可。
針對文章開頭提到的get的請求,加入按以下方式調用
1 |
Call<BookSearchResponse> call = mBlueService.getSearchBooks("小王子", null, 0, 3); |
那么得到的url地址為
1 |
https://api.douban.com/v2/book/search?q=%E5%B0%8F%E7%8E%8B%E5%AD%90&start=0&count=3 |
5. @Path
如果請求的相對地址也是需要調用方傳遞,那么可以使用@Path注解,示例代碼如下:
1 |
@GET("book/{id}") |
業務方想要在地址后面拼接書籍id,那么通過Path注解可以在具體的調用場景中動態傳遞,具體的調用方式如下:
1 |
Call<BookResponse> call = mBlueService.getBook("1003078"); |
此時的url地址為
1 |
https://api.douban.com/v2/book/1003078 |
@Path可以用於任何請求方式,包括Post,Put,Delete等等
Post請求
1. @field
Post請求需要把請求參數放置在請求體中,而非拼接在url后面,先來看一個簡單的例子
1 |
@FormUrlEncoded |
這里有幾點需要說明的
-
@FormUrlEncoded將會自動將請求參數的類型調整為application/x-www-form-urlencoded,假如content傳遞的參數為Good Luck,那么最后得到的請求體就是
1
content=Good+Luck
FormUrlEncoded不能用於Get請求
-
@Field注解將每一個請求參數都存放至請求體中,還可以添加encoded參數,該參數為boolean型,具體的用法為
1
@Field(value = "book", encoded = true) String book
encoded參數為true的話,key-value-pair將會被編碼,即將中文和特殊字符進行編碼轉換
2. @FieldMap
上述Post請求有4個請求參數,假如說有更多的請求參數,那么通過一個一個的參數傳遞就顯得很麻煩而且容易出錯,這個時候就可以用FieldMap
1 |
@FormUrlEncoded |
3. @Body
如果Post請求參數有多個,那么統一封裝到類中應該會更好,這樣維護起來會非常方便
1 |
@FormUrlEncoded |
其他請求方式
除了Get和Post請求,Http請求還包括Put,Delete等等,用法和Post相似,所以就不再單獨介紹了。
上傳
上傳因為需要用到Multipart,所以需要單獨拿出來介紹,先看一個具體上傳的例子
首先還是需要新建一個interface用於定義上傳方法
1 |
public interface FileUploadService { |
接下來我們還需要在Activity和Fragment中實現兩個工具方法,代碼如下:
1 |
public static final String MULTIPART_FORM_DATA = "multipart/form-data"; |
好了,接下來就是最終的上傳文件代碼了
1 |
Uri file1Uri = ... // 從文件選擇器或者攝像頭中獲取 |
三、其他必須知道的事項
1. 添加自定義的header
Retrofit提供了兩個方式定義Http請求頭參數:靜態方法和動態方法,靜態方法不能隨不同的請求進行變化,頭部信息在初始化的時候就固定了。而動態方法則必須為每個請求都要單獨設置。
-
靜態方法
1
2
3
4
5
6
7public interface BlueService {
@Headers("Cache-Control: max-age=640000")
@GET("book/search")
Call<BookSearchResponse> getSearchBooks(@Query("q") String name,
@Query("tag") String tag, @Query("start") int start,
@Query("count") int count);
}當然你想添加多個header參數也是可以的,寫法也很簡單
1
2
3
4
5
6
7
8
9
10public interface BlueService {
@Headers({
"Accept: application/vnd.yourapi.v1.full+json",
"User-Agent: Your-App-Name"
})
@GET("book/search")
Call<BookSearchResponse> getSearchBooks(@Query("q") String name,
@Query("tag") String tag, @Query("start") int start,
@Query("count") int count);
}此外也可以通過Interceptor來定義靜態請求頭
1
2
3
4
5
6
7
8
9
10
11
12public 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參數Request提供了兩個方法,一個是header(key, value),另一個是.addHeader(key, value),兩者的區別是,header()如果有重名的將會覆蓋,而addHeader()允許相同key值的header存在
然后在OkHttp創建Client實例時,添加RequestInterceptor即可
1
2
3
4
5
6private static OkHttpClient getNewClient(){
return new OkHttpClient.Builder()
.addInterceptor(new RequestInterceptor())
.connectTimeout(DEFAULT_TIMEOUT, TimeUnit.SECONDS)
.build();
} -
動態方法
1
2
3
4
5
6
7public interface BlueService {
@GET("book/search")
Call<BookSearchResponse> getSearchBooks(
@Header("Content-Range") String contentRange,
@Query("q") String name, @Query("tag") String tag,
@Query("start") int start, @Query("count") int count);
}
2. 網絡請求日志
調試網絡請求的時候經常需要關注一下請求參數和返回值,以便判斷和定位問題出在哪里,Retrofit官方提供了一個很方便查看日志的Interceptor,你可以控制你需要的打印信息類型,使用方法也很簡單。
首先需要在build.gradle文件中引入logging-interceptor
1 |
compile 'com.squareup.okhttp3:logging-interceptor:3.4.1' |
同上文提到的CustomInterceptor和RequestInterceptor一樣,添加到OkHttpClient創建處即可,完整的示例代碼如下:
1 |
private static OkHttpClient getNewClient(){ |
HttpLoggingInterceptor提供了4中控制打印信息類型的等級,分別是NONE,BASIC,HEADERS,BODY,接下來分別來說一下相應的打印信息類型。
-
NONE
沒有任何日志信息
-
Basic
打印請求類型,URL,請求體大小,返回值狀態以及返回值的大小
1
2D/HttpLoggingInterceptor$Logger: --> POST /upload HTTP/1.1 (277-byte body)
D/HttpLoggingInterceptor$Logger: <-- HTTP/1.1 200 OK (543ms, -1-byte body) -
Headers
打印返回請求和返回值的頭部信息,請求類型,URL以及返回值狀態碼
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16<-- 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信息
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28<-- 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)
3. 為某個請求設置完整的URL
假如說你的某一個請求不是以base_url開頭該怎么辦呢?別着急,辦法很簡單,看下面這個例子你就懂了
1 |
public interface BlueService { |
直接用@Url注解的方式傳遞完整的url地址即可。
4. 取消請求
Call提供了cancel方法可以取消請求,前提是該請求還沒有執行
1 |
String fileUrl = "http://futurestud.io/test.mp4"; |
四、結語
關於Retrofit常用的方法基本上已經介紹完了,有些請求由於工作保密性的原因,所以就沒有放出來,但是基本的方法和操作都是有的,仿照文中提到的代碼就可以實現你想要的功能。參考了國外的一則系列教程和liangfei的一篇文章圖解 Retrofit - ServiceMethod,由於本人能力有限,有錯誤或者表述不准確的地方還望多多留言指正。