Retrofit的基本使用

此文章分析的Retrofit是基于Retrofit2.6.0版本。Gradle依赖如下：

implementation 'com.squareup.retrofit2:retrofit:2.6.0'

Retrofit使用步骤

//创建Retrofit对象
val retrofit = Retrofit.Builder()
    .addConverterFactory(GsonConverterFactory.create())////设置数据解析器为GSON
    //.addCallAdapterFactory(RxJava2CallAdapterFactory.create())//返回的结果通过RxJava处理
    .baseUrl("http://xxx")
    .build()
//2.创建网络接口实例
val apiService = retrofit.create(ApiService::class.java)
//3.进行网络请求,得到数据
apiService.getHomeData()

创建Retrofit对象

我们可以看到创建Retrofit对象是通过Build构建者模式来创建的，我们看下源码

    Builder(Platform platform) {
      this.platform = platform;
    }

    public Builder() {
      this(Platform.get());
    }

Builder需要传入一个Platfrom，我们接下来看下Platform

class Platform {
  private static final Platform PLATFORM = findPlatform();

  static Platform get() {
    return PLATFORM;
  }

  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();
  }
  ...
  static class Android extends Platform {
    ...
  }
  static class Java8 extends Platform {
    ...
  }
}

我们可以看到Platform的findPlatform方法会帮忙匹配到对应的平台，目前支持的平台有Android和Java8。
Platform中的defaultCallbackExecutor提供了我们异步回调的线程切换。我们看Android平台的Platform。

  static class Android extends Platform {
    //因为Java8中接口中新增了默认方法，这个是健壮性判断
    @Override boolean isDefaultMethod(Method method) {
      if (Build.VERSION.SDK_INT < 24) {
        return false;
      }
      return method.isDefault();
    }
    //返回的Executor实际是运行在主线程的，后面收到返回结果用于线程切换
    @Override public Executor defaultCallbackExecutor() {
      return new MainThreadExecutor();
    }

    @Override List<? extends CallAdapter.Factory> defaultCallAdapterFactories(
        @Nullable Executor callbackExecutor) {
      if (callbackExecutor == null) throw new AssertionError();
      DefaultCallAdapterFactory executorFactory = new DefaultCallAdapterFactory(callbackExecutor);
      return Build.VERSION.SDK_INT >= 24
        ? asList(CompletableFutureCallAdapterFactory.INSTANCE, executorFactory)
        : singletonList(executorFactory);
    }

    @Override int defaultCallAdapterFactoriesSize() {
      return Build.VERSION.SDK_INT >= 24 ? 2 : 1;
    }

    @Override List<? extends Converter.Factory> defaultConverterFactories() {
      return Build.VERSION.SDK_INT >= 24
          ? singletonList(OptionalConverterFactory.INSTANCE)
          : Collections.<Converter.Factory>emptyList();
    }

    @Override int defaultConverterFactoriesSize() {
      return Build.VERSION.SDK_INT >= 24 ? 1 : 0;
    }
    //封装的Executor用于线程线程切换
    static class MainThreadExecutor implements Executor {
      private final Handler handler = new Handler(Looper.getMainLooper());//获得主线程的Looper

      @Override public void execute(Runnable r) {
        handler.post(r);//Runnable将在主线程运行
      }
    }
  }

我们继续分析build方法

public Retrofit build() {
    //验证参数的合法性，如果我们没有传baseUrl则会抛出异常，baseUrl是必传字段
    if (baseUrl == null) {
      throw new IllegalStateException("Base URL required.");
    }
    //Retrofit是对okHttp的封装，真正的网络请求还是OkHttp
    okhttp3.Call.Factory callFactory = this.callFactory;
    if (callFactory == null) {
      callFactory = new OkHttpClient();//如果我们没有传入OkHttp，则new出来
    }
    //用于对Respone结果处理的Executor，主要作用是线程切换
    Executor callbackExecutor = this.callbackExecutor;
    if (callbackExecutor == null) {
      //callbackExecutor我们没有传入的则采用Platform中提供的Executor，在Android平台其实就是MainThreadExecutor
      callbackExecutor = platform.defaultCallbackExecutor();
    }
    //添加callAdapterFactories到集合中，先添加我们传入的，再添加默认的defaultCallAdapterFactories
    List<CallAdapter.Factory> callAdapterFactories = new ArrayList<>(this.callAdapterFactories);
    callAdapterFactories.addAll(platform.defaultCallAdapterFactories(callbackExecutor));
    //添加converterFactories，先添加内置的，再添加我们传入的，最后添加默认的
    List<Converter.Factory> converterFactories = new ArrayList<>(
        1 + this.converterFactories.size() + platform.defaultConverterFactoriesSize());
    converterFactories.add(new BuiltInConverters());
    converterFactories.addAll(this.converterFactories);
    converterFactories.addAll(platform.defaultConverterFactories());

    return new Retrofit(callFactory, baseUrl, unmodifiableList(converterFactories),
        unmodifiableList(callAdapterFactories), callbackExecutor, validateEagerly);
}

