Retrofit各个注解的含义及作用

本篇文章基于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

2.2 Multipart注解:

作用于方法
使用该注解,表示请求体是多部分的。 每一部分作为一个参数,且用Part注解声明

2.3 Part注解:

作用于方法的参数,用于定义Multipart请求的每个part
使用该注解定义的参数,参数值可以为空,为空时,则忽略
使用该注解定义的参数类型有以下3种方式可选: 
1, 如果类型是okhttp3.MultipartBody.Part，内容将被直接使用。 省略part中的名称,即 @Part MultipartBody.Part part 
2, 如果类型是RequestBody，那么该值将直接与其内容类型一起使用。 在注释中提供part名称（例如，@Part（“foo”）RequestBody foo）。 
3, 其他对象类型将通过使用转换器转换为适当的格式。 在注释中提供part名称（例如，@Part（“foo”）Image photo）。

示例:

@Multipart
@POST("/")
Call<ResponseBody> example(
@Part("description") String description,
@Part(value = "image", encoding = "8-bit") RequestBody image);

1
2
3
4
5

2.4 PartMap注解:

作用于方法的参数,以map的方式定义Multipart请求的每个part
map中每一项的键和值都不能为空,否则抛出IllegalArgumentException异常
使用该注解定义的参数类型有以下2种方式可选: 
1, 如果类型是RequestBody，那么该值将直接与其内容类型一起使用。 
2, 其他对象类型将通过使用转换器转换为适当的格式。

示例:

@Multipart
@POST("/upload")
Call<ResponseBody> upload(
@Part("file") RequestBody file,
@PartMap Map<String, RequestBody> params);

1
2
3
4
5

2.5 OPTIONS注解:

用于发送一个OPTIONS请求
OPTIONS注解一般必须添加相对路径或绝对路径或者全路径,如果不想在OPTIONS注解后添加请求路径,则可以在方法的第一个参数中用@Url注解添加请求路径

2.6 PATCH注解:

用于发送一个PATCH请求
PATCH注解一般必须添加相对路径或绝对路径或者全路径,如果不想在PATCH注解后添加请求路径,则可以在方法的第一个参数中用@Url注解添加请求路径

2.7 Path注解:

作用于方法的参数
在URL路径段中替换指定的参数值。使用String.valueOf()和URL编码将值转换为字符串。
使用该注解定义的参数的值不可为空
参数值默认使用URL编码

示例:

//标准使用方式,默认使用URL编码
@GET("/image/{id}")
Call<ResponseBody> example(@Path("id") int id);
//默认使用URL编码
@GET("/user/{name}")
Call<ResponseBody> encoded(@Path("name") String name);
//不使用URL编码
@GET("/user/{name}")
Call<ResponseBody> notEncoded(@Path(value="name", encoded=true) String name);

1
2
3
4
5
6
7
8
9

2.8 POST注解:

用于发送一个POST请求
POST注解一般必须添加相对路径或绝对路径或者全路径,如果不想在POST注解后添加请求路径,则可以在方法的第一个参数中用@Url注解添加请求路径

2.9 PUT注解:

用于发送一个PUT请求
PUT注解一般必须添加相对路径或绝对路径或者全路径,如果不想在PUT注解后添加请求路径,则可以在方法的第一个参数中用@Url注解添加请求路径

3.0 Query注解:

作用于方法的参数
用于添加查询参数,即请求参数
参数值通过String.valueOf()转换为String并进行URL编码
使用该注解定义的参数,参数值可以为空,为空时,忽略该值,当传入一个List或array时,为每个非空item拼接请求键值对,所有的键是统一的,如: name=张三&name=李四&name=王五.

示例:

@GET("/list")
Call<ResponseBody> list(@Query("page") int page);
@GET("/list")
Call<ResponseBody> list(@Query("category") String category);
//传入一个数组
@GET("/list")
Call<ResponseBody> list(@Query("category") String... categories);
//不进行URL编码
@GET("/search")
Call<ResponseBody> list(@Query(value="foo", encoded=true) String foo);

1
2
3
4
5
6
7
8
9
10

3.1 QueryMap注解:

作用于方法的参数
以map的形式添加查询参数,即请求参数
参数的键和值都通过String.valueOf()转换为String格式
map的键和值默认进行URL编码
map中每一项的键和值都不能为空,否则抛出IllegalArgumentException异常

示例:

//使用默认URL编码
@GET("/search")
Call<ResponseBody> list(@QueryMap Map<String, String> filters);
//不使用默认URL编码
@GET("/search")
Call<ResponseBody> list(@QueryMap(encoded=true) Map<String, String> filters);

