Retrofit各個注解的含義及作用

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

方法注解：@GET、@POST、@PUT、@DELETE、@PATH、@HEAD、@OPTIONS、@HTTP。
標記注解：@FormUrlEncoded、@Multipart、@Streaming。
參數(shù)注解：@Query，@QueryMap；@Body；@Field、@FieldMap；@Part，@PartMap。
其他注解：@Path；@Header,@Headers；@Url

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

1.1 Body注解:

  • 作用于方法的參數(shù)
  • 使用該注解定義的參數(shù)不可為null
  • 當你發(fā)送一個post或put請求,但是又不想作為請求參數(shù)或表單的方式發(fā)送請求時,使用該注解定義的參數(shù)可以直接傳入一個實體類,retrofit會通過convert把該實體序列化并將序列化后的結果直接作為請求體發(fā)送出去.

示例:

//實體 
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注解:

  • 用于發(fā)送一個DELETE請求
  • DELETE注解一般必須添加相對路徑或絕對路徑或者全路徑,如果不想在DELETE注解后添加請求路徑,則可以在方法的第一個參數(shù)中用@Url注解添加請求路徑

1.3 Field注解:

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

示例:

//普通參數(shù) 
@FormUrlEncoded
@POST("/")
Call<ResponseBody> example(@Field("name") String name,@Field("occupation") String occupation);
 //固定或可變數(shù)組
@FormUrlEncoded 
@POST("/list") 
Call<ResponseBody> example(@Field("name") String... names);

1.4 FieldMap注解:

  • 作用于方法的參數(shù)
  • 用于發(fā)送一個表單請求
  • map中每一項的鍵和值都不能為空,否則拋出IllegalArgumentException異常
    示例:
@FormUrlEncoded 
@POST("/things") 
Call<ResponseBody> things(@FieldMap Map<String, String> fields);

1.5 FormUrlEncoded注解:

  • 用于修飾Field注解和FieldMap注解
  • 使用該注解,表示請求正文將使用表單網(wǎng)址編碼。字段應該聲明為參數(shù)，并用@Field注釋或FieldMap注釋。
  • 使用FormUrlEncoded注解的請求將具”application / x-www-form-urlencoded” MIME類型。字段名稱和值將先進行UTF-8進行編碼,再根據(jù)RFC-3986進行URI編碼.

1.6 GET注解

  • 用于發(fā)送一個get請求
  • GET注解一般必須添加相對路徑或絕對路徑或者全路徑,如果不想在GET注解后添加請求路徑,則可以在方法的第一個參數(shù)中用@Url注解添加請求路徑

1.7 HEAD注解

  • 用于發(fā)送一個HEAD請求
  • HEAD注解一般必須添加相對路徑或絕對路徑或者全路徑,如果不想在HEAD注解后添加請求路徑,則可以在方法的第一個參數(shù)中用@Url注解添加請求路徑

1.8 Header注解:

  • 作用于方法的參數(shù),用于添加請求頭
  • 使用該注解定義的請求頭可以為空,當為空時,會自動忽略,當傳入一個List或array時,為拼接每個非空的item的值到請求頭中.
  • 具有相同名稱的請求頭不會相互覆蓋,而是會照樣添加到請求頭中

示例:

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

1.9 HeaderMap注解:

  • 作用于方法的參數(shù),用于添加請求頭
  • 以map的方式添加多個請求頭,map中的key為請求頭的名稱,value為請求頭的值,且value使用String.valueOf()統(tǒng)一轉換為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注解:

  • 作用于方法,用于發(fā)送一個自定義的HTTP請求

示例:

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

2.2 Multipart注解:

  • 作用于方法
  • 使用該注解,表示請求體是多部分的。 每一部分作為一個參數(shù),且用Part注解聲明

