Retrofit 注解最全使用讲解

前言

retrofit 支持多种请求方式： DELETE GET HEAD PUT PATCH POST ,在Android中最常用的就是 get 和 post ，其他请求方式将不再进行考虑。

修饰方法体相关注解

@GET

作用：声明在方法上表示get请求

@POST

作用：声明在方法上表示Post请求

@Headers

作用：请求头中添加头信息
请求方式：@POST or @GET
修饰类型：声明在方法体上

//headers中只有一对值用法
@Headers("Cache-Control: max-age=640000")
@GET("/users")
Observable<List<User>> getUsers();

//headers中有多对值方法
@Headers({
"Accept: application/vnd.yourapi.v1.full+json",
"User-Agent: Your-App-Name"
})
@GET("/users")
Observable<List<User>> getUsers();

@Multipart

作用：混合类型网络请求，多用于文件上传，该注解需要配合@Part使用
注意事项：不能和@FormUrlEncoded 同时使用
请求方式：@POST
修饰类型： 声明在方法上

@Multipart
@POST("/users")
Observable<List<User>> getUsers();

//使用该注解，请求头中content-type为 multipart/form-data

@FormUrlEncoded

作用：声明表单提交，该注解需要配合@Field使用
请求方式： @POST
修饰类型： 声明在方法上

@FormUrlEncoded
@POST("/users")
Observable<List<User>> getUsers();

//使用该注解，请求头中content-type为 x-www-form-urlencoded

修饰参数类型相关注解

@Url

作用：定义relativeUrl
请求方式：@GET or @POST
修饰类型：修饰参数类型可以是基本数据类型（int float double long short byte boolean char） String, 数组 或者 集合 ,自定义数据类型（自定义数据类型需要复写toString方法，value值是通过toString来确定的，具体源码我会在写一篇专门分析）
注意事项：
1. @Url 在一个方法中不能重复使用
2. @Url 和 @Path @Query @queryMap @queryName 不能够同时使用
3. 使用该注解@GET和@POST()注解中不能有value值,其实使用 @GET/@POST也能达到同样的效果只需要GET或者POST里面声明url路径即可， 这两种方式选择一种，不可同时使用，同时使用会报错

@POST
Observable<List<User>> getUsers(@Url String relativeUrl);//传递参数值为users

@POST("/users")
Observable<List<User>> getUsers();

如上两种方式都能达到相同的效果
result:  http://192.168.1.1/users

@Path

作用：动态生成url路径
请求方式：@GET or @POST
修饰类型：修饰参数类型可以是基本数据类型 String, 数组 或者 集合 ,自定义数据类型（自定义数据类型需要复写toString方法）
注意事项：
1. @Path的声明必须在@Query 、 @QueryMap 、@QueryName之前；
2. 并且不能够和@Url一起使用；
3. @Get 和 @Post 注解中必须要有value值，并且value必须包含{} ， {} 中的值要和下面@Path中的值相匹配

@POST("/users/{nihao}")
Observable<List<User>> getUsers(@Path("nihao") String nihao); //传递参数值为paths

result: http://192.168.1.1/users/paths

@Query

作用：向url后面追加key value值
请求方式：@POST , @GET
修饰类型：修饰参数类型可以是基本数据类型 String, 数组 或者 集合 ,自定义数据类型（自定义数据类型需要复写toString方法）

@POST("/users")
Observable<List<User>> getUsers(@Query("since") int query)

//传入query = 1
result: http://192.168.1.1/users?since=1

@POST("/users")
Observable<List<User>> getUsers(@Query("since") List<String> lists); 

//传入参数lists
ArrayList<String> lists = new ArrayList<>();
lists.add("test1");
lists.add("test2");
lists.add("test3");

result: http://192.168.1.1/users?since=test1&since=test2&since=test3 


@POST("/users")
Observable<List<User>> getUsers(@Query("since") String[] array); 传递参数 array中包含 test1  test2  test3

result: http://192.168.1.1/users?since=test1&since=test2&since=test3

@QueryMap

作用：批量向url后追加key value 值
请求方式：请求方式：@POST , @GET
修饰类型：修饰的参数类型必须Map<k,v> k必须是String.class ,v类型为基本数据类型，String，或者自定义类

@POST("/users")
Observable<List<User>> getUsers(@QueryMap HashMap<String,String> maps); //传递参数 HashMap