创建网络接口实例

  public <T> T create(final Class<T> service) {
    //验证接口的合法性
    Utils.validateServiceInterface(service);
    //提前检测方法的合法性
    if (validateEagerly) {
      eagerlyValidateMethods(service);
    }
    return (T) Proxy.newProxyInstance(service.getClassLoader(), new Class<?>[] { service },
        new InvocationHandler() {
          private final Platform platform = Platform.get();
          private final Object[] emptyArgs = new Object[0];

          @Override public @Nullable Object invoke(Object proxy, Method method,
              @Nullable Object[] args) throws Throwable {
            // 如果是Object的方法则直接调用不做处理
            if (method.getDeclaringClass() == Object.class) {
              return method.invoke(this, args);
            }
            //如果是java8中接口的默认方法，则直接调用不做处理
            if (platform.isDefaultMethod(method)) {
              return platform.invokeDefaultMethod(method, service, proxy, args);
            }
            return loadServiceMethod(method).invoke(args != null ? args : emptyArgs);
          }
        });
  }
  //验证接口的合法性，此接口不允许继承其他的接口
  static <T> void validateServiceInterface(Class<T> service) {
    if (!service.isInterface()) {
      throw new IllegalArgumentException("API declarations must be interfaces.");
    }
    if (service.getInterfaces().length > 0) {
      throw new IllegalArgumentException("API interfaces must not extend other interfaces.");
    }
  }

create的核心是通过动态代理返回一个接口的实例，这段代码的核心是loadServiceMethod(method)，下面我们看下这个代码：

  ServiceMethod<?> loadServiceMethod(Method method) {
    //如果缓存中有则直接取缓存，否则创建
    ServiceMethod<?> result = serviceMethodCache.get(method);
    if (result != null) return result;
    //加锁
    synchronized (serviceMethodCache) {
      result = serviceMethodCache.get(method);
      if (result == null) {
        //根据method得到对应的ServiceMethod，并加入缓存
        result = ServiceMethod.parseAnnotations(this, method);
        serviceMethodCache.put(method, result);
      }
    }
    return result;
  }

ServiceMethod是缓存到了一个Map中，首先会通过Map获取其实例，如果Map中有其实例，就直接返回，否者创建一个缓存到Map中，然后返回
我们可以看到创建代码ServiceMethod的核心是ServiceMethod#parseAnnotations，我们继续分析这个方法

  static <T> ServiceMethod<T> parseAnnotations(Retrofit retrofit, Method method) {
    RequestFactory requestFactory = RequestFactory.parseAnnotations(retrofit, method);
    ...
    return HttpServiceMethod.parseAnnotations(retrofit, method, requestFactory);
  }