1
2
3
4
5
6

3.2 Streaming注解:

作用于方法
处理返回Response的方法的响应体，即没有将body（）转换为byte []。

3.3 Url注解:

作用于方法参数
用于添加请求的接口地址

示例:

@GET
Call<ResponseBody> list(@Url String url);

1
2

注意事项:

1,以上部分注解真正的实现在ParameterHandler类中,,每个注解的真正实现都是ParameterHandler类中的一个final类型的内部类,每个内部类都对各个注解的使用要求做了限制,比如参数是否可空,键和值是否可空等.

2,FormUrlEncoded注解和Multipart注解不能同时使用,否则会抛出methodError(“Only one encoding annotation is allowed.”);可在ServiceMethod类中parseMethodAnnotation()方法中找到不能同时使用的具体原因.

3,Path注解与Url注解不能同时使用,否则会抛出parameterError(p, “@Path parameters may not be used with @Url.”),可在ServiceMethod类中parseParameterAnnotation()方法中找到不能同时使用的具体代码.其实原因也很好理解: Path注解用于替换url路径中的参数,这就要求在使用path注解时,必须已经存在请求路径,不然没法替换路径中指定的参数啊,而Url注解是在参数中指定的请求路径的,这个时候指定请求路径已经晚了,path注解找不到请求路径,更别提更换请求路径中的参数了.

4,对于FiledMap,HeaderMap,PartMap,QueryMap这四种作用于方法的注解,其参数类型必须为Map的实例,且key的类型必须为String类型,否则抛出异常(以PartMap注解为例):parameterError(p, “@PartMap keys must be of type String: ” + keyType);

5,使用Body注解的参数不能使用form 或multi-part编码,即如果为方法使用了FormUrlEncoded或Multipart注解,则方法的参数中不能使用Body注解,否则抛出异常parameterError(p, “@Body parameters cannot be used with form or multi-part encoding.”);

小结:

早就想把Retrofit的各个注解的含义和使用条件研究一番,但是几个月来一直加班,根本没多少时间仔细研读,中间有点闲暇时间也想偷个懒休息一下,眼看着已经是2016年最后一天了,再不研究就要等明年了,所以下定决心,花了大半天的时间,把Retrofit 2.1版本的源码彻底的读了一篇,边读变做笔记,读完之后把这些笔记又做了一些整理,才有了这2016年最后一篇博客.当然,文章中难免有错误或者不足之处,如果发现,还请及时告知,谢谢啦~~

读完源码,发现Retrofit并不像理想中的那么好,这里说的不好不是说代码架构不好,而是单指易用性这个方面,所有会用Retrofit的朋友,都知道如何使用Retrofit发送一个请求:
需要写至少一个接口
然后定义至少一个接口方法
然后构建Retrofit
然后调用create方法生成接口类
然后调用enqueue或者 execute方法发送一个异步或同步请求

一个简单的请求一共经历了5步,这还不算完: 

- 你需要添加json解析器,如GsonConvertFactory,来自动序列化json串 

- 你需要配置统一的cookie拦截器,这些代码需要你自己编写(网上复制粘贴的除外) 

- 一般你还需要添加日志拦截器,因为在debug的时候你会发现,Retrofit竟然他妈的不能拼接出完整的url请求地址(完整的请求地址包括请求的主机地址,接口名,所有请求参数拼接,Retrofit最多只能看到接口,后面拼接的参数是看不到的,这在调试的时候很让人不爽)

如果你说这些都不是事,那么我们再看:
Retrofit提供了MultiPart注解,说明我们可以上传文件,又提供了Streaming注解,说明我们可以下载文件,我们知道Retrofit可以干这些事,但是我们还是没有办法直接写上传下载代码,这些东西都需要我们自己去封装,这也是为什么目前有很多基于Retrofit构建的二次封装库的原因
很多人用Retrofit基本上也就会发送一个get或者post请求,也就熟悉个别几个作用于参数的注解,如果你让这些人用Retrofit去搞定所有RESTful风格的接口,可能大部分人直接懵逼,因为他们不知道各个方法的注解和参数的注解怎么搭配使用才能完美运行,而不是抛出异常,因为Retrofit制定的这些规则你必须遵守
有些狂热的Retrofit粉丝大呼Retrofit有着插拔式设计,想用就用,想不用就不用,耦合很低,这确实是Retrofit的优点,但也正是因为足够灵活,导致易用性不够,不然也不会产生这么多基于Retrofit构建的框架了。