其中HashMap的参数为：
HashMap<String,String> map = new HashMap<>();
map.put("key1","value1");
map.put("key2","value2");

result: http://192.168.1.1/users?key1=value1&key2=value2  

@QueryName

作用：url后追加key,此注解项目中几乎不会用到，一般url 后面追加的参数都是以key value的形式存在,所以@Query会使用较多
请求方式： @POST , @GET
修饰类型：修饰参数类型可以是基本数据类型 String 集合 或者数组

@POST("/users")
Observable<List<User>> getUsers(@QueryName String query)  //传递参数test

result: http://192.168.1.1/users?test   

@POST("/users")
Observable<List<User>> getUsers(@QueryName List<String> lists)

//lists参数为
ArrayList<String> lists = new ArrayList<>();
lists.add("test1");
lists.add("test2");
lists.add("test3");

result:http://192.168.1.1/users?test1&test2&test3

@Header

作用：请求头中添加头信息
请求方式： @POST , @GET
修饰类型：修饰参数类型可以是基本数据类型 String 集合 或者数组，从ServiceMethod中我们也可以看出对这些参数类型都是调用了toString 转换成为了String类型。

@POST("/users")
Observable<List<User>> getUsers(@Header("header1") String header); //传递参数 header的值为headerValue  

网络请求Header中就会有 header1 : headerValue
result: http://192.168.1.1/users

@HeaderMap

作用：批量向请求头中添加头信息
请求方式：@POST , @GET
修饰类型：修饰的参数类型必须Map<k,v> k必须是String.class ,v类型为基本数据类型，String，或者自定义类（复写toString）

@POST("/users")
Observable<List<User>> getUsers(@HeaderMap HashMap<String,String> maps); //传递参数 HashMap


其中HashMap的参数为：
HashMap<String,String> map = new HashMap<>();
map.put("header1","value1");
map.put("header2","value2");

则会在Header中添加多个头信息

@Field

作用：请求体中添加Field数据
注意事项：使用该注解必须在method方法上声明@FormUrlEncoded
请求方式：@POST
修饰类型：修饰参数类型可以是基本数据类型, String, 数组 或者 集合 ,自定义类（自定义类需要复写toString方法，并返回想传递的值）
content-type:application/x-www-form-urlencoded

@FormUrlEncoded
@POST("/users")
Observable<List<User>> getUsers(@Field("username") String username);

@FieldMap

作用：批量向请求体中添加Field数据
注意事项：使用该注解必须在method方法上声明@FormUrlEncoded
请求方式：@POST
修饰类型：修饰的参数类型必须是Map<k,v> k必须是String类型, v类型为基本数据类型，String，或者自定义类（复写toString）
content-type:application/x-www-form-urlencoded

@FormUrlEncoded
@POST("/users/{nihao}")
Observable<List<User>> getUsers(@FieldMap HashMap<String,Object> username);

@Part

作用：文件上传
注意事项：必需要搭配@Multipart注解使用
请求方式：@POST
修饰类型：如果@Part 修饰的参数类型为MultipartBody.Part 那么@Part注解不能有value值，否则必须@Part必须要有值，参数类型可以为基本数据类型，String，或者自定义类
content-type:multipart/form-data;

@Multipart
@POST("/users")
Observable<List<User>> getUsers(@Part("key1") String value, @Part MultipartBody.Part part);

@PartMap

作用：批量向请求体中添加Part数据，涉及到文件上传需要使用该注解
注意事项：该注解必需要搭配@Multipart注解使用
请求方式：@POST
修饰类型：该注解修饰的参数类型必须是Map<k,v> k 必须是String类型 ，v 不能为MultipartBody.Part 类型，可以为基本数据类型，String，或者自定义类请求头
content-type:multipart/form-data;

@Multipart
@POST("/users")
Observable<List<User>> getUsers(@Part HashMap<String,Object> hashMap);

eg:HashMap 中 value值类型 常见也就是String.class File.class

@Body

作用：添加请求体
注意事项：1.使用该注解就不能搭配@Multipart 和 @FormUrlEncoded 2.一个方法体里面只能有一个@Body,因为一次网络请求最多存在一个请求体
请求方式：@POST
修饰类型：该注解修饰的参数类型如果是 基本数据类型，String，或者自定义类
content-type:application/json

@POST("/users")
Observable<List<User>> getUsers(@Body String value);