2.3 Part注解:

  • 作用于方法的參數(shù),用于定義Multipart請求的每個part
  • 使用該注解定義的參數(shù),參數(shù)值可以為空,為空時,則忽略
  • 使用該注解定義的參數(shù)類型有以下3種方式可選:
    1, 如果類型是okhttp3.MultipartBody.Part，內容將被直接使用。 省略part中的名稱,即 @Part MultipartBody.Part part
    2, 如果類型是RequestBody，那么該值將直接與其內容類型一起使用。 在注釋中提供part名稱（例如，@Part（“foo”）RequestBody foo）。
    3, 其他對象類型將通過使用轉換器轉換為適當?shù)母袷健?在注釋中提供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注解:

  • 作用于方法的參數(shù),以map的方式定義Multipart請求的每個part
  • map中每一項的鍵和值都不能為空,否則拋出IllegalArgumentException異常
  • 使用該注解定義的參數(shù)類型有以下2種方式可選:
    1, 如果類型是RequestBody，那么該值將直接與其內容類型一起使用。
    2, 其他對象類型將通過使用轉換器轉換為適當?shù)母袷健?/li>

示例:

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

2.5 OPTIONS注解:

  • 用于發(fā)送一個OPTIONS請求
  • OPTIONS注解一般必須添加相對路徑或絕對路徑或者全路徑,如果不想在OPTIONS注解后添加請求路徑,則可以在方法的第一個參數(shù)中用@Url注解添加請求路徑

2.6 PATCH注解:

  • 用于發(fā)送一個PATCH請求
  • PATCH注解一般必須添加相對路徑或絕對路徑或者全路徑,如果不想在PATCH注解后添加請求路徑,則可以在方法的第一個參數(shù)中用@Url注解添加請求路徑

2.7 Path注解:

  • 作用于方法的參數(shù)
  • 在URL路徑段中替換指定的參數(shù)值。使用String.valueOf()和URL編碼將值轉換為字符串。
  • 使用該注解定義的參數(shù)的值不可為空
  • 參數(shù)值默認使用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注解:

  • 用于發(fā)送一個POST請求
  • POST注解一般必須添加相對路徑或絕對路徑或者全路徑,如果不想在POST注解后添加請求路徑,則可以在方法的第一個參數(shù)中用@Url注解添加請求路徑

2.9 PUT注解:

  • 用于發(fā)送一個PUT請求
  • PUT注解一般必須添加相對路徑或絕對路徑或者全路徑,如果不想在PUT注解后添加請求路徑,則可以在方法的第一個參數(shù)中用@Url注解添加請求路徑

3.0 Query注解:

  • 作用于方法的參數(shù)
  • 用于添加查詢參數(shù),即請求參數(shù)
  • 參數(shù)值通過String.valueOf()轉換為String并進行URL編碼
  • 使用該注解定義的參數(shù),參數(shù)值可以為空,為空時,忽略該值,當傳入一個List或array時,為每個非空item拼接請求鍵值對,所有的鍵是統(tǒng)一的,如: name=張三&name=李四&name=王五.

示例:

@GET("/list")
Call<ResponseBody> list(@Query("page") int page);
@GET("/list")
Call<ResponseBody> list(@Query("category") String category);//傳入一個數(shù)組
@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注解:

  • 作用于方法的參數(shù)
  • 以map的形式添加查詢參數(shù),即請求參數(shù)
  • 參數(shù)的鍵和值都通過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注解:

  • 作用于方法參數(shù)
  • 用于添加請求的接口地址

示例:

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

注意事項:

1, 以上部分注解真正的實現(xiàn)在ParameterHandler類中,,每個注解的真正實現(xiàn)都是ParameterHandler類中的一個final類型的內部類,每個內部類都對各個注解的使用要求做了限制,比如參數(shù)是否可空,鍵和值是否可空等.
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路徑中的參數(shù),這就要求在使用path注解時,必須已經(jīng)存在請求路徑,不然沒法替換路徑中指定的參數(shù)啊,而Url注解是在參數(shù)中指定的請求路徑的,這個時候指定請求路徑已經(jīng)晚了,path注解找不到請求路徑,更別提更換請求路徑中的參數(shù)了.
4, 對于FiledMap,HeaderMap,PartMap,QueryMap這四種作用于方法的注解,其參數(shù)類型必須為Map的實例,且key的類型必須為String類型,否則拋出異常(以PartMap注解為例):parameterError(p, “@PartMap keys must be of type String: ” + keyType);
5, 使用Body注解的參數(shù)不能使用form 或multi-part編碼,即如果為方法使用了FormUrlEncoded或Multipart注解,則方法的參數(shù)中不能使用Body注解,否則拋出異常parameterError(p, “@Body parameters cannot be used with form or multi-part encoding.”);

