Retrofit源码解读

1 简介

提供给使用者的接口类：Retrofit

Retrofit用注解的方式为HTTP接口适配了带有回调的java接口，通过这些java接口可以实现HTTP请求。

本文Retrofit版本：2.6.0

2 Retrofit组成：

image

2.1 Builder: Retrofit构建器（Builder模式）

作用：在保证Retrofit有默认组件的情况下，方便使用者自定义相关Retrofit组件。

小细节Platform：
Builder也可以配置Platform，默认情况下，Bulder会自动获取对应的平台。

  private static Platform findPlatform() {
    try {
      Class.forName("android.os.Build");
      if (Build.VERSION.SDK_INT != 0) {
        return new Android();
      }
    } catch (ClassNotFoundException ignored) {
    }
    try {
      Class.forName("java.util.Optional");
      return new Java8();
    } catch (ClassNotFoundException ignored) {
    }
    return new Platform();
  }

可以看到有三个平台，Android（继承Platform）,Java8（继承Platform）和Platform自己。

下面再看三个平台区别：

2.1.1 Platform

Platform平台应该是用来支持java8版本之下的java平台。

class Platform {
    ...
    // 平台无回调执行器，应该在哪里创建的，就在哪里回调
  Executor defaultCallbackExecutor() {
    return null;
  }
  // 平台默认的回调适配器工厂列表为new DefaultCallAdapterFactory(callbackExecutor)
  List defaultCallAdapterFactories(
      @Nullable Executor callbackExecutor) {
    return singletonList(new DefaultCallAdapterFactory(callbackExecutor));
  }
  // 默认回调适配器工厂数量为1
    int defaultCallAdapterFactoriesSize() {
    return 1;
  }
  // 默认的转换器工厂列表为空列表
    List defaultConverterFactories() {
    return emptyList();
  }
  // 是否是默认方法
    boolean isDefaultMethod(Method method) {
    return false;
  }
  // 调用指定类默认的方法会抛异常，即不支持调用非默认方法
 @Nullable Object invokeDefaultMethod(Method method, Class declaringClass, Object object,
      @Nullable Object... args) throws Throwable {
    throw new UnsupportedOperationException();
  }
    ...
    
}

• isDefaultMethod()返回false，表示传入的Method都告知不是默认方法（默认方法是一种公共的非抽象实例方法，即带有主体的非静态方法，在接口中声明）
• invokeDefaultMethod返回异常，表示调用非默认方法不支持

2.1.2 Android

static class Android extends Platform {
    // 平台默认的回调执行器 可以看出默认的回调线程是UI线程，所以使用者不用在回调里做线程切换
    @Override public Executor defaultCallbackExecutor() {
      return new MainThreadExecutor();
    }
    // 是否是默认方法
    @Override boolean isDefaultMethod(Method method) {
    // 如果安卓构建版本小于24（安卓7.0），则直接返回是非默认方法，否则正常返回method.isDefault()
      if (Build.VERSION.SDK_INT < 24) {
        return false;
      }
      return method.isDefault();
    }
    //回调执行器必须不为空，回调适配器工厂列表版本小于Android7返回new DefaultCallAdapterFactory(callbackExecutor)单独组成的不可变list，否则返回CompletableFutureCallAdapterFactory.INSTANCE和DefaultCallAdapterFactory(callbackExecutor)组成的不可变list
    @Override List defaultCallAdapterFactories(
        @Nullable Executor callbackExecutor) {
      if (callbackExecutor == null) throw new AssertionError();
      DefaultCallAdapterFactory executorFactory = new DefaultCallAdapterFactory(callbackExecutor);
      // CompletableFutureCallAdapterFactory是支持CompletableFutureCall，是java8特性
      return Build.VERSION.SDK_INT >= 24
        ? asList(CompletableFutureCallAdapterFactory.INSTANCE, executorFactory)
        : singletonList(executorFactory);
    }
    // 默认的回调适配器工程个数，和defaultCallAdapterFactories对应
    @Override int defaultCallAdapterFactoriesSize() {
      return Build.VERSION.SDK_INT >= 24 ? 2 : 1;
    }
    // 默认的转换器工厂
    @Override List defaultConverterFactories() {
    // 如果平台支持java8，则让Converter支持java8操作符
      return Build.VERSION.SDK_INT >= 24
          ? singletonList(OptionalConverterFactory.INSTANCE)
          : Collections.emptyList();
    }
    // 默认转换器工厂个数
    @Override int defaultConverterFactoriesSize() {
      return Build.VERSION.SDK_INT >= 24 ? 1 : 0;
    }

