Retrofit 2.0 个注解详解

本文转载来自http://www.jianshu.com/p/bf884248cb37

分类

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

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

请求方法类

序号名称1GET2POST3PUT4DELETE5PATCH6HEAD7OPTIONS8HTTP

序号 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

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 转换~~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

表单提交，如登录

 @FormUrlEncoded @POST("v1/login") Call<ResponseBody> userLogin(@Field("phone") String phone, @Field("password") String password);

FieldMap

Part

PartMap

Path

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

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

Query

查询参数

// 链接 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