Android Retrofit 使用

TimeFine
934 阅读6分钟

一、注解

1.请求头注解

请求头注解说明
@Headers用于添加固定请求头，可以同时添加多个，通过该注解的请求头不会相互覆盖，而是共同存在
@Header作为方法的参数传入，用于添加不固定的header，它会更新已有请求头

2.请求方法注解

请求方法注解说明
@GETget请求
@POSTpost请求
@PUTput请求
@DELETEdelete请求
@PATCHpatch请求，该请求是对put请求的补充，用于更新局部资源
@HEADhead请求
@OPTIONSoptions请求
@HTTP通过注解，可以替换以上所有的注解，它拥有三个属性：method、path、hasBody

3.请求参数注解

请求参数注解说明
@Body多用于Post请求发送非表达数据，根据转换方式将实例对象转化为对应字符串传递参数，比如使用Post发送Json数据，添加GsonConverterFactory则是将body转化为json字符串进行传递
@Filed多用于Post方式传递参数，需要结合@FromUrlEncoded使用，即以表单的形式传递参数
@FiledMap多用于Post请求中的表单字段，需要结合@FromUrlEncoded使用
@Part用于表单字段，Part和PartMap与@multipart注解结合使用，适合文件上传的情况
@PartMap用于表单字段，默认接受类型是Map<String,RequestBody>，可用于实现多文件上传
@Path用于Url中的占位符
@Query用于Get请求中的参数
@QueryMap与Query类似，用于不确定表单参数
@Url指定请求路径

4.请求和响应格式(标记)注解

标记类注解说明
@FromUrlCoded表示请求发送编码表单数据，每个键值对需要使用@Filed注解
@Multipart表示请求发送form_encoded数据(使用于有文件上传的场景)，每个键值对需要用@Part来注解键名，随后的对象需要提供值
@Streaming表示响应用字节流的形式返回，如果没有使用注解，默认会把数据全部载入到内存中，该注解在下载大文件时特别有用

二、使用

假设BaseUrl为

https://api.github.com/

解析的基类为

ResponseBody

1、请求头@Header

请求头注解，用于添加不固定请求头,作用于方法的参数，作为方法的参数传入，该注解会更新已有的请求头

@GET("user/emails") 
Call<ResponseBody> getHeaderData(@Header("token") String token);

2、请求头@Headers

请求头注解，用于添加固定请求头，可以添加多个

@Headers({"phone-type:android", "version:1.1.1"}) 
@GET("user/emails") 
Call<ResponseBody> getHeadersData();

3、@Get请求

1）占位@Path

@GET("orgs/{id}") 
Call<ResponseBody> getPathData(@Path("id") long idLong);
请求链接: https://api.github.com/orgs/idLong

2) 追加参数@Query

@GET("user") 
Call<ResponseBody> getData(@Query("name") String nameStr,@Query("age") int ageNum);  
请求链接：https://api.github.com/user?name=nameStr&age=ageNum

3) 追加参数@QueryMap

Map<String, Object> map = new HashMap<>(); 
map.put("id", 100); 
map.put("name", "张三");

@GET("user") 
Call<ResponseBody> getData(@QueryMap Map<String,Object> map);  
请求链接：https://api.github.com/user?id=100&name=张三

4、@Post请求

1) 表单提交参数@Field

@FormUrlEncoded    请求格式注解，请求实体是一个From表单，每个键值对需要使用@Field注解.

@FormUrlEncoded 
@POST("user/emails") 
Call<ResponseBody> getData(@Field("name") String nameStr, @Field("sex") String sexStr);

2) 表单提交参数@FieldMap

@FormUrlEncoded    请求格式注解，请求实体是一个From表单，每个键值对需要使用@Field注解.

@FormUrlEncoded 
@POST("user/emails") 
Call<ResponseBody> getData(@FieldMap Map<String,Object> map);

3) 对象形式提交参数@Body

上传json格式数据，直接传入实体它会自动转为json，这个转化方式是GsonConverterFactory定义的。 把参数封装在对象中,比如有下面的User.class

public class User {
    String name;
    String sex;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }
}

请求前把参数都设置好,比如

User user = new User();
user.setName("张三");
user.setSex("男");

将user传入下面的请求即可。这种方式对于多参数请求是很实用的。

@POST("user/emails") 
Call<ResponseBody> getData(@Body User user);

5、@HTTP请求

@HTTP注解的作用是替换@GET、@POST、@PUT、@DELETE、@HEAD以及更多拓展功能

