Retrofit 2.0 注解分类详解

分类

Retrofit 共22个注解，根据功能大概分为三类：

1. 请求方法类
2. 标记类
3. 参数类

请求方法类

序号 名称 1 GET 2 POST 3 PUT 4 DELETE 5 PATCH 6 HEAD 7 OPTIONS 8 HTTP

序号 1 ~ 7

• 分别对应 HTTP 的请求方法；
• 接收一个字符串表示接口 path ，与 baseUrl 组成完整的 Url；
• 可以不指定，结合 @Url 注解使用；
• url 中可以使用变量，如 {id} ，并使用 @Path(“id”) 注解为 {id} 提供值。

举个栗子

public interface BlogService{    @GET("blog/{id}")    Call<ResponseBody> getBlog(@Path("id") int id);}

序号 8

• 可用于替代以上 7 个，及其他扩展方法；
• 有 3 个属性：method、path、hasBody、 举个栗子

public interface BlogService{    /**    * Cmethod  请求方法，不区分大小写    * path    路径    * hasBody 是否有请求体    */    @HTTP(method = "get", path = "blog/{id}", hasBody = false)    Call<ResponseBody> getBlog(@Path("id") int id);}

标记类

分类 名称 备注 表单请求 FormUrlEncoded 请求体是 From 表单 ~~ Multipart 请求体是支持文件上传的 From 表单 标记 Streaming 响应体的数据用流的形式返回

FormUrlEncoded

登录页面使用：Content-Type:application/x-www-form-urlencoded

• 用于修饰Field注解和FieldMap注解
• 使用该注解,表示请求正文将使用表单网址编码。字段应该声明为参数，并用@Field注释或FieldMap注释。使用FormUrlEncoded注解的请求将具”application/ x-www-form-urlencoded”MIME类型。字段名称和值将先进行UTF-8进行编码,再根据RFC-3986进行URI编码.

Multipart

上传文件使用：Content-Type:multipart/form-data

//传单个文件@Multipart@POST("v1/create")Call<ResponseBody> create(@Part("pictureName") RequestBody pictureName,  @Part MultipartBody.Part pictureRequestBody pictureNameBody = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), "pictureName");File picture= new File(path);RequestBody requestFile = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), picture);// MultipartBody.Part is used to send also the actual file nameMultipartBody.Part picturePart = MultipartBody.Part.createFormData("picture", picture.getName(), requestFile);//调接口create(pictureNameBody, picturePart);//传多个文件@Multipart@POST("v1/create")Call<ResponseBody> create(@Part("pictureName") RequestBody pictureName,   @PartMap Map<String, RequestBodyRequestBody pictureNameBody = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), "pictureName");File picture= new File(path);RequestBody requestFile = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), picture);Map<String, RequestBody> params = new HashMap<>();params.put("picture\"; filename=\"" + picture.getName() + "", requestFile);//调接口create(pictureNameBody, params);

Streaming

未使用该注解，默认会把数据全部载入内存，之后通过流获取数据也是读取内存中数据，所以返回数据较大时，需要使用该注解。

参数类

分类 名称 备注 作用于方法 Headers 添加请求头 作用于方法参数(形参) Header 添加不固定的 Header ~~ Body 非表单请求体 ~~ Field 表单字段，与 FieldMap、FormUrlEncoded 配合 ~~ FieldMap 表单字段，与 Field、FormUrlEncoded 配合；接受 Map< String,String>类型，非 String 类型会调用 toString() 方法 ~~ Part 表单字段，与 PartMap 配合，适合文件上传情况 ~~ PartMap 表单字段，与 Part 配合，适合文件上传情况；默认接受 Map< String, RequestBody> 类型，非 RequestBody 会通过 Converter 转换 ~~ HeaderMap 用于URL，添加请求头 ~~ Path 用于URL ~~ Query 用于URL ~~ QueryMap 用于URL ~~ Url 用于URL

注意：

1. Map 用来组合复杂的参数；
2. Query、QueryMap 与 Field、FieldMap 功能一样，生成的数据形式一样； Query、QueryMap
   的数据体现在 Url 上； Field、FieldMap 的数据是请求体；
3. {占位符}和 PATH 尽量只用在URL的 path 部分，url 中的参数使用 Query、QueryMap 代替，保证接口的简洁；
4. Query、Field、Part 支持数组和实现了 Iterable 接口的类型， 如
   List、Set等，方便向后台传递数组，示例如下：

Call<ResponseBody> foo(@Query("ids[]") List<Integer> ids);// 结果// ids[]=0&ids[]=1&ids=2

Headers

使用 @Headers注解设置固定的请求头，所有请求头不会相互覆盖，即使名字相同。

@Headers("Cache-Control: max-age=640000")@GET("widget/list")Call<List<Widget>> widgetList();@Headers({ "Accept: application/vnd.github.v3.full+json","User-Agent: Retrofit-Sample-App"})@GET("users/{username}")Call<User> getUser(@Path("username") String username);

Header

使用 @Header注解动态更新请求头，匹配的参数必须提供给 @Header ，若参数值为 null ，这个头会被省略，否则，会使用参数值的 toString 方法的返回值。

@GET("user")Call<User> getUser(@Header("Authorization") String authorization)

Body

使用@Body注解，指定一个对象作为 request body 。

@POST("users/new")Call<User> createUser(@Body User user);

对象会被 Retrofit实例中指定的转换器转换，若未添加转换器，只能使用RequestBody ，如下：

@POST("users/new")Call<RequestBody> createUser(@Body User user);

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);

FieldMap

• 作用于方法的参数
• 用于发送一个表单请求
• map中每一项的键和值都不能为空,否则抛出IllegalArgumentException异常

示例:

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

Part

• 作用于方法的参数,用于定义Multipart请求的每个part
  
• 使用该注解定义的参数,参数值可以为空,为空时,则忽略
  
• 使用该注解定义的参数类型有以下3种方式可选:
  1, 如果类型是okhttp3.MultipartBody.Part，内容将被直接使用。省略part中的名称,即 @Part MultipartBody.Part part
  
  2,如果类型是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);

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);

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");

Path

请求 URL 可以替换模块来动态改变，替换模块是 {}包含的字母数字字符串，替换的参数必须使用 @Path 注解的相同字符串。

// 链接 http://baseurl/blog/idpublic interface BlogService{    @GET("blog/{id}")    Call<ResponseBody> getBlog(@Path("id") int id);}

Query

• 作用于方法的参数
• 用于添加查询参数,即请求参数
• 参数值通过String.valueOf()转换为String并进行URL编码
• 使用该注解定义的参数,参数值可以为空,为空时,忽略该值,当传入一个List或array时,为每个非空item拼接请求键值对,所有的键是统一的,如:
  name=张三&name=李四&name=王五.

// 链接 http://baseurl/blog/id?sort=ShortStrpublic interface BlogService{    @GET("blog/{id}")    Call<ResponseBody> getBlog(@Path("id") int id, @Query("sort") String sort);}//传数组public interface BlogService{    @GET("blog/{id}")    Call<ResponseBody> getBlog(@Path("id") int id, @Query("linked[]") String... linked);}

QueryMap

复杂的查询参数

// 链接 http://baseurl/blog/id?param1=Param1&param2=Param2...public interface BlogService{    @GET("blog/{id}")    Call<ResponseBody> getBlog(@Path("id") int id, @QueryMap Map<String, String> options);}

Url

• 作用于方法参数
• 用于添加请求的接口地址

示例:

@GETCall<ResponseBody> list(@Url String url);