分类

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

1. 请求方法类
2. 标记类
3. 参数类

请求方法类

序号 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

登录页面使用：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

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

参数类

注意：

1. Map 用来组合复杂的参数；

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

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

4. 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);
}

Url