Retrofit 中的注解定义在 retrofit.http 包下，包含了 Retrofit 用到的注解。主要分为两类，HTTP请求注解（针对函数）和参数注解（针对参数）。
本文对各种注解的用法做了个简单的介绍。
This post includes a simple introduction to retrofit annotations and some concise example.
// 上一行是为了谷歌爸爸的 SEO （ 逃
Annotations for interface methods to control the HTTP request behavior.
package-info.java中写到, 这里包含了定义的Retrofit接口中的方法用来控制HTTP请求行为的注解.
参数注解
@Query & @QueryMap
和
GET结合使用，使用@QueryMap可以动态添加字段
- 简单示例：
1
2("/friends")
Call<ResponseBody> friends(@Query("page") int page);
调用 foo.friends(1) 产生 /friends?page=1
- 参数为null的情况：
1
2("/friends")
Call<ResponseBody> friends(@Query("group") String group);
调用 foo.friends(null) 产生 /friends
- 数组和 varargs 示例：
1
2("/friends")
Call<ResponseBody> friends(@Query("group") String... groups);
调用 foo.friends("coworker", "bowling") 产生 /friends?group=coworker&group=bowling
@QueryName
适用于没有 值 的查询参数
1 | ("/friends") |
foo.friends("contains(Bob)", "age(42)") –> /friends?contains(Bob)&age(42)
直接是
?filter1&filter2而不是?filter1=foo&filter2=bar
@Field & @FieldMap
和
POST结合使用，使用@FieldMap可以动态添加
- 简单示例：
1
2
3
4
("/")
Call<ResponseBody> example(@Field("name") String name,
@Field("occupation") String occupation);
调用
foo.example("Bob Smith", "President")所产生请求的 body 为name=Bob+Smith&occupation=President
- 数组和 varargs 示例：参考
@GET
@Header & @HeaderMap
@Header和@HeaderMap用来添加请求头
需要注意的地方：
- header 不会相互覆盖，重复的添加会在请求头产生多行记录
- 对于值 null 的情况，键会被忽略
- 值的类型为 List 或 Array 时，其中的非空值会被分解为多条。 eg.
name : ["Jiang", "Min"] --> name: Jiang \r\n name: Min
@Body
在参数上使用这个注解来直接控制 POST/PUT 请求的 body 。如果是对象的化将由 Retrofit中指定的
Converter来进行序列化，序列化结果将被直接设置为请求的 body 。比如，直接使用和后端对应的实体类作为参数，使用Gson来进行序列化)
一个例子：
1 | /* 接口定义 */ |
1 | OkHttp: --> POST http://sample.com/abc |
@Part & @PartMap
与方法注解
@Multipart结合使用
根据修饰的参数类型分为三类
okhttp3.MultipartBody.Part, Retrofit 将直接使用参数内包含的信息。
如@Part MultipartBody.Part part，使用默认注解参数。okhttp3.RequestBody RequestBody, 同样 Retrofit 将直接使用参数内包含的信息。同时会用到@Part的参数。 比如@Part("foo") RequestBody foo。- others , 其他类型的对象将经由
Converter来转换成合适的格式，也会用到@Part的参数。
@Url
用来动态指定要请求的 URL
@Path
@Path注解用来替换 url 的 key
1 | GET("/image/{id}") |
foo.example(233) –> /image/233
方法注解
@GET
GET 请求用来获取服务器端的资源。GET 仅仅应该用来获取数据而不应该产生其他副作用。
@POST
POST 被设计用来请求 web 服务器接受包含在 请求消息正文(request message body) 中的数据。当上传文件或提交完整的网页表单时，经常使用它。
用途比较广泛，比如 公告板消息、一条评论、网页表单产生的一大坨数据、一些可以放到数据库中的实体数据 等等。
@PUT
PUT 一般用来请求服务器存储特定 URI 便是的资源。服务器一般会更新（已经存在）或新建（之前不存在）资源文件。
@DELETE
字面意思，删除。
@PATCH
Path ~ 补丁，对特定资源进行部分（partial）修改。
@OPTIONS
对于 OPTIONS 请求，服务器返回该 URL 支持的所有 HTTP 请求种类。
@HEAD
HEAD基本等价于没有response body的GET请求。如果返回的数据在response header中，使用 HEAD 会很合适。
@HTTP
使用自定义的 HTTP 操作，比如：
1 | (method = "KISS", path = "/beauties/girlfriend") |
此注解还可以用来发送带 body 的 DELETE 请求：1
2(method = "DELETE", path = "remove/", hasBody = true)
Call<ResponseBody> deleteObject(@Body RequestBody object);
@Multipart
表示请求体为
multi-part, 这些part应该使用@Part注解。
一个示例：1
2
3
("/")
Call<ResponseBody> example(@Part("description") String description, @Part(value = "image", encoding = "8-bit") RequestBody image);
@FormUrlEncoded
表示请求体会使用
URL形式的表单编码(form url encoding)，字段（体现在接口中是形参）应该使用@Part注解。使用这个注解产生的请求的请求头中会有application/x-www-form-urlencodedMIME 类型。字段的键值在编码前会先被编码为UTF-8
@Headers
对于 header 的值确定的情况，可以直接使用作用于方法的注解
就像下面这样：
1 | ("Cache-Control: max-age=640000") |
@Streaming
将方法返回的
okhttp3.Response Response保持原样，不将okhttp3.Response#body() body()转换为byte[]
Ref:
Hypertext Transfer Protocol - Wikipedia
via boileryao
happy coding :)