Retrofit源码解析之概括总览

1 前言

首先，Retrofit是对OkHttp作了进一步的封装，网络请求的本质还是通过OkHttp来完成。

其次，Retrofit运用了大量的设计模式，使得整体框架显得整洁明了。其中通过适配器模式甚至可以直接兼容Rxjava。

2 注解

Retrofi的一大特色就是应用了大量的注解。这些注解可分为三大部分：

2.1 网络请求方法的注解

从get到options对应着HTTP中的网络请求方式，其中最常用的应该是@GET以及@POST这两个注解了。可以这样子比喻。TCP相当于高速公路，GET相当于送急件的汽车装载量小但速度快(把参数包含在URL中)，而POST相当于满载货物的大卡车但速度较慢(通过request body传递参数)。具体内容可参考https://www.cnblogs.com/logsharing/p/8448446.html。具体差别如下表所示：

这边在注解后面可以用网址作为参数。这边要提一下，retrofit把网络URL分为两个部分：Baseurl+注解跟的参数。具体例子如下所示：

// 第1部分：在网络请求接口的注解设置
 @GET("openapi.do")
Call<Translation>  getCall();

// 第2部分：在创建Retrofit实例时通过.baseUrl()设置
Retrofit retrofit = new Retrofit.Builder()
                .baseUrl("http://fanyi.youdao.com/")  .build();

//这边的话最终生成的url是 http://fanyi.youdao.com/openapi.do

当然还有其他方式。比如说当你拥有两个baseUrl的时候，你也可以在注解的参数里面写全路径。具体的整合规则如下所示：

当注解是@HTTP的时候，他是可以替换以上7种注解的功能：

/**
     * method：网络请求的方法（区分大小写）
     * path：网络请求地址路径
     * hasBody：是否有请求体
     */
    @HTTP(method = "GET", path = "blog/{id}", hasBody = false)
    Call<ResponseBody> getCall(@Path("id") int id);

2.2 网络请求接口的注解

@FormUrlEncoded和@Multipart都是用于表示发送form-encoded的数据，而Multipart用于有文件上传的场景。

具体可参考以下例子：

public interface Demo {
        /**
         *表明是一个表单格式的请求（Content-Type:application/x-www-form-urlencoded）
         * <code>Field("username")</code> 表示将后面的 <code>String name</code> 中name的取值作为 username 的值
         */
        @POST("/form")
        @FormUrlEncoded
        Call<ResponseBody> testFormUrlEncoded1(@Field("username") String name, @Field("age") int age);
         
        /**
         * {@link Part} 后面支持三种类型，{@link RequestBody}、{@link okhttp3.MultipartBody.Part} 、任意类型
         * 除 {@link okhttp3.MultipartBody.Part} 以外，其它类型都必须带上表单字段({@link okhttp3.MultipartBody.Part} 中已经包含了表单字段的信息)，
         */
        @POST("/form")
        @Multipart
        Call<ResponseBody> testFileUpload1(@Part("name") RequestBody name, @Part("age") RequestBody age, @Part MultipartBody.Part file);

}

2.3 请求参数的接口

@Headers和@Header两个的效果是一样的。Headers用于修饰请求方法所以它用于添加固定的请求 头而Header用于修饰请求参数所以它用于修饰不固定的请求头。如下所示：

// @Header
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

// @Headers
@Headers("Authorization: authorization")
@GET("user")
Call<User> getUser()

@Body用于非表单请求体，比如说json数据。如果提交的是Map，那么作用相当于 @Field。而且他要经过以下处理

FormBody.Builder builder = new FormBody.Builder();
builder.add("key","value");

@Field & @FieldMap 用于post提交表单数据：

public interface GetRequest_Interface {
        /**
         *表明是一个表单格式的请求（Content-Type:application/x-www-form-urlencoded）
         * <code>Field("username")</code> 表示将后面的 <code>String name</code> 中name的取值作为 username 的值
         */
        @POST("/form")
        @FormUrlEncoded
        Call<ResponseBody> testFormUrlEncoded1(@Field("username") String name, @Field("age") int age);

/**
         * Map的key作为表单的键
         */
        @POST("/form")
        @FormUrlEncoded
        Call<ResponseBody> testFormUrlEncoded2(@FieldMap Map<String, Object> map);

}

