Retrofit教程之【入门篇】

Retrofit已经出了好久了，现在才开始研究，真的是太落后了我，废话不多说了，直接进入主题。

我将由三篇文章来介绍Retrofit的使用以及源码，架构设计方面。如果想直接跳过可以直接传送：

1. Retrofit教程之【新手入门】篇
2. Retrofit教程之【深入源码】篇
3. 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);

注意：

1. 声明的Header不会互相覆盖。所有的Header有这一样的名字都会被添加到请求里。
2. 一个请求的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. 总结

1. Retrofit是基于RESTfull的网络请求框架，底层是使用OKHttpClient完成网络请求；
2. 采用注解式+Java接口式声明请求及参数；
3. 支持异步及同步；
4. 支持数据解析器Converter并且支持自定义；