写在前面
本篇文章基于retrofit-2.1进行分析.
1. 各个注解的含义及使用
1.1 Body注解:
- 作用于方法的参数
- 使用该注解定义的参数不可为null
- 当你发送一个post或put请求,但是又不想作为请求参数或表单的方式发送请求时,使用该注解定义的参数可以直接传入一个实体类,retrofit会通过convert把该实体序列化并将序列化后的结果直接作为请求体发送出去.
示例:
//实体
class Repo {
final String owner;
final String name;
Repo(String owner, String name) {
this.owner = owner;
this.name = name;
}
}
//接口
interface Service {
@POST("/")
Call<ResponseBody> sendNormal(@Body Repo repo);
* 1
* 2
* 3
* 4
* 5
* 6
* 7
* 8
* 9
* 10
* 11
* 12
* 13
* 14
* 15
1.2 DELETE注解:
- 用于发送一个DELETE请求
- DELETE注解一般必须添加相对路径或绝对路径或者全路径,如果不想在DELETE注解后添加请求路径,则可以在方法的第一个参数中用@Url注解添加请求路径
1.3 Field注解:
- 作用于方法的参数
- 用于发送一个表单请求
- 用String.valueOf()把参数值转换为String,然后进行URL编码,当参数值为null值时,会自动忽略,如果传入的是一个List或array,则为每一个非空的item拼接一个键值对,每一个键值对中的键是相同的,值就是非空item的值,如: name=张三&name=李四&name=王五,另外,如果item的值有空格,在拼接时会自动忽略,例如某个item的值为:张 三,则拼接后为name=张三.
示 例:
//普通参数
@FormUrlEncoded
@POST("/")
Call<ResponseBody> example(@Field("name") String name,@Field("occupation") String occupation);
//固定或可变数组
@FormUrlEncoded
@POST("/list")
Call<ResponseBody> example(@Field("name") String... names);
* 1
* 2
* 3
* 4
* 5
* 6
* 7
* 8
* 9
1.4 FieldMap注解:
- 作用于方法的参数
- 用于发送一个表单请求
- map中每一项的键和值都不能为空,否则抛出IllegalArgumentException异常
示例:
@FormUrlEncoded
@POST("/things")
Call<ResponseBody> things(@FieldMap Map<String, String> fields);
* 1
* 2
* 3
1.5 FormUrlEncoded注解:
- 用于修饰Field注解和FieldMap注解
- 使用该注解,表示请求正文将使用表单 网址编码。字段应该声明为参数,并用@Field注释或FieldMap注释。使用FormUrlEncoded注解的请求将具”application / x-www-form-urlencoded” MIME类型。字段名称和值将先进行UTF-8进行编码,再根据RFC-3986进行URI编码.
1.6 GET注解
- 用于发送一个get请求
- GET注解一般必须添加相对路径或绝对路径或者全路径,如果不想在GET注解后添加请求路径,则可以在方法的第一个参数中用@Url注解添加请求路径
1.7 HEAD注解
- 用于发送一个HEAD请求
- HEAD注解一般必须添加相对路径或绝对路径或者全路径,如果不想在HEAD注解后添加请求路径,则可以在方法的第一个参数中用@Url注解添加请求路径
1.8 Header注解:
- 作用于方法的参数,用于添加请求头
- 使用该注解定义的请求头可以为空,当为空时,会自动忽略,当传入一个List或array时,为拼接每个非空的item的值到请求头中.
- 具有相同名称的请求头不会相互覆盖,而是会照样添加到请求头中
示例:
@GET("/")
Call<ResponseBody> foo(@Header("Accept-Language") String lang);
* 1
* 2
1.9 HeaderMap注解:
- 作用于方法的参数,用于添加请求头
- 以map的方式添加多个请求头,map中的key为请求头的名称,value为请求头的值,且value使用String.valueOf()统一转换为String类型,
- map中每一项的键和值都不能为空,否则 抛出IllegalArgumentException异常
示例:
@GET("/search")
void list(@HeaderMap Map<String, String> headers);
//map
Map<String,String> headers = new HashMap()<>;
headers.put("Accept","text/plain");
headers.put("Accept-Charset", "utf-8");
* 1
* 2
* 3
* 4
* 5
* 6
* 7
2.0 Headers注解:
- 作用于方法,用于添加一个或多个请求头
- 具有相同名称的请求头不会相互覆盖,而是会照样添加到请求头中
示例:
//添加一个请求头
@Headers("Cache-Control: max-age=640000")
@GET("/")
...
//添加多个请求头
@Headers({ "X-Foo: Bar",
"X-Ping: Pong"
})
@GET("/")
...
* 1
* 2
* 3
* 4
* 5
* 6
* 7
* 8
* 9
* 10
2.1 HTTP注解:
- 作用于方法,用于发送一个自定义的HTTP请求
示例:
//自定义HTTP请求的标准样式
interface Service {
@HTTP(method = "CUSTOM", path = "custom/endpoint/")
Call<ResponseBody> customEndpoint();
}
//发送一个DELETE请求
interface Service {
@HTTP(method = "DELETE", path = "remove/", hasBody = true)
Call<ResponseBody> deleteObject(@Body RequestBody object);
}
* 1
* 2
* 3
* 4
* 5
* 6
* 7
* 8
* 9
* 10