最后调用的是HttpServiceMethod#parseAnnotations

  static <ResponseT, ReturnT> HttpServiceMethod<ResponseT, ReturnT> parseAnnotations(
      Retrofit retrofit, Method method, RequestFactory requestFactory) {
    boolean isKotlinSuspendFunction = requestFactory.isKotlinSuspendFunction;
    boolean continuationWantsResponse = false;
    boolean continuationBodyNullable = false;

    Annotation[] annotations = method.getAnnotations();
    Type adapterType;
    if (isKotlinSuspendFunction) {
      Type[] parameterTypes = method.getGenericParameterTypes();
      Type responseType = Utils.getParameterLowerBound(0,(ParameterizedType) parameterTypes[parameterTypes.length - 1]);
      if (getRawType(responseType) == Response.class && responseType instanceof ParameterizedType) {
        responseType = Utils.getParameterUpperBound(0, (ParameterizedType) responseType);
        continuationWantsResponse = true;
      } else {
      }
      adapterType = new Utils.ParameterizedTypeImpl(null, Call.class, responseType);
      annotations = SkipCallbackExecutorImpl.ensurePresent(annotations);
    } else {
      adapterType = method.getGenericReturnType();
    }
    //从callAdapterFactories中找到合适的CallAdapter
    CallAdapter<ResponseT, ReturnT> callAdapter = createCallAdapter(retrofit, method, adapterType, annotations);
    Type responseType = callAdapter.responseType();
    //验证responseType的合法性
    if (responseType == okhttp3.Response.class) {
      throw methodError(method, "'"
          + getRawType(responseType).getName()
          + "' is not a valid response body type. Did you mean ResponseBody?");
    }
    //验证responseType的合法性
    if (responseType == Response.class) {
      throw methodError(method, "Response must include generic type (e.g., Response<String>)");
    }
    //验证请求合法性
    if (requestFactory.httpMethod.equals("HEAD") && !Void.class.equals(responseType)) {
      throw methodError(method, "HEAD method must use Void as response type.");
    }
    //从converterFactories中找到合适Converter
    Converter<ResponseBody, ResponseT> responseConverter = createResponseConverter(retrofit, method, responseType);
    okhttp3.Call.Factory callFactory = retrofit.callFactory;
    if (!isKotlinSuspendFunction) {
      return new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
    } else if (continuationWantsResponse) {
      return (HttpServiceMethod<ResponseT, ReturnT>) new SuspendForResponse<>(requestFactory,
          callFactory, responseConverter, (CallAdapter<ResponseT, Call<ResponseT>>) callAdapter);
    } else {
      return (HttpServiceMethod<ResponseT, ReturnT>) new SuspendForBody<>(requestFactory,
          callFactory, responseConverter, (CallAdapter<ResponseT, Call<ResponseT>>) callAdapter,
          continuationBodyNullable);
    }
  }

Retrofit2.6.0版本增加了对协程的处理，支持了协程。我们暂时先不分析这部门，如果不是协程，则返回的是CallAdapted，我们再去看这个

CallAdapted(RequestFactory requestFactory, okhttp3.Call.Factory callFactory,
    Converter<ResponseBody, ResponseT> responseConverter,
    CallAdapter<ResponseT, ReturnT> callAdapter) {
  super(requestFactory, callFactory, responseConverter);
  this.callAdapter = callAdapter;
}
//保存变量
HttpServiceMethod(RequestFactory requestFactory, okhttp3.Call.Factory callFactory,
    Converter<ResponseBody, ResponseT> responseConverter) {
  this.requestFactory = requestFactory;
  this.callFactory = callFactory;
  this.responseConverter = responseConverter;
}

保存requestFactory、callFactory和responseConverter，得到了ServiceMethod
下面我们分析下createCallAdapter

private static <ResponseT, ReturnT> CallAdapter<ResponseT, ReturnT> createCallAdapter(
    Retrofit retrofit, Method method, Type returnType, Annotation[] annotations) {
  try {
    return (CallAdapter<ResponseT, ReturnT>) retrofit.callAdapter(returnType, annotations);
  } catch (RuntimeException e) { // Wide exception range because factories are user code.
    throw methodError(method, e, "Unable to create call adapter for %s", returnType);
  }
}

Retrofit.java

public CallAdapter<?, ?> callAdapter(Type returnType, Annotation[] annotations) {
  return nextCallAdapter(null, returnType, annotations);
}
  public CallAdapter<?, ?> nextCallAdapter(@Nullable CallAdapter.Factory skipPast, Type returnType,
      Annotation[] annotations) {
    ...省略代码
    int start = callAdapterFactories.indexOf(skipPast) + 1;
    for (int i = start, count = callAdapterFactories.size(); i < count; i++) {
    //根据returnType、annotations和Retrofit从callAdapterFactories找到匹配的CallAdapter
      CallAdapter<?, ?> adapter = callAdapterFactories.get(i).get(returnType, annotations, this);
      if (adapter != null) {
        return adapter;
      }
    }
    ...省略代码
  }

createResponseConverter的流程与上面类似，这里就不作分析了。

进行网络请求,得到数据

调用ServiceMethod的invoke，我们看他的实现类HttpServiceMethod的invoke

@Override final @Nullable ReturnT invoke(Object[] args) {
  Call<ResponseT> call = new OkHttpCall<>(requestFactory, args, callFactory, responseConverter);
  return adapt(call, args);
}