小結:

發(fā)現(xiàn)Retrofit并不像理想中的那么好,這里說的不好不是說代碼架構不好,而是單指易用性這個方面,所有會用Retrofit的朋友,都知道如何使用Retrofit發(fā)送一個請求:

  • 需要寫至少一個接口
  • 然后定義至少一個接口方法
  • 然后構建Retrofit
  • 然后調用create方法生成接口類
  • 然后調用enqueue或者 execute方法發(fā)送一個異步或同步請求

一個簡單的請求一共經(jīng)歷了5步,這還不算完:

  • 你需要添加json解析器,如GsonConvertFactory,來自動序列化json串 - 你需要配置統(tǒng)一的cookie攔截器,這些代碼需要你自己編寫(網(wǎng)上復制粘貼的除外)
  • 一般你還需要添加日志攔截器,因為在debug的時候你會發(fā)現(xiàn),Retrofit竟然他媽的不能拼接出完整的url請求地址(完整的請求地址包括請求的主機地址,接口名,所有請求參數(shù)拼接,Retrofit最多只能看到接口,后面拼接的參數(shù)是看不到的,這在調試的時候很讓人不爽)

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

  • Retrofit提供了MultiPart注解,說明我們可以上傳文件,又提供了Streaming注解,說明我們可以下載文件,我們知道Retrofit可以干這些事,但是我們還是沒有辦法直接寫上傳下載代碼,這些東西都需要我們自己去封裝,這也是為什么目前有很多基于Retrofit構建的二次封裝庫的原因
  • 很多人用Retrofit基本上也就會發(fā)送一個get或者post請求,也就熟悉個別幾個作用于參數(shù)的注解,如果你讓這些人用Retrofit去搞定所有RESTful風格的接口,可能大部分人直接懵逼,因為他們不知道各個方法的注解和參數(shù)的注解怎么搭配使用才能完美運行,而不是拋出異常,因為Retrofit制定的這些規(guī)則你必須遵守
    有些狂熱的Retrofit粉絲大呼Retrofit有著插拔式設計,想用就用,想不用就不用,耦合很低,這確實是Retrofit的優(yōu)點,但也正是因為足夠靈活,導致易用性不夠,不然也不會產(chǎn)生這么多基于Retrofit構建的框架了

原文：http://blog.csdn.net/qiang_xi/article/details/53959437

最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發(fā)布，文章內容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務。

推薦閱讀更多精彩內容

  • 寫在前面 本篇文章基于retrofit-2.1進行分析. 1. 各個注解的含義及使用 1.1 Body注解: 作用...
    NeWolf閱讀 1,519評論 0贊 1
  • Spring Cloud為開發(fā)人員提供了快速構建分布式系統(tǒng)中一些常見模式的工具（例如配置管理，服務發(fā)現(xiàn)，斷路器，智...
    卡卡羅2017閱讀 134,993評論 19贊 139
  • 整體Retrofit內容如下： 1、Retrofit解析1之前哨站——理解RESTful2、Retrofit解析2...
    隔壁老李頭閱讀 15,163評論 4贊 39
  • Android 自定義View的各種姿勢1 Activity的顯示之ViewRootImpl詳解 Activity...
    passiontim閱讀 173,560評論 25贊 708
  • 今天要說的焦慮是：知識焦慮。 身邊的很多人都在同時通過多種方式在努力的學習，我也是一樣。訂閱優(yōu)質的微信公眾號每天閱...
    健健大俠閱讀 742評論 0贊 50