    //安卓平台的主线程执行器
    static class MainThreadExecutor implements Executor {
      private final Handler handler = new Handler(Looper.getMainLooper());

      @Override public void execute(Runnable r) {
        handler.post(r);
      }
    }
  }

Android有默认的MainThreadExecutor，就是Android主线程任务执行器，默认的CallAdapter.Factory任务回调适配器工厂。

从这里就可以看出Android平台上，Retrofit执行任务默认是在主线程。

2.1.3 java8

  static class Java8 extends Platform {
  // 默认method.isDefault()
    @Override boolean isDefaultMethod(Method method) {
      return method.isDefault();
    }
    // 支持调用默认方法
    @Override Object invokeDefaultMethod(Method method, Class declaringClass, Object object,
        @Nullable Object... args) throws Throwable {
      // Because the service interface might not be public, we need to use a MethodHandle lookup
      // that ignores the visibility of the declaringClass.
      Constructor constructor = Lookup.class.getDeclaredConstructor(Class.class, int.class);
      constructor.setAccessible(true);
      return constructor.newInstance(declaringClass, -1 /* trusted */)
          .unreflectSpecial(method, declaringClass)
          .bindTo(object)
          .invokeWithArguments(args);
    }
    // 默认适配器工厂列表，和Android差不多
    @Override List defaultCallAdapterFactories(
        @Nullable Executor callbackExecutor) {
      List factories = new ArrayList<>(2);
      factories.add(CompletableFutureCallAdapterFactory.INSTANCE);
      factories.add(new DefaultCallAdapterFactory(callbackExecutor));
      return unmodifiableList(factories);
    }
    // 默认适配器工厂个数
     @Override int defaultCallAdapterFactoriesSize() {
      return 2;
    }
    // 默认转换器工厂列表
    @Override List defaultConverterFactories() {
      return singletonList(OptionalConverterFactory.INSTANCE);
    }
    // 默认转换器工厂个数
    @Override int defaultConverterFactoriesSize() {
      return 1;
    }
  }

• isDefaultMethod():返回method.isDefault()
• invokeDefaultMethod()：调用非默认方法接口。

总结一下：

平台	默认回调执行器	默认回调适配器工厂	默认转换器工厂	判断methos是默认方法	Object invokeDefaultMethod()
Platform	无	DefaultCallAdapterFactory(callbackExecutor)	无	false	不支持
Java8	无	DefaultCallAdapterFactory(callbackExecutor)和CompletableFutureCallAdapterFactory.INSTANCE	OptionalConverterFactory.INSTANCE	method.isDefault()	支持
Android	MainThreadExecutor	一个DefaultCallAdapterFactory(callbackExecutor)或者DefaultCallAdapterFactory(callbackExecutor)和CompletableFutureCallAdapterFactory.INSTANCE	OptionalConverterFactory.INSTANCE	SDK_INT< 24 ? false:method.isDefault()	不支持

2.2 合成Retrofit的组件：

Retrofit是一个门面，这个门面通过组合各种组件来为使用者提供API。以下就是合成Retrofit的必要组件：

• callFactory:okhttp3.Call.Factory 生成（HTTP调用对象）的工厂
• baseUrl:HttpUrl HTTP url相关
• converterFactories:List
• adapterFactories:List
• callbackExecutor: Executor
• validateEagerly: boolean

2.2.1 okhttp3.Call.Factory

http调用（call）工厂，就是生产http调用对象的工厂

可以看看okhttp3.Call接口

// 表示单个请求/响应，不能执行两次，它是可以取消的。
public interface Call extends Cloneable {
  // 返回发起请求回调的Request
  Request request();
  // 同步执行
  Response execute() throws IOException;
 //  异步执行
  void enqueue(Callback responseCallback);
 // 取消    
  void cancel();
  // 是否已执行
  boolean isExecuted();
 // 是否已取消
  boolean isCanceled();
    // 克隆方法
  Call clone();

// 工厂接口
  interface Factory {
  // 工厂方法
    Call newCall(Request request);
  }
}