首先创建了OkHttpCall，根据保存的ServiceMethod创建对应的OkHttpCall。

OkHttpCall(RequestFactory requestFactory, Object[] args,
    okhttp3.Call.Factory callFactory, Converter<ResponseBody, T> responseConverter) {
  this.requestFactory = requestFactory;
  this.args = args;
  this.callFactory = callFactory;//这里的callFactory是Factory callFactory = retrofit.callFactory;也就是Retrofit中的callFactory
  this.responseConverter = responseConverter;
}

然后调用adapt，我们还看实现类，这里我们看CallAdapted

@Override protected ReturnT adapt(Call<ResponseT> call, Object[] args) {
  return callAdapter.adapt(call);
}

在看callAdapter的adapt调用的是DefaultCallAdapterFactory#get返回的匿名类CallAdapter中adapt

final Executor executor = Utils.isAnnotationPresent(annotations, SkipCallbackExecutor.class)? null: callbackExecutor;
return new CallAdapter<Object, Call<?>>() {
  @Override public Type responseType() {
    return responseType;
  }
  @Override public Call<Object> adapt(Call<Object> call) {
    return executor == null? call: new ExecutorCallbackCall<>(executor, call);//这里面的executor是ExecutorCallbackCall
  }
};

最终得到的实现类是ExecutorCallbackCall。当我们调用enqueue之后，会先调用OkHttpCall的enqueue，OkHttpCall的enqueue本质是调用OkHttp的Call，然后把返回的结果传递到ExecutorCallbackCall中，通过callbackExecutor进行转换，这里面callbackExecutor也是我们上面分析的defaultCallbackExecutor(运行在主线程中)。这样就把结果回调到主线程中了。

@Override public void enqueue(final Callback<T> callback) {
  checkNotNull(callback, "callback == null");
  delegate.enqueue(new Callback<T>() {
    @Override public void onResponse(Call<T> call, final Response<T> response) {
      callbackExecutor.execute(new Runnable() {//进行线程切换
        @Override public void run() {
          if (delegate.isCanceled()) {
            // Emulate OkHttp's behavior of throwing/delivering an IOException on cancellation.
            callback.onFailure(ExecutorCallbackCall.this, new IOException("Canceled"));
          } else {
            callback.onResponse(ExecutorCallbackCall.this, response);
          }
        }
      });
    }

    @Override public void onFailure(Call<T> call, final Throwable t) {
      callbackExecutor.execute(new Runnable() {//进行线程切换
        @Override public void run() {
          callback.onFailure(ExecutorCallbackCall.this, t);
        }
      });
    }
  });
}

当我们调用execute的时候，不做处理，最终直接调用OkHttp的execute。

@Override public boolean isExecuted() {
  return delegate.isExecuted();
}

数据解析

我们通过OkHttp得到的数据并不是我们想要的Bean，Retrofit是通过parseResponse对数据进行解析

  Response<T> parseResponse(okhttp3.Response rawResponse) throws IOException {
    ResponseBody rawBody = rawResponse.body();

    // Remove the body's source (the only stateful object) so we can pass the response along.
    rawResponse = rawResponse.newBuilder()
        .body(new NoContentResponseBody(rawBody.contentType(), rawBody.contentLength()))
        .build();

    int code = rawResponse.code();
    if (code < 200 || code >= 300) {//排除错误的请求
      try {
        // Buffer the entire body to avoid future I/O.
        ResponseBody bufferedBody = Utils.buffer(rawBody);
        return Response.error(bufferedBody, rawResponse);
      } finally {
        rawBody.close();
      }
    }
    if (code == 204 || code == 205) {//如果是204 205直接返回原始数据
      rawBody.close();
      return Response.success(null, rawResponse);
    }
    ExceptionCatchingResponseBody catchingBody = new ExceptionCatchingResponseBody(rawBody);//封装了异常捕获
    try {
      T body = responseConverter.convert(catchingBody);//进行数据解析
      return Response.success(body, rawResponse);
    } catch (RuntimeException e) {
      catchingBody.throwIfCaught();
      throw e;
    }
  }

总结

Retrofit中运用了大量的设计模式，其本质是对OkHttp的一层封装，这篇文章简单的Retrofit的基本流程进行了分析，具体细节还需要看代码分析。