Retrofit各個註解的含義及作用

阿新 • • 發佈：2018-12-14

寫在前面

本篇文章基於retrofit-2.1進行分析.

1. 各個註解的含義及使用

1.1 Body註解:

作用於方法的引數
使用該註解定義的引數不可為null
當你傳送一個post或put請求,但是又不想作為請求引數或表單的方式傳送請求時,使用該註解定義的引數可以直接傳入一個實體類,retrofit會通過convert把該實體序列化並將序列化後的結果直接作為請求體傳送出去.

示例:

  //實體
   class Repo {
    final String owner;
    final String name;

    Repo(String owner, String name) {
      this.owner = owner;
      this.name = name;
    }
  }

  //介面
  interface Service {
    @POST("/")
    Call<ResponseBody> sendNormal(@Body Repo repo);

1.2 DELETE註解:

用於傳送一個DELETE請求
DELETE註解一般必須新增相對路徑或絕對路徑或者全路徑,如果不想在DELETE註解後新增請求路徑,則可以在方法的第一個引數中用@Url註解新增請求路徑

1.3 Field註解:

作用於方法的引數
用於傳送一個表單請求
用String.valueOf()把引數值轉換為String,然後進行URL編碼,當引數值為null值時,會自動忽略,如果傳入的是一個List或array,則為每一個非空的item拼接一個鍵值對,每一個鍵值對中的鍵是相同的,值就是非空item的值,如: name=張三&name=李四&name=王五,另外,如果item的值有空格,在拼接時會自動忽略,例如某個item的值為:張三,則拼接後為name=張三.

示例:

//普通引數
   @FormUrlEncoded
@POST("/")
Call<ResponseBody> example(@Field("name") String name,@Field("occupation") String occupation);

   //固定或可變陣列
   @FormUrlEncoded
   @POST("/list")
   Call<ResponseBody> example(@Field("name") String... names);

1.4 FieldMap註解:

作用於方法的引數
用於傳送一個表單請求
map中每一項的鍵和值都不能為空,否則丟擲IllegalArgumentException異常

示例:

  @FormUrlEncoded
   @POST("/things")
   Call<ResponseBody> things(@FieldMap Map<String, String> fields);

1.5 FormUrlEncoded註解:

用於修飾Field註解和FieldMap註解
使用該註解,表示請求正文將使用表單網址編碼。欄位應該宣告為引數，並用@Field註釋或FieldMap註釋。使用FormUrlEncoded註解的請求將具”application / x-www-form-urlencoded” MIME型別。欄位名稱和值將先進行UTF-8進行編碼,再根據RFC-3986進行URI編碼.

1.6 GET註解

用於傳送一個get請求
GET註解一般必須新增相對路徑或絕對路徑或者全路徑,如果不想在GET註解後新增請求路徑,則可以在方法的第一個引數中用@Url註解新增請求路徑

1.7 HEAD註解

用於傳送一個HEAD請求
HEAD註解一般必須新增相對路徑或絕對路徑或者全路徑,如果不想在HEAD註解後新增請求路徑,則可以在方法的第一個引數中用@Url註解新增請求路徑

1.8 Header註解:

作用於方法的引數,用於新增請求頭
使用該註解定義的請求頭可以為空,當為空時,會自動忽略,當傳入一個List或array時,為拼接每個非空的item的值到請求頭中.
具有相同名稱的請求頭不會相互覆蓋,而是會照樣新增到請求頭中

示例:

  @GET("/")
   Call<ResponseBody> foo(@Header("Accept-Language") String lang);

1.9 HeaderMap註解:

作用於方法的引數,用於新增請求頭
以map的方式新增多個請求頭,map中的key為請求頭的名稱,value為請求頭的值,且value使用String.valueOf()統一轉換為String型別,
map中每一項的鍵和值都不能為空,否則丟擲IllegalArgumentException異常

示例:

   @GET("/search")
   void list(@HeaderMap Map<String, String> headers);

   //map
   Map<String,String> headers = new HashMap()<>;
   headers.put("Accept","text/plain");
   headers.put("Accept-Charset", "utf-8");

2.0 Headers註解:

作用於方法,用於新增一個或多個請求頭
具有相同名稱的請求頭不會相互覆蓋,而是會照樣新增到請求頭中

示例:

//新增一個請求頭
 @Headers("Cache-Control: max-age=640000")
 @GET("/")
 ...
//新增多個請求頭
@Headers({ "X-Foo: Bar",
           "X-Ping: Pong"
        })
   @GET("/")
   ...

2.1 HTTP註解:

作用於方法,用於傳送一個自定義的HTTP請求

示例:

//自定義HTTP請求的標準樣式
interface Service {
     @HTTP(method = "CUSTOM", path = "custom/endpoint/")
     Call<ResponseBody> customEndpoint();
   }
//傳送一個DELETE請求
interface Service {
     @HTTP(method = "DELETE", path = "remove/", hasBody = true)
     Call<ResponseBody> deleteObject(@Body RequestBody object);
   }

2.2 Multipart註解:

作用於方法
使用該註解,表示請求體是多部分的。每一部分作為一個引數,且用Part註解宣告

2.3 Part註解:

作用於方法的引數,用於定義Multipart請求的每個part
使用該註解定義的引數,引數值可以為空,為空時,則忽略
使用該註解定義的引數型別有以下3種方式可選:1, 如果型別是okhttp3.MultipartBody.Part，內容將被直接使用。省略part中的名稱,即 @Part MultipartBody.Part part2, 如果型別是RequestBody，那麼該值將直接與其內容型別一起使用。在註釋中提供part名稱（例如，@Part（“foo”）RequestBody foo）。3, 其他物件型別將通過使用轉換器轉換為適當的格式。在註釋中提供part名稱（例如，@Part（“foo”）Image photo）。

示例:

@Multipart
@POST("/")
Call<ResponseBody> example(
       @Part("description") String description,
       @Part(value = "image", encoding = "8-bit") RequestBody image);

2.4 PartMap註解:

作用於方法的引數,以map的方式定義Multipart請求的每個part
map中每一項的鍵和值都不能為空,否則丟擲IllegalArgumentException異常
使用該註解定義的引數型別有以下2種方式可選:1, 如果型別是RequestBody，那麼該值將直接與其內容型別一起使用。2, 其他物件型別將通過使用轉換器轉換為適當的格式。

示例:

@Multipart
@POST("/upload")
Call<ResponseBody> upload(
       @Part("file") RequestBody file,
       @PartMap Map<String, RequestBody> params);

2.5 OPTIONS註解:

用於傳送一個OPTIONS請求
OPTIONS註解一般必須新增相對路徑或絕對路徑或者全路徑,如果不想在OPTIONS註解後新增請求路徑,則可以在方法的第一個引數中用@Url註解新增請求路徑

2.6 PATCH註解:

用於傳送一個PATCH請求
PATCH註解一般必須新增相對路徑或絕對路徑或者全路徑,如果不想在PATCH註解後新增請求路徑,則可以在方法的第一個引數中用@Url註解新增請求路徑

2.7 Path註解:

作用於方法的引數
在URL路徑段中替換指定的引數值。使用String.valueOf()和URL編碼將值轉換為字串。
使用該註解定義的引數的值不可為空
引數值預設使用URL編碼

示例:

//標準使用方式,預設使用URL編碼
@GET("/image/{id}")
Call<ResponseBody> example(@Path("id") int id);
//預設使用URL編碼
@GET("/user/{name}")
Call<ResponseBody> encoded(@Path("name") String name);
//不使用URL編碼
@GET("/user/{name}")
Call<ResponseBody> notEncoded(@Path(value="name", encoded=true) String name);

2.8 POST註解:

用於傳送一個POST請求
POST註解一般必須新增相對路徑或絕對路徑或者全路徑,如果不想在POST註解後新增請求路徑,則可以在方法的第一個引數中用@Url註解新增請求路徑

2.9 PUT註解:

用於傳送一個PUT請求
PUT註解一般必須新增相對路徑或絕對路徑或者全路徑,如果不想在PUT註解後新增請求路徑,則可以在方法的第一個引數中用@Url註解新增請求路徑

3.0 Query註解:

作用於方法的引數
用於新增查詢引數,即請求引數
引數值通過String.valueOf()轉換為String並進行URL編碼
使用該註解定義的引數,引數值可以為空,為空時,忽略該值,當傳入一個List或array時,為每個非空item拼接請求鍵值對,所有的鍵是統一的,如: name=張三&name=李四&name=王五.

示例:

@GET("/list")
Call<ResponseBody> list(@Query("page") int page);
@GET("/list")
Call<ResponseBody> list(@Query("category") String category);
//傳入一個數組
@GET("/list")
Call<ResponseBody> list(@Query("category") String... categories);
//不進行URL編碼
@GET("/search")
Call<ResponseBody> list(@Query(value="foo", encoded=true) String foo);

3.1 QueryMap註解:

作用於方法的引數
以map的形式新增查詢引數,即請求引數
引數的鍵和值都通過String.valueOf()轉換為String格式
map的鍵和值預設進行URL編碼
map中每一項的鍵和值都不能為空,否則丟擲IllegalArgumentException異常

示例:

//使用預設URL編碼
@GET("/search")
Call<ResponseBody> list(@QueryMap Map<String, String> filters);
//不使用預設URL編碼
@GET("/search")
Call<ResponseBody> list(@QueryMap(encoded=true) Map<String, String> filters);

3.2 Streaming註解:

作用於方法
處理返回Response的方法的響應體，即沒有將body（）轉換為byte []。

3.3 Url註解:

作用於方法引數
用於新增請求的介面地址

示例:

@GET
Call<ResponseBody> list(@Url String url);

注意事項:

1,以上部分註解真正的實現在ParameterHandler類中,,每個註解的真正實現都是ParameterHandler類中的一個final型別的內部類,每個內部類都對各個註解的使用要求做了限制,比如引數是否可空,鍵和值是否可空等.

2,FormUrlEncoded註解和Multipart註解不能同時使用,否則會丟擲methodError(“Only one encoding annotation is allowed.”);可在ServiceMethod類中parseMethodAnnotation()方法中找到不能同時使用的具體原因.

3,Path註解與Url註解不能同時使用,否則會丟擲parameterError(p, “@Path parameters may not be used with @Url.”),可在ServiceMethod類中parseParameterAnnotation()方法中找到不能同時使用的具體程式碼.其實原因也很好理解: Path註解用於替換url路徑中的引數,這就要求在使用path註解時,必須已經存在請求路徑,不然沒法替換路徑中指定的引數啊,而Url註解是在引數中指定的請求路徑的,這個時候指定請求路徑已經晚了,path註解找不到請求路徑,更別提更換請求路徑中的引數了.

4,對於FiledMap,HeaderMap,PartMap,QueryMap這四種作用於方法的註解,其引數型別必須為Map的例項,且key的型別必須為String型別,否則丟擲異常(以PartMap註解為例):parameterError(p, “@PartMap keys must be of type String: ” + keyType);

5,使用Body註解的引數不能使用form 或multi-part編碼,即如果為方法使用了FormUrlEncoded或Multipart註解,則方法的引數中不能使用Body註解,否則丟擲異常parameterError(p, “@Body parameters cannot be used with form or multi-part encoding.”);

小結:

早就想把Retrofit的各個註解的含義和使用條件研究一番,但是幾個月來一直加班,根本沒多少時間仔細研讀,中間有點閒暇時間也想偷個懶休息一下,眼看著已經是2016年最後一天了,再不研究就要等明年了,所以下定決心,花了大半天的時間,把Retrofit 2.1版本的原始碼徹底的讀了一篇,邊讀變做筆記,讀完之後把這些筆記又做了一些整理,才有了這2016年最後一篇部落格.當然,文章中難免有錯誤或者不足之處,如果發現,還請及時告知,謝謝啦~~

讀完原始碼,發現Retrofit並不像理想中的那麼好,這裡說的不好不是說程式碼架構不好,而是單指易用性這個方面,所有會用Retrofit的朋友,都知道如何使用Retrofit傳送一個請求:

需要寫至少一個介面
然後定義至少一個介面方法
然後構建Retrofit
然後呼叫create方法生成介面類
然後呼叫enqueue或者 execute方法傳送一個非同步或同步請求

一個簡單的請求一共經歷了5步,這還不算完: - 你需要新增json解析器,如GsonConvertFactory,來自動序列化json串 - 你需要配置統一的cookie攔截器,這些程式碼需要你自己編寫(網上覆制貼上的除外) - 一般你還需要新增日誌攔截器,因為在debug的時候你會發現,Retrofit竟然他媽的不能拼接出完整的url請求地址(完整的請求地址包括請求的主機地址,介面名,所有請求引數拼接,Retrofit最多隻能看到介面,後面拼接的引數是看不到的,這在除錯的時候很讓人不爽)

如果你說這些都不是事,那麼我們再看:

Retrofit提供了MultiPart註解,說明我們可以上傳檔案,又提供了Streaming註解,說明我們可以下載檔案,我們知道Retrofit可以幹這些事,但是我們還是沒有辦法直接寫上傳下載程式碼,這些東西都需要我們自己去封裝,這也是為什麼目前有很多基於Retrofit構建的二次封裝庫的原因
很多人用Retrofit基本上也就會發送一個get或者post請求,也就熟悉個別幾個作用於引數的註解,如果你讓這些人用Retrofit去搞定所有RESTful風格的介面,可能大部分人直接懵逼,因為他們不知道各個方法的註解和引數的註解怎麼搭配使用才能完美執行,而不是丟擲異常,因為Retrofit制定的這些規則你必須遵守
有些狂熱的Retrofit粉絲大呼Retrofit有著插拔式設計,想用就用,想不用就不用,耦合很低,這確實是Retrofit的優點,但也正是因為足夠靈活,導致易用性不夠,不然也不會產生這麼多基於Retrofit構建的框架了