image

如果你使用过OkHttp3，会发现这就是OkHttp3常用的外部接口。所以OkHttpClient就是它的一个实现。所以Retrofit框架里没有自己扩展Call.Factory，那么默认工厂就是用的OkHttp3框架里实现的OkHttpClient。

okhttp3.Call.Factory callFactory = this.callFactory;
      if (callFactory == null) {
        callFactory = new OkHttpClient();
      }

上面取自Retrofit.Builder.build()里的代码，可以看到如果用户没有指定自定义的okhttp3.Call.Factory，那么默认就是用OkHttpClient。

2.2.2 baseUrl:HttpUrl

image

HttpUrl对象可通过HttpUrl.Build对象的parse()方法构造。HttpUrl包含一个Http Url的组成信息，比如域名，端口，用户名，密码等都可以设置。

HttpUrl就是Retrofit的基地址，它可以通过HttpUrl.parse(String baseUrl)的匹配校验生成一个HttpUrl对象。

例：

 /**
     * Set the API base URL.
     *
     * @see #baseUrl(HttpUrl)
     */
    public Builder baseUrl(String baseUrl) {
      checkNotNull(baseUrl, "baseUrl == null");
      return baseUrl(HttpUrl.get(baseUrl));
    }
    
    public Builder baseUrl(HttpUrl baseUrl) {
      checkNotNull(baseUrl, "baseUrl == null");
      List pathSegments = baseUrl.pathSegments();
      if (!"".equals(pathSegments.get(pathSegments.size() - 1))) {
        throw new IllegalArgumentException("baseUrl must end in /: " + baseUrl);
      }
      this.baseUrl = baseUrl;
      return this;
    }

上面取自Retrofit.Builder.build()里的代码，可以得知我们通常set的地址，最后会转化成一个HttpUrl对象。

2.2.3 converterFactories:List

Converter是从一个对象转为另一种对象过程的抽象，简明一点就叫转换器。比如说你总要把用户的请求信息转为OkHttp标准的请求结构(Request)，或者是OkHttp的标准响应信息(Response)转为用户数据。

把它抽象为一个接口，接口里就有一个convert方法

public interface Converter {
    // T是目标类型，F是原始类型
  T convert(F value) throws IOException;
  }

