Retrofit 2.0 注解篇

分类

Retrofit 共22个注解，根据功能大概分为三类：

请求方法类
标记类
参数类

请求方法类

序号	名称
1	`GET`
2	`POST`
3	`PUT`
4	`DELETE`
5	`PATCH`
6	`HEAD`
7	`OPTIONS`
8	`HTTP`

序号 1 ~ 7

分别对应 HTTP 的请求方法；
接收一个字符串表示接口 path ，与 baseUrl 组成完整的 Url；
可以不指定，结合 @Url 注解使用；
url 中可以使用变量，如 {id} ，并使用 @Path("id") 注解为 {id} 提供值。

举个栗子

public interface BlogService{
    @GET("blog/{id}")
    Call<ResponseBody> getBlog(@Path("id") int id);
}

序号 8

可用于替代以上 7 个，及其他扩展方法；
有 3 个属性：method、path、hasBody、

举个栗子

public interface BlogService{
    /**
    * Cmethod  请求方法，不区分大小写
    * path    路径
    * hasBody 是否有请求体
    */
    @HTTP(method = "get", path = "blog/{id}", hasBody = false)
    Call<ResponseBody> getBlog(@Path("id") int id);
}

标记类

分类	名称	备注
表单请求	`FormUrlEncoded`	请求体是 `From` 表单
~~	`Multipart`	请求体是支持文件上传的 `From` 表单
标记	`Streaming`	响应体的数据用流的形式返回

FormUrlEncoded

登录页面使用：Content-Type:application/x-www-form-urlencoded

Multipart

上传文件使用：Content-Type:multipart/form-data

//传单个文件
@Multipart
@POST("v1/create")
Call<ResponseBody> create(@Part("pictureName") RequestBody pictureName,  @Part MultipartBody.Part picture

RequestBody pictureNameBody = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), "pictureName");
File picture= new File(path);
RequestBody requestFile = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), picture);
// MultipartBody.Part is used to send also the actual file name
MultipartBody.Part picturePart = MultipartBody.Part.createFormData("picture", picture.getName(), requestFile);
//调接口
create(pictureNameBody, picturePart);

//传多个文件
@Multipart
@POST("v1/create")
Call<ResponseBody> create(@Part("pictureName") RequestBody pictureName,   @PartMap Map<String, RequestBody

RequestBody pictureNameBody = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), "pictureName");
File picture= new File(path);
RequestBody requestFile = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), picture);
Map<String, RequestBody> params = new HashMap<>();
params.put("picture\"; filename=\"" + picture.getName() + "", requestFile);
//调接口
create(pictureNameBody, params);

Streaming

未使用该注解，默认会把数据全部载入内存，之后通过流获取数据也是读取内存中数据，所以返回数据较大时，需要使用该注解。

参数类

分类	名称	备注
作用于方法	`Headers`	添加请求头
作用于方法参数(形参)	`Header`	添加不固定的 `Header`
~~	`Body`	非表单请求体
~~	`Field`	表单字段，与 `FieldMap`、`FormUrlEncoded` 配合
~~	`FieldMap`	表单字段，与 `Field`、`FormUrlEncoded` 配合；接受 `Map<String, String>` 类型，非 `String` 类型会调用 `toString()` 方法
~~	`Part`	表单字段，与 `PartMap` 配合，适合文件上传情况
~~	`PartMap`	表单字段，与 `Part` 配合，适合文件上传情况；默认接受 `Map<String, RequestBody>` 类型，非 `RequestBody` 会通过 `Converter` 转换
~~	`Path`	用于URL
~~	`Query`	用于URL
~~	`QueryMap`	用于URL
~~	`Url`	用于URL

注意：

Map 用来组合复杂的参数；

Query、QueryMap 与 Field、FieldMap 功能一样，生成的数据形式一样；
Query、QueryMap 的数据体现在 Url 上；
Field、FieldMap 的数据是请求体；

{占位符}和 PATH 尽量只用在URL的 path 部分，url 中的参数使用 Query、QueryMap 代替，保证接口的简洁；

Query、Field、Part 支持数组和实现了 Iterable 接口的类型，如 List、Set等，方便向后台传递数组，示例如下：

Call<ResponseBody> foo(@Query("ids[]") List<Integer> ids);
// 结果
// ids[]=0&ids[]=1&ids=2

Headers

使用 @Headers 注解设置固定的请求头，所有请求头不会相互覆盖，即使名字相同。

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();

@Headers({ "Accept: application/vnd.github.v3.full+json","User-Agent: Retrofit-Sample-App"})
@GET("users/{username}")Call<User> getUser(@Path("username") String username);

Header

使用 @Header 注解动态更新请求头，匹配的参数必须提供给 @Header ，若参数值为 null ，这个头会被省略，否则，会使用参数值的 toString 方法的返回值。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

Body

使用 @Body 注解，指定一个对象作为 request body 。

@POST("users/new")
Call<User> createUser(@Body User user);

对象会被 Retrofit 实例中指定的转换器转换，若未添加转换器，只能使用 RequestBody ，如下：

@POST("users/new")
Call<RequestBody> createUser(@Body User user);

Field

表单提交，如登录

 @FormUrlEncoded
 @POST("v1/login")
 Call<ResponseBody> userLogin(@Field("phone") String phone, @Field("password") String password);

FieldMap

 @FormUrlEncoded
 @POST("v1/login")
 Call<ResponseBody> userLogin(@FieldMap map Map<String,String>);

Part

PartMap

Path

请求 URL 可以替换模块来动态改变，替换模块是 {}包含的字母数字字符串，替换的参数必须使用 @Path 注解的相同字符串。

// 链接 http://baseurl/blog/id
public interface BlogService{
    @GET("blog/{id}")
    Call<ResponseBody> getBlog(@Path("id") int id);
}

Query

查询参数

// 链接 http://baseurl/blog/id?sort=ShortStr
public interface BlogService{
    @GET("blog/{id}")
    Call<ResponseBody> getBlog(@Path("id") int id, @Query("sort") String sort);
}

//传数组
public interface BlogService{
    @GET("blog/{id}")
    Call<ResponseBody> getBlog(@Path("id") int id, @Query("linked[]") String... linked);
}

QueryMap

复杂的查询参数

// 链接 http://baseurl/blog/id?param1=Param1&param2=Param2...
public interface BlogService{
    @GET("blog/{id}")
    Call<ResponseBody> getBlog(@Path("id") int id, @QueryMap Map<String, String> options);
}

Retrofit 2.0 注解篇