Retrofit的基本使用手册

Retrofit使用手册😸

Retrofit简介

A type-safe HTTP client for Android and Java。封装了OkHttp，也是由square公司开发的一个处理网络请求的开源项目。

Retrofit基础使用方法

跟OkHttp一样先将依赖包添加到build.gradle里面，这里有一点需要注意，因为retrofit封装了OkHttp所以我们将retrofit依赖包添加到AS中OkHttp的依赖包也会被一起添加到AS中，Retrofit的依赖包如下：

dependencies{
	implementation 'com.squareup.retrofit2:retrofit:2.9.0'
		...
}

第一步

我们需要先根据接口创建Java接口：

如下根据接口要求我们的接口需要向服务器提交username，password，我们在AS中用retrofit的方法实现：

public interface HttpbinService {
	
	@POST("post") //post 注解 括号内代表我们要请求的接口类型，表明这个方法会用post方法请求
	@FormUrlEncoded //注解 post 提交方式
    //post 方法
	Call<ResponseBody> post(@Field("user") String username,@Field("passwd") String pwd); //@Field 注解 括号内容表示我们提交参数的名字
	
	@GET("get")
    //get 方法
	Call<ResponseBody> get(@Query("user") String username,@Query("passwd") String pwd); //一般get请求我们用 @Query 注解 而post请求用 @Field
}

注意事项：我们补全代码自动导包时我们需要注意retrofit包和okhttp包，不要导错包

第二步

创建Retrofit对象，并生成接口实现类对象：

retrofit = new Retrofit.Builder().baseUrl("https://www.httpbin.org/").build();
httpbinService = retrofit.create(HttpbinService.class);

这里我将Retrofit对象和HttpbinService都设定为全局变量，方便后续使用

随后我们需要生成对应的方法来实现Retrofit，代码如下：

retrofit2.Call<ResponseBody> call = httpbinService.post("abc","123456"); //括号内为先前创建的接口里面的user值和passwd值
call.enqueue(new Callback<ResponseBody>(){
 			@Override
            public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {

                try {
                    Log.i("abc", "onResponse: "+ response.body().string());
                } catch (IOException e) {
                    e.printStackTrace();
                }
            }

            @Override
            public void onFailure(Call<ResponseBody> call, Throwable t) {

            }
        });
}

我们直观对比一下okhttp和retrofit的代码量

OkHttp：

Retrofit：

明显Retrofit的代码量较少，但这是不包含接口的，我们okhttp的提交内容是在方法里直接写出，而retrofit是在接口里面写出

那么这样有什么好处？接口的方式便于我们管理代码，会使单码简洁方便后续的调试，其次如果我们有很多的登录请求要完成用okhttp的话我们每个请求就需要写一次表单，但用接口的话我们只需要一个，这样代码量大幅度减少。

Retrofit中的注解

Retrofit的注解：

• 方法注解：@GET, @POST, @PUT, @DELETE, @PATH, @HEAD, @OPTIONS, @HTTP
• 标记注解：@FormUrlEncoded, @Multipart, @Streaming
• 参数注解：@Query, @QueryMap, @Body, @Field, @FieldMap, @Part, @PartMap
• 其他注解：@Path, @Header, @Headers, @Url

方法注解就是我们的请求方式，像GET请求和POST请求

标记注解就是我们提交下载有关的注解

参数注解顾名思义就是我们设置参数时要用到的注解

各各注解的含义如下

1.1 Body注解:

• 作用于方法的参数
• 使用该注解定义的参数不可为null
• 当你发送一个post或put请求,但是又不想作为请求参数或表单的方式发送请求时,使用该注解定义的参数可以直接传入一个实体类,retrofit会通过convert把该实体序列化并将序列化后的结果直接作为请求体发送出去.

---

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=张三.

---

1.4 FieldMap注解:

• 作用于方法的参数
• 用于发送一个表单请求
• map中每一项的键和值都不能为空,否则抛出IllegalArgumentException异常

---

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的值到请求头中.
• 具有相同名称的请求头不会相互覆盖,而是会照样添加到请求头中

---

1.9 HeaderMap注解:

• 作用于方法的参数,用于添加请求头
• 以map的方式添加多个请求头,map中的key为请求头的名称,value为请求头的值,且value使用String.valueOf()统一转换为String类型,
• map中每一项的键和值都不能为空,否则抛出IllegalArgumentException异常

---

2.0 Headers注解:

• 作用于方法,用于添加一个或多个请求头
• 具有相同名称的请求头不会相互覆盖,而是会照样添加到请求头中

---

2.1 HTTP注解:

• 作用于方法,用于发送一个自定义的HTTP请求

---

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）。

---

2.4 PartMap注解:

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

---

2.5 OPTIONS注解:

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

---

2.6 PATCH注解:

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

---

2.7 Path注解:

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

---

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=王五.

---

3.1 QueryMap注解:

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

---

3.2 Streaming注解:

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

---

3.3 Url注解:

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

---