然而Converter又可以是多种多样的，这样就最好是用工厂类来生产：

  abstract class Factory {
    // 生产responseBody转换器
    public @Nullable Converter responseBodyConverter(Type type,
        Annotation[] annotations, Retrofit retrofit) {
      return null;
    }
    // 目标为RequestBody的转换器 type为原始类型的type,parameterAnnotations为参数上的注解（因为支持Body,Part,PartMap注解），methodAnnotations为方法注解，retrofit是门面
    public @Nullable Converter requestBodyConverter(Type type,
        Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {
      return null;
    }
    // 生产目标为String类型的转换器
    public @Nullable Converter stringConverter(Type type, Annotation[] annotations,
        Retrofit retrofit) {
      return null;
    }
    // 泛型参数type的指定位置参数的上限，比如Map这个type索引位置0参数的type的上限为String，1为Long
    protected static Type getParameterUpperBound(int index, ParameterizedType type) {
      return Utils.getParameterUpperBound(index, type);
    }
    // 一般用于获取泛型参数前的type，比如List会返回List.class
    protected static Class getRawType(Type type) {
      return Utils.getRawType(type);
    }
  }

想要转换肯定要知道原始类型和目标类型，所以可以从生成方法中的参数

Retrofit库已经为我们实现了很多Converter,如下图:

image

常用的GsonConverterFactory实现:

public final class GsonConverterFactory extends Converter.Factory {
    // 实例化一个GsonConverterFactory
    public static GsonConverterFactory create() {
    return create(new Gson());
  }
  
    public static GsonConverterFactory create(Gson gson) {
    if (gson == null) throw new NullPointerException("gson == null");
    return new GsonConverterFactory(gson);
  }
  
    private final Gson gson;
    // 构造方法
    private GsonConverterFactory(Gson gson) {
    this.gson = gson;
  }
  // 把ResponseBody转为指定类型对象
  @Override
  public Converter responseBodyConverter(Type type, Annotation[] annotations,
      Retrofit retrofit) {
    TypeAdapter adapter = gson.getAdapter(TypeToken.get(type));
    return new GsonResponseBodyConverter<>(gson, adapter);
  }
  // 把指定类型转为RequestBody
  @Override
  public Converter requestBodyConverter(Type type,
      Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {
    TypeAdapter adapter = gson.getAdapter(TypeToken.get(type));
    return new GsonRequestBodyConverter<>(gson, adapter);
  }
  
}

Gson是怎么解析的？

GsonRequestBodyConverter类里:

// 这里实际也就是把对象转为Json字符串写入到RequestBody里而已。
@Override public RequestBody convert(T value) throws IOException {
    Buffer buffer = new Buffer();
    Writer writer = new OutputStreamWriter(buffer.outputStream(), UTF_8);
    JsonWriter jsonWriter = gson.newJsonWriter(writer);
    adapter.write(jsonWriter, value);
    jsonWriter.close();
    return RequestBody.create(MEDIA_TYPE, buffer.readByteString());
  }

使用Gson的jsonWriter配合TypeAdapter写入Buffer,然后构造RequestBody。

GsonResponseBodyConverter类里：

final class GsonResponseBodyConverter implements Converter {
  private final Gson gson;
  private final TypeAdapter adapter;

  GsonResponseBodyConverter(Gson gson, TypeAdapter adapter) {
    this.gson = gson;
    this.adapter = adapter;
  }
    // 就是把body里面的Json字符串读出来然后转为指定类型的对象
  @Override public T convert(ResponseBody value) throws IOException {
    JsonReader jsonReader = gson.newJsonReader(value.charStream());
    try {
      T result = adapter.read(jsonReader);
      if (jsonReader.peek() != JsonToken.END_DOCUMENT) {
        throw new JsonIOException("JSON document was not fully consumed.");
      }
      return result;
    } finally {
      value.close();
    }
  }
}

2.2.4 adapterFactories:List 适配器工厂

功能：将默认的网络请求执行器（OkHttpCall）转换成适合被不同平台来调用的网络请求执行器形式，相当于返回一个代理。

CallAdapter.java

// R为原始响应Java对象类型，T为目标响应类型
public interface CallAdapter {
    // 返回想要响应转成的Java对象类型
    Type responseType();
    // 返回一个call的代理
    T adapt(Call call);
}

对应的工厂类：其实跟前面的转换器差不多

abstract class Factory {
    // 返回一个回调适配器
    public abstract @Nullable CallAdapter get(Type returnType, Annotation[] annotations,
        Retrofit retrofit);
    // 获取容器指定索引位置的存放值类型
    protected static Type getParameterUpperBound(int index, ParameterizedType type) {
      return Utils.getParameterUpperBound(index, type);
    }
    // 获取原始Class
    protected static Class getRawType(Type type) {
      return Utils.getRawType(type);
    }
  }
}

同样的Retrofit也为我们实现了几个现成的适配器工厂

image

DefaultCallAdapterFactory 默认的Call适配器工厂

重写get():

 @Override public @Nullable CallAdapter get(
      Type returnType, Annotation[] annotations, Retrofit retrofit) {
      // 若返回类型Type不是Call.class，返回适配器null
    if (getRawType(returnType) != Call.class) {
      return null;
    }
    // 返回类型Type必须为带泛型参数的Type
    if (!(returnType instanceof ParameterizedType)) {
      throw new IllegalArgumentException(
          "Call return type must be parameterized as Call or Call");
    }
    // 取得返回类型的泛型参数第一个参数的Type实例
    final Type responseType = Utils.getParameterUpperBound(0, (ParameterizedType) returnType);
    // 获取回调执行器
    final Executor executor = Utils.isAnnotationPresent(annotations, SkipCallbackExecutor.class)
        ? null
        : callbackExecutor;

    return new CallAdapter>() {
      @Override public Type responseType() {
      // 适配器适配的类型Type
        return responseType;
      }

      @Override public Call