网络通讯库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这一对最流行的框架搭配。