Retrofit教程之【入门篇】
Retrofit已经出了好久了,现在才开始研究,真的是太落后了我,废话不多说了,直接进入主题。
我将由三篇文章来介绍Retrofit的使用以及源码,架构设计方面。如果想直接跳过可以直接传送:
- Retrofit教程之【新手入门】篇
- Retrofit教程之【深入源码】篇
- Retrofit教程之【设计模式】篇
1. 介绍
还不了解Retrofit的可以先去 Retrofit官网 瞧瞧。
Retrofit是采用 RESTfull 的HTTP网络请求框架,内部是基于OkHttpClient的源码进行封装的。
相比较于传统的网络框架,其本质没有区别,只是将网络请求过程的每一步都进行非常缜密的设计并对其封装,这里面涉及了很多设计模式,把网络请求实现真正的解耦,真可谓是把设计模式运用到了极致。
首先在使用之前,需要将Retrofit依赖到项目里:
dependencies {
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
}
需要注意的是:Retrofit requires at minimum Java 8+ or Android API 21+.
接下来让我们来看看使用Retrofit创建一个网络请求需要分几步:
2. 使用
2.1 声明接口式API
public interface GitHubService {
@GET("users/{user}/repos")
Call<List<Repo>> listRepos(@Path("user") String user);
}
2.2 创建Retrofit对象
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.build();
2.3 创建接口实现
GitHubService service = retrofit.create(GitHubService.class);
2.4 调用Call对象发起网络请求
Call<List<Repo>> repos = service.listRepos("octocat");
repos.enqueue(new Callback<List<Repo>>() {
@Override
public void onResponse(Call<List<Repo>> call, Response<List<Repo>> response) {
//成功
}
@Override
public void onFailure(Call<List<Repo>> call, Throwable t) {
//失败
}
});
3. API详细使用
3.1 请求方法
发起一个Get请求只需要在方法上声明@Get注解,另外还支持HTTP, POST, PUT, PATCH, DELETE, OPTIONS、 HEAD。
3.2 URL自定义
我们可以采用 {id}的方式将参数替换到url里面。例如下面:
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);
Query的参数也可以这样用:
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);
稍微复杂的参数可以使用@QueryMap:
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);
3.3 带body的请求
我们也以注解的方式声明一个带具体实体的请求,例如下面:
@POST("users/new")
Call<User> createUser(@Body User user);
3.4 表单加密和多种请求体
使用@FormUrlEncoded注解来提交表单,表单的数据对应的是在方法参数里面声明的@Field字段,key对应的@Field("first_name"),value就是具体的first字符串内容。
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first,
@Field("last_name") String last);
带有多类型的请求可以使用@Multipart注解字段来声明,例如:
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
3.5 Header定制化
Header的声明可以直接在方法上使用@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可以利用@Header注解动态的更改;
另外需要把Header添加到每个请求里可以使用OkHttp的BridgeInterceptor来实现。
4. 配置Retrofit
Retrofit是将你的API请求转换成Call对象。所以,Retrofit会给你默认的配置,也允许你自己定制。
Converters(数据转换器)
Converters是在一开始创建Retrofit对象时进行配置的。
Converter的作用就是在数据返回的时候,对数据进行对应格式的转换,减少了我们在拿到数据的时候进行自定义解析时候的麻烦以及bug;
Retrofit retrofit = new Retrofit.Builder()
.baseUrl(BASE_URL)
.addConverterFactory(GsonConverterFactory.create())
.build();
GsonConverterFactory是继承自Converter.Factory
public interface Converter<F, T> {
@Nullable
T convert(F value) throws IOException;
abstract class Factory {
public @Nullable Converter<ResponseBody, ?> responseBodyConverter(
Type type, Annotation[] annotations, Retrofit retrofit) {
return null;
}
//...
}
Retrofit不仅支持Gson,还支持
-
Gson:
com.squareup.retrofit2:converter-gson
-
Jackson:
com.squareup.retrofit2:converter-jackson
-
Moshi:
com.squareup.retrofit2:converter-moshi
-
Protobuf:
com.squareup.retrofit2:converter-protobuf
-
Wire:
com.squareup.retrofit2:converter-wire
-
Simple XML:
com.squareup.retrofit2:converter-simplexml
-
JAXB:
com.squareup.retrofit2:converter-jaxb
- Scalars (primitives, boxed, and String):
com.squareup.retrofit2:converter-scalars
当然,我们也可以自定义Converter。
5. 总结
- Retrofit是基于RESTfull的网络请求框架,底层是使用OKHttpClient完成网络请求;
- 采用注解式+Java接口式声明请求及参数;
- 支持异步及同步;
- 支持数据解析器Converter并且支持自定义;