@Part & @PartMap

同样是post提交表单数据，但是他所携带的参数更加的丰富可用于提交文件的场景，与 @Multipart 注解配合使用。

public interface GetRequest_Interface {

        @POST("/form")
        @Multipart
        Call<ResponseBody> testFileUpload1(@Part("name") RequestBody name, @Part("age") RequestBody age, @Part MultipartBody.Part file);


        @POST("/form")
        @Multipart
        Call<ResponseBody> testFileUpload2(@PartMap Map<String, RequestBody> args, @Part MultipartBody.Part file);
}

 MediaType textType = MediaType.parse("text/plain");
        RequestBody name = RequestBody.create(textType, "Carson");
        RequestBody age = RequestBody.create(textType, "24");
        RequestBody file = RequestBody.create(MediaType.parse("application/octet-stream"), "这里是模拟文件的内容");

        // @Part
        MultipartBody.Part filePart = MultipartBody.Part.createFormData("file", "test.txt", file);
        Call<ResponseBody> call3 = service.testFileUpload1(name, age, filePart);
        ResponseBodyPrinter.printResponseBody(call3);

        // @PartMap
        // 实现和上面同样的效果
        Map<String, RequestBody> fileUpload2Args = new HashMap<>();
        fileUpload2Args.put("name", name);
        fileUpload2Args.put("age", age);
        Call<ResponseBody> call4 = service.testFileUpload2(fileUpload2Args, filePart); 
}

@Query和@QueryMap

用于@GET方法的查询参数，如下例子所示：

@GET("/")    
 Call<String> cate(@Query("cate") String cate);

cate("test")
//以上相当于baseurl+/？cate=test

@Path和@Url

Path用于动态替换注解中的URL的缺省值，而Url则可以动态替换整个注解中的URL

@GET("users/{user}/repos")
Call<ResponseBody>  getBlog（@Path("user") String user ）;
        
 @GET
  Call<ResponseBody> testUrlAndQuery(@Url String url, @Query("showAll") boolean showAll);

3 Retrofit的基本使用

第一步是创建Retrofit实例，它采用建造者模式来构建。

 Retrofit retrofit = new Retrofit.Builder()
                .baseUrl("http://fanyi.youdao.com/") // 设置网络请求的Url地址
                .addConverterFactory(GsonConverterFactory.create()) // 设置数据解析器
                .addCallAdapterFactory(RxJavaCallAdapterFactory.create()) // 支持RxJava平台
                .build();

其中有两个工厂。addConverterFactory用于添加数据转换平台而addCallAdapterFactory用于适配不同的调用框架。他们所兼容的不同框架如下所示：

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
Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

网络请求适配器	Gradle依赖
guava	com.squareup.retrofit2:adapter-guava:2.0.2
Java8	com.squareup.retrofit2:adapter-java8:2.0.2
rxjava	com.squareup.retrofit2:adapter-rxjava:2.0.2

第二步是创建请求接口

interface GithubService {
    //通过注解定义请求的方法以及路径，“{}”里面的表示：该内容是可变的，通过下面方法的参数赋值
    @POST("/xx/xx")
    Observable<JsonObject> getCall();
}

第三步创建网络请求对象，里面实现了第二步中的接口

 // 创建 网络请求接口 的实例
 GithubService request = retrofit.create(GithubService.class);

第四步就是处理返回的数据结果,这边使用的Rxjava所以可以使用相关方法来接收数据。

request.getCall()
    	.retry(3)
    	.onTerminateDetach()//当执行了反注册 unsubscribes 或者发送数据序列中断了则解除订阅
                .subscribeOn(Schedulers.io())
                .observeOn(AndroidSchedulers.mainThread())
                .subscribe(jsonObject -> {
		//dosomething
                }, throwable -> {
                    //dosomething
                });

这四步之后你就可以开始请求数据以及处理返回的数据了。

4 结语

retrofit更像是一个平台，就好比是电脑的机箱。他将各种电脑元件有机的组合起来，可以方便的升级替换。