网络通讯库Retrofit精炼详解第（二）课：Retrofit各种注解的使用

一、前期基础知识储备

在上一篇文章《网络通讯库Retrofit精炼详解第（一）课：Retrofit基础理论和简单实现》中，笔者详细介绍了Retrofit的一些基础知识，并留下了有关于Retrofit注解类型的问题到第二篇文章，那么本文就来具体讲解一下Retrofit中各种注解类型的使用。
以下是Retrofit的常用注解表：

Path	GET	Query	QueryMap
Patch	POST	Field	FieldMap
Multipart	HTTP	Part	PartMap
Streaming	PUT	Url	HEAD
FormUrlEncoded	DELETE	Body	Header

二、上代码，具体实现

在发出HTTP请求时，需要传入参数，而Retrofit中通过各种注解的形式令 Http 请求的参数变得更加直接，而且类型也更加安全。
（1）@Query &@ QueryMap——查询参数的设置
@GET("/list")  //此处的Value中传入一个绝对路径
Call<ResponseBody> list(@Query("page") int page);
--------------------------------------------------------
Query 其实就是 Url 中‘?’ 后面的 key-value，比如以下这种url类型： http://www.println.net/?page=android 这里的 page=android 就是一个 Query，而我们在配置它的时候只需要在接口方法中增加一个参数，即可：
interface PrintlnServer{   
  @GET("/")    //这里的gate()方法由@GET注解标记为get请求
  Call<String> gate(@Query("gate") String gate);//()里面实际上只有一个参数
}
这时候你肯定想，如果我有很多个 Query，这么一个个写岂不是很累？而且根据不同的情况，有些字段可能不传，这与方法的参数要求显然也不相符。于是，打群架版本的 QueryMap 横空出世了，使用方法很简单：
Call<gitmodel> manykey(@QueryMapMap<String, String> options);
（2）@Field & @FieldMap——POST请求/表单方式传递 键值对
其实我们用 POST 的场景相对较多，绝大多数的服务端接口都需要做加密、鉴权和校验，GET 显然不能很好的满足这个需求。使用 POST 提交表单的场景就更是刚需了，怎么提呢？
public interface SignInService {
@FormUrlEncoded  //表单方式传递键值对
@POST("/")  
Call<ResponseBody>example(
@Field("name")String name, @Field("password")String password); 
--------------------------------------------------------
其实也很简单，我们只需要定义上面的接口就可以了，我们用 Field 声明了表单的项，这样提交表单就跟普通的函数调用一样简单直接了。
（3）@Part & @PartMap——单文件/多文件上传
Volley网络通讯库的一大缺陷就是无法应对用户上传和下载的需求，用Retrofit完美的解决了这个问题。
public interface FileUploadService { 
   @Multipart  // @MultiPart的意思就是允许多个@Part
   @POST("upload")   
  Call<ResponseBody> upload(
@Part("description")RequestBody description, @Part  MultipartBody.Part file);                             
}
public interface IUserBiz{
     @Multipart
     @POST("register")
    Call<User> registerUser(
    @PartMapMap<String, RequestBody> params,  
    @Part("password") RequestBodypassword);
}
--------------------------------------------------------
如果你需要上传文件，和我们前面的做法类似，定义一个接口方法，需要注意的是，这个方法不再有 @FormUrlEncoded 这个注解，而换成了 @Multipart，后面只需要在参数中增加 Part 就可以了。
（4）@PATH——动态的url访问
retrofit非常适用于restfulurl的格式，那么例如下面这样的url：
//用于访问zhy的信息 http://192.168.1.102:8080/springmvc_users/user/zhy //用于访问lmj的信息 http://192.168.1.102:8080/springmvc_users/user/lmj 即通过不同的username访问不同用户的信息，返回数据为json字符串。那么可以通过retrofit提供的@PATH注解非常方便的完成上述需求。
public interface IUserBiz{
    @GET("{username}")
   Call<User> getUser(@Path("username")String username);
}
//访问代码如下：
Call<User> call =userBiz.getUser("zhy");
Call<User> call =userBiz.getUser("lmj");
可以看到我们定义了一个getUser方法，方法接收一个username参数，并且我们的@GET注解中使用{username}声明了访问路径，这里你可以把{username}当做占位符，而实际运行中会通过@PATH("username")所标注的参数进行替换。
（5）@Body——向服务器传入json字符串
大家都清楚，我们app很多时候跟服务器通信，会选择直接使用POST方式将json字符串作为请求体发送到服务器，那么我们看看这个需求使用retrofit该如何实现。
public interface IUserBiz{
 @POST("add")
 Call<List<User>> addUser(@Body User user);
}
//省略retrofit的构建代码
 Call<List<User>> call =userBiz.addUser(
newUser(1001, "jj", "123,", "jj123","jj@qq.com"));
//注意往接口方法中传入的参数要是json字符串格式
三、call对象执行http请求时常常添加的依赖文件Gson: com.squareup.retrofit2:converter-gson
Jackson: com.squareup.retrofit2:converter-jackson
Moshi: com.squareup.retrofit2:converter-moshi
Protobuf: com.squareup.retrofit2:converter-protobuf
Wire: com.squareup.retrofit2:converter-wire
Simple XML: com.squareup.retrofit2:converter-simplexml
Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars具体的版本号，大家根据自己的gradle文件进行添加。
 小结：好了，以上就是一些常用的方法，还涉及到一些没有介绍的注解，比如Patch、Streaming、HTTP、PUT、Url、HEAD、Header、DELETE，后期有时间会再补充一次。
 文章的末尾，在分享一些非常好的学习Retrofit的资料：
《用 Retrofit 2 简化 HTTP 请求》——Retrofit作者本人Jake Wharton所写；

《Retrofit2 完全解析 探索与okhttp之间的关系》——鸿洋大神所著的Retrofit完全解析
到此为止，我们就差不多都学了Retrofit的常用知识点，相信在以后的开发里惠更加的清晰Retrofit的用法。在实际项目中，我们常常会使用不同的框架进行搭配，做出最好的效果，接下来的一篇文章，笔者将和大家一起学习Retrofit+RxJava这一对最流行的框架搭配。