Android Retrofit 2.0 注解的理解

Retrofit 2.0包含众多的注解，包括
方法注解，包含@GET、@POST、@PUT、@DELETE、@PATH、@HEAD、@OPTIONS、@HTTP。
标记注解，包含@FormUrlEncoded、@Multipart、@Streaming。
参数注解，包含@Query,@QueryMap、@Body、@Field，@FieldMap、@Part，@PartMap。
其他注解，@Path、@Header,@Headers、@Url


1.@Path：URL占位符，用于替换和动态更新,相应的参数必须使用相同的字符串被@Path进行注释

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);

2.@Feild 和 @Query 
@FeildMap 和 @QueryMap 区别

@Query,@QueryMap:查询参数，用于GET查询,需要注意的是@QueryMap可以约定是否需要encode

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);

@Query也可以用于@Post

@Field，@FieldMap:Post方式传递简单的键值对,需要添加@FormUrlEncoded表示表单提交
Content-Type:application/x-www-form-urlencoded

当函数有@FormUrlEncoded注解的时候，将会发送form-encoded数据，每个键-值对都要被含有名字的@Field注解和提供值的对象所标注

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

3.@PUT @Part @MultiPart @Body的使用

@PUT是方法注解，稍后会统一说明

@Part，@PartMap：用于POST文件上传
其中@Part MultipartBody.Part代表文件，@Part("key") RequestBody代表参数
需要添加@Multipart表示支持文件上传的表单，Content-Type: multipart/form-data

当函数有@Multipart注解的时候，将会发送multipart数据，Parts都使用@Part注解进行声明

Multipart parts要使用Retrofit的众多转换器之一或者实现RequestBody来处理自己的序列化

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

@Body

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

4.@Headers @Header 方法注解@HEAD

@HEAD是方法注解，与参数注解@Header不同，下面会统一说明。

@Header：header处理，不能被互相覆盖，用于修饰参数，在参数中的@Header可以作为@Headers的增项使用

//动态设置Header值
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

等同于:

//静态设置Header值
@Headers("Authorization: authorization")//这里authorization就是上面方法里传进来变量的值
@GET("widget/list")
Call<User> getUser()

@Headers 用于修饰方法,用于设置多个Header值：

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call<User> getUser(@Path("username") String username);

5.@Url

@Url，它允许我们直接传入一个请求的URL。这样以来我们可以将上一个请求的获得的url直接传入进来。方便了我们的操作。

@GET
Call<List<Contributor>> repoContributorsPaginate(@Url String url);

6.方法注解@PATCH、@OPTIONS、@HTTP、@HEAD、@PUT、@GET、@PUT、@DELETE
方法注解和RESTFUL API有关

@PUT，PUT方法用来创建一个URI已知的资源，或对已知资源进行完全替换，比如users/1， 因此PUT方法一般会用来更新一个已知资源，

    除非在创建前，你完全知道自己要创建的对象的URI。  

@PATCH ，PATCH方法是新引入的，是对PUT方法的补充，用来对已知资源进行局部更新

@HEAD ，与参数注解@Header不同， 只请求页面的首部。

@OPTIONS  允许客户端查看服务器的性能

@HTTP ,使用用户自定义的verb进行网络请求

参考文章

http://www.jianshu.com/p/3e13e5d34531

http://kb.cnblogs.com/page/512047/