@HTTP(method = "GET", path = "user/keys", hasBody = false)
Call<ResponseBody> getData();
  • method              表示请求的方法，区分大小写，这里的值retrofit不会再做任何处理，必须要保证正确
  • path                   网络请求地址路径
  • hasBody            是否有请求体，boolean类型

@HTTP注解可以通过method字段灵活设置具体请求方法，通过path设置网络请求地址，用的比较少。@HTTP替换@POST、@PUT、@DELETE、@HEAD等方法的用法类似，这里就不一一讲解了。

6、@Url地址重定向

如果需要重新地址接口地址，可以使用@Url，将地址以参数的形式传入即可。如果有@Url注解时，GET传入的Url可以省略。

@GET
Call<ResponseBody> getData(@Url String nameStr, @Query("id") long idLong);

7）@Streaming

 @Streaming
 @POST("gists/public")
 Call<ResponseBody> getStreamingBig();
  • @Streaming  表示响应体的数据用流的方式返回，使用于返回数据比较大，该注解在下载大文件时特别有用 我们在使用下载比较大的文件的时候需要添加@Streaming注解。

8）@Multipart、@part、@PartMap

@Multipart
@POST("user/followers")
Call<ResponseBody> getPartData(@Part("name") RequestBody name, @Part MultipartBody.Part file);
  • @Multipart 表示请求实体是一个支持文件上传的表单，需要配合@Part和@PartMap使用，适用于文件上传。
  • @Part     用于表单字段，适用于文件上传的情况，@Part支持三种类型：RequestBody、MultipartBody.Part、任意类型。
  • @PartMap   用于多文件上传， 与@FieldMap和@QueryMap的使用类似。

上面的使用是一个上传文字和文件的写法，在使用@Part注解时需要在头部添加@Multipart注解，实现支持文件上传，我们来看看怎么使用：

//声明类型,这里是文字类型
 MediaType textType = MediaType.parse("text/plain");
//根据声明的类型创建RequestBody,就是转化为RequestBody对象
RequestBody name = RequestBody.create(textType, "这里是你需要写入的文本：刘亦菲");

//创建文件，这里演示图片上传
File file = new File("文件路径");
if (!file.exists()) {
   file.mkdir();
 }

//将文件转化为RequestBody对象
//需要在表单中进行文件上传时，就需要使用该格式：multipart/form-data
RequestBody imgBody = RequestBody.create(MediaType.parse("image/png"), file);
//将文件转化为MultipartBody.Part
//第一个参数：上传文件的key；第二个参数：文件名；第三个参数：RequestBody对象
MultipartBody.Part filePart = MultipartBody.Part.createFormData("file", file.getName(), imgBody);

Call<ResponseBody> partDataCall = retrofit.create(Api.class).getPartData(name, filePart);
复制代码

首先声明类型，然后根据类型转化为RequestBody对象，返回RequestBody或者转化为 MultipartBody.Part，需要在表单中进行文件上传时，就需要使用该格式：multipart/form-data。

@PartMap的使用与@FieldMap和@QueryMap的使用类似，用于多文件上传，我们直接看代码：

 @Multipart
 @POST("user/followers")
 Call<ResponseBody> getPartMapData(@PartMap Map<String, MultipartBody.Part> map);

    File file1 = new File("文件路径");
    File file2 = new File("文件路径");
        if (!file1.exists()) {
        file1.mkdir();
    }
        if (!file2.exists()) {
        file2.mkdir();
    }

    RequestBody requestBody1 = RequestBody.create(MediaType.parse("image/png"), file1);
    RequestBody requestBody2 = RequestBody.create(MediaType.parse("image/png"), file2);
    MultipartBody.Part filePart1 = MultipartBody.Part.createFormData("file1", file1.getName(), requestBody1);
    MultipartBody.Part filePart2 = MultipartBody.Part.createFormData("file2", file2.getName(), requestBody2);

    Map<String,MultipartBody.Part> mapPart = new HashMap<>();
        mapPart.put("file1",filePart1);
        mapPart.put("file2",filePart2);

    Call<ResponseBody> partMapDataCall = retrofit.create(Api.class).getPartMapData(mapPart);

上面的(@PartMap Map<String, MultipartBody.Part> map)方法参数中的 MultipartBody.Part 可以是RequestBody、String、MultipartBody.Part等类型，可以根据个人需要更换，这里就不一一说明了。

参考了以下文章:

Retrofit2 实战（一、使用详解篇）

--个人学习笔记

avatar
文章
阅读
粉丝