介绍

Retrofit是一个用于Android和Java的类型安全的网络请求封装，之所以说是封装，是因为它只是对OkHttp网络请求框架的封装。Retrofit将网络请求API转化成Java接口的形式，即每个网络请求对应Java接口中的各个方法。它使用动态代理的方式生成该接口的代理对象，然后调用代理对象的方法得到Call对象，最后调用execute完成同步请求或者enqueue完成异步请求。

简单使用示例如下

//1.在接口中定义网络请求的方法，其中请求方式、请求地址以及请求参数等通过注解配置
public interface DemoService {
    @GET("users/{user}/repos")
    Call<List<Repo>> listRepos(@Path("user") String user);
}
//2.通过Builder模式构造Retrofit实例
Retrofit retrofit = new Retrofit.Builder()
                .baseUrl("https://api.github.com/")
                .addConverterFactory(GsonConverterFactory.create())
                .build();
//3.通过动态代理获取接口的代理对象
DemoService demoService = retrofit.create(DemoService.class);
//4.调用代理对象的listRepos方法获取Call对象
Call<List<Repo>> call = demoService.listRepos("jake wharton");
//5.调用call的enqueue方法发起异步请求获得响应
call.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) {

              }
           });

源码分析

基于Retrofit2.5.0

Retrofit实例的构建

Retrofit使用Builder模式构建，初始化其静态内部类Builder，并调用其build方法完成Retrofit的构建。

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

调用一个参数构造方法

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

platform参数是调用Platform的get静态方法得到的

static Platform get() {
  return PLATFORM;
}
private static final Platform PLATFORM = findPlatform();

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和Java8，这里通过反射得到Android平台返回。

设置baseUrl

public Builder baseUrl(String baseUrl) {
  checkNotNull(baseUrl, "baseUrl == null");
  return baseUrl(HttpUrl.get(baseUrl));
}

这里将String类型的url封装成HttpUrl类型。

添加转换器工厂对象

/** Add converter factory for serialization and deserialization of objects. */
public Builder addConverterFactory(Converter.Factory factory) {
  converterFactories.add(checkNotNull(factory, "factory == null"));
  return this;
}

这些工厂创造的转换器对象可以将响应结果解析转换成java类，比如Gson，JackSon转换器等等。

调用build方法

public Retrofit build() {
  if (baseUrl == null) {
    throw new IllegalStateException("Base URL required.");
  }

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

  Executor callbackExecutor = this.callbackExecutor;
  if (callbackExecutor == null) {
    callbackExecutor = platform.defaultCallbackExecutor();
  }

  // Make a defensive copy of the adapters and add the default Call adapter.
  List<CallAdapter.Factory> callAdapterFactories = new ArrayList<>(this.callAdapterFactories);
  callAdapterFactories.addAll(platform.defaultCallAdapterFactories(callbackExecutor));

  // Make a defensive copy of the converters.
  List<Converter.Factory> converterFactories = new ArrayList<>(
      1 + this.converterFactories.size() + platform.defaultConverterFactoriesSize());

  // Add the built-in converter factory first. This prevents overriding its behavior but also
  // ensures correct behavior when using converters that consume all types.
  converterFactories.add(new BuiltInConverters());
  converterFactories.addAll(this.converterFactories);
  converterFactories.addAll(platform.defaultConverterFactories());

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

首先判断了关键对象的非空，将其赋为默认值，如初始化了OkHttpClient客户端类，并获取的当前平台的默认回调执行器对象，安卓平台就是主线程的执行器。然后为请求适配器工厂集合和转换器工厂集合进行了赋值，并调用Retrofit的构造方法实例化Retrofit对象。

Retrofit(okhttp3.Call.Factory callFactory, HttpUrl baseUrl,
    List<Converter.Factory> converterFactories, List<CallAdapter.Factory> callAdapterFactories,
    @Nullable Executor callbackExecutor, boolean validateEagerly) {
  this.callFactory = callFactory;
  this.baseUrl = baseUrl;
  this.converterFactories = converterFactories; // Copy+unmodifiable at call site.
  this.callAdapterFactories = callAdapterFactories; // Copy+unmodifiable at call site.
  this.callbackExecutor = callbackExecutor;
  this.validateEagerly = 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 Object invoke(Object proxy, Method method, @Nullable Object[] args)
            throws Throwable {
          // If the method is a method from Object then defer to normal invocation.
          if (method.getDeclaringClass() == Object.class) {
            return method.invoke(this, args);
          }
          if (platform.isDefaultMethod(method)) {
            return platform.invokeDefaultMethod(method, service, proxy, args);
          }
          return loadServiceMethod(method).invoke(args != null ? args : emptyArgs);
        }
      });
}

validateEagerly标志位是是否要提前验证接口中的方法的配置，默认为false。

接下来通过Proxy.newProxyInstance方法动态代理了传入的service接口。我们知道调用动态代理对象的方法时，InvocationHandler的invoke方法便会执行，这里就是调用listRepos时会调invoke方法，所以我们看一下invoke中的逻辑。

1. 如果当前调用的是Object方法的话，直接执行该方法。
2. 如果该方法是接口的默认方法时，执行invokeDefaultMethod。而这里在安卓平台该值为false，不会执行。
3. 最后执行loadServiceMethod方法，并调用invoke方法。

下面先分析loadServiceMethod方法

ServiceMethod<?> loadServiceMethod(Method method) {
  ServiceMethod<?> result = serviceMethodCache.get(method);
  if (result != null) return result;

  synchronized (serviceMethodCache) {
    result = serviceMethodCache.get(method);
    if (result == null) {
      result = ServiceMethod.parseAnnotations(this, method);
      serviceMethodCache.put(method, result);
    }
  }
  return result;
}

该方法返回一个ServiceMethod类型的对象。

首先从缓存中获取，如果缓存为空，会通过parseAnnotations方法获取

abstract class ServiceMethod<T> {
  static <T> ServiceMethod<T> parseAnnotations(Retrofit retrofit, Method method) {
    RequestFactory requestFactory = RequestFactory.parseAnnotations(retrofit, method);

    Type returnType = method.getGenericReturnType();
    if (Utils.hasUnresolvableType(returnType)) {
      throw methodError(method,
          "Method return type must not include a type variable or wildcard: %s", returnType);
    }
    if (returnType == void.class) {
      throw methodError(method, "Service methods cannot return void.");
    }

    return HttpServiceMethod.parseAnnotations(retrofit, method, requestFactory);
  }

  abstract T invoke(Object[] args);
}

调用RequestFactory的parseAnnotations方法，返回RequestFactory对象

static RequestFactory parseAnnotations(Retrofit retrofit, Method method) {
  return new Builder(retrofit, method).build();
}

Builder(Retrofit retrofit, Method method) {
  this.retrofit = retrofit;
  this.method = method;
  this.methodAnnotations = method.getAnnotations();
  this.parameterTypes = method.getGenericParameterTypes();
  this.parameterAnnotationsArray = method.getParameterAnnotations();
}

获取方法的注解数组methodAnnotations，获取方法的泛型参数类型数组parameterTypes，获取参数注解数组parameterAnnotationsArray。

继而调用build方法，build方法逻辑有些多，分步来看

1. 解析方法注解

   for (Annotation annotation : methodAnnotations) {
     parseMethodAnnotation(annotation);
   }
   

   private void parseMethodAnnotation(Annotation annotation) {
     if (annotation instanceof DELETE) {
       parseHttpMethodAndPath("DELETE", ((DELETE) annotation).value(), false);
     } else if (annotation instanceof GET) {
       parseHttpMethodAndPath("GET", ((GET) annotation).value(), false);
     }  else if (annotation instanceof POST) {
       parseHttpMethodAndPath("POST", ((POST) annotation).value(), true);
     } else if (annotation instanceof retrofit2.http.Headers) {
       String[] headersToParse = ((retrofit2.http.Headers) annotation).value();
       if (headersToParse.length == 0) {
         throw methodError(method, "@Headers annotation is empty.");
       }
       headers = parseHeaders(headersToParse);
     } else if (annotation instanceof Multipart) {
       if (isFormEncoded) {
         throw methodError(method, "Only one encoding annotation is allowed.");
       }
       isMultipart = true;
     } else if (annotation instanceof FormUrlEncoded) {
       if (isMultipart) {
         throw methodError(method, "Only one encoding annotation is allowed.");
       }
       isFormEncoded = true;
     }
   }
   

通过判断注解的类型，执行parseHttpMethodAndPath解析请求方法和请求路径

private void parseHttpMethodAndPath(String httpMethod, String value, boolean hasBody) {
  //...省略部分代码
  // Get the relative URL path and existing query string, if present.
  int question = value.indexOf('?');
  if (question != -1 && question < value.length() - 1) {
    // Ensure the query string does not have any named parameters.
    String queryParams = value.substring(question + 1);
    Matcher queryParamMatcher = PARAM_URL_REGEX.matcher(queryParams);
    if (queryParamMatcher.find()) {
      throw methodError(method, "URL query string \"%s\" must not have replace block. "
          + "For dynamic query parameters use @Query.", queryParams);
    }
  }

  this.relativeUrl = value;
  this.relativeUrlParamNames = parsePathParameters(value);
}

调用parsePathParameters解析请求路径上的参数。

2. 解析方法的参数注解

int parameterCount = parameterAnnotationsArray.length;
parameterHandlers = new ParameterHandler<?>[parameterCount];
for (int p = 0; p < parameterCount; p++) {
  parameterHandlers[p] = parseParameter(p, parameterTypes[p], parameterAnnotationsArray[p]);
}

parameterHandlers是一个二维数组，遍历这个二维数组调用parseParameter方法便可以解析每一个参数的注解

private ParameterHandler<?> parseParameter(
    int p, Type parameterType, @Nullable Annotation[] annotations) {
  ParameterHandler<?> result = null;
  if (annotations != null) {
    for (Annotation annotation : annotations) {
      ParameterHandler<?> annotationAction =
          parseParameterAnnotation(p, parameterType, annotations, annotation);

      if (annotationAction == null) {
        continue;
      }
    //...
      result = annotationAction;
    }
  }
//...
  return result;
}

调用parseParameterAnnotation方法解析单个参数的注解

@Nullable
private ParameterHandler<?> parseParameterAnnotation(
    int p, Type type, Annotation[] annotations, Annotation annotation) {
  if (annotation instanceof Url) {
    //...省略部分代码
  }
  //...省略部分代码
  else if (annotation instanceof Field) {
        validateResolvableType(p, type);
        if (!isFormEncoded) {
          throw parameterError(method, p, "@Field parameters can only be used with form encoding.");
        }
        Field field = (Field) annotation;
        String name = field.value();
        boolean encoded = field.encoded();

        gotField = true;

        Class<?> rawParameterType = Utils.getRawType(type);
        if (Iterable.class.isAssignableFrom(rawParameterType)) {
          if (!(type instanceof ParameterizedType)) {
            throw parameterError(method, p, rawParameterType.getSimpleName()
                + " must include generic type (e.g., "
                + rawParameterType.getSimpleName()
                + "<String>)");
          }
          ParameterizedType parameterizedType = (ParameterizedType) type;
          Type iterableType = Utils.getParameterUpperBound(0, parameterizedType);
          Converter<?, String> converter =
              retrofit.stringConverter(iterableType, annotations);
          return new ParameterHandler.Field<>(name, converter, encoded).iterable();
        } else if (rawParameterType.isArray()) {
          Class<?> arrayComponentType = boxIfPrimitive(rawParameterType.getComponentType());
          Converter<?, String> converter =
              retrofit.stringConverter(arrayComponentType, annotations);
          return new ParameterHandler.Field<>(name, converter, encoded).array();
        } else {
          Converter<?, String> converter =
              retrofit.stringConverter(type, annotations);
          return new ParameterHandler.Field<>(name, converter, encoded);
        }
      } 
  //...省略部分代码

parseParameterAnnotation对各种注解类型做了判断并做了相应的处理，这里以Field注解为例。

如果使用Field注解，但是没有使用FormUrlEncoded的话，会抛出异常。

然后判断参数的类型，并对Iterable、Array以及其他类型的数据做对应的处理

Field(String name, Converter<T, String> valueConverter, boolean encoded) {
  this.name = checkNotNull(name, "name == null");
  this.valueConverter = valueConverter;
  this.encoded = encoded;
}

Field是ParameterHandler的子类，这里构建一个Field返回。这样方法参数的注解也解析完成了，并且将其封装成了对应的ParameterHandler的参数子类，如这里就是Field类。

3. 构建RequestFactory

调用RequestFactory的构造方法，并传入Builder类完成RequestFactory构建。

RequestFactory(Builder builder) {
  method = builder.method;
  baseUrl = builder.retrofit.baseUrl;
  httpMethod = builder.httpMethod;
  relativeUrl = builder.relativeUrl;
  headers = builder.headers;
  contentType = builder.contentType;
  hasBody = builder.hasBody;
  isFormEncoded = builder.isFormEncoded;
  isMultipart = builder.isMultipart;
  parameterHandlers = builder.parameterHandlers;
}

RequestFactory对象封装请求用到的参数，如请求方法、baseUrl、relativeUrl、请求头以及请求参数等等。

构建完RequestFactory后，调用HttpServiceMethod的parseAnnotations方法

static <ResponseT, ReturnT> HttpServiceMethod<ResponseT, ReturnT> parseAnnotations(
    Retrofit retrofit, Method method, RequestFactory requestFactory) {
  CallAdapter<ResponseT, ReturnT> callAdapter = createCallAdapter(retrofit, method);
//省略部分代码...
  Converter<ResponseBody, ResponseT> responseConverter =
      createResponseConverter(retrofit, method, responseType);

  okhttp3.Call.Factory callFactory = retrofit.callFactory;
  return new HttpServiceMethod<>(requestFactory, callFactory, callAdapter, responseConverter);
}

获取CallAdapter、Converter对象以及callFactory对象构建HttpServiceMethod并返回。

private HttpServiceMethod(RequestFactory requestFactory, okhttp3.Call.Factory callFactory,
    CallAdapter<ResponseT, ReturnT> callAdapter,
    Converter<ResponseBody, ResponseT> responseConverter) {
  this.requestFactory = requestFactory;
  this.callFactory = callFactory;
  this.callAdapter = callAdapter;
  this.responseConverter = responseConverter;
}

loadServiceMethod方法分析完成，得到了HttpServiceMethod对象，然后调用其invoke方法

@Override ReturnT invoke(Object[] args) {
  return callAdapter.adapt(
      new OkHttpCall<>(requestFactory, args, callFactory, responseConverter));
}

这里会构建一个OkHttpCall对象传入adapt方法。这里通过配置的CallAdapter对象适配出一个对应平台的对象，默认是Call对象，而这里就是Call<List<Repo>>类型的对象。

调用enqueue发起异步网络请求

调用createRawCall方法创建OkHttp的RealCall对象，调用call的enqueue的方法使用Okhttp发起异步请求。

@Override public void enqueue(final Callback<T> callback) {
  checkNotNull(callback, "callback == null");

  okhttp3.Call call;
  Throwable failure;

  synchronized (this) {
    if (executed) throw new IllegalStateException("Already executed.");
    executed = true;

    call = rawCall;
    failure = creationFailure;
    if (call == null && failure == null) {
      try {
        call = rawCall = createRawCall();
      } catch (Throwable t) {
        throwIfFatal(t);
        failure = creationFailure = t;
      }
    }
  }

  if (failure != null) {
    callback.onFailure(this, failure);
    return;
  }

  if (canceled) {
    call.cancel();
  }

  call.enqueue(new okhttp3.Callback() {
    @Override public void onResponse(okhttp3.Call call, okhttp3.Response rawResponse) {
      Response<T> response;
      try {
        response = parseResponse(rawResponse);
      } catch (Throwable e) {
        throwIfFatal(e);
        callFailure(e);
        return;
      }

      try {
        callback.onResponse(OkHttpCall.this, response);
      } catch (Throwable t) {
        t.printStackTrace();
      }
    }

    @Override public void onFailure(okhttp3.Call call, IOException e) {
      callFailure(e);
    }

    private void callFailure(Throwable e) {
      try {
        callback.onFailure(OkHttpCall.this, e);
      } catch (Throwable t) {
        t.printStackTrace();
      }
    }
  });
}

在onResponse中调用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) {
    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) {
    // If the underlying source threw an exception, propagate that rather than indicating it was
    // a runtime exception.
    catchingBody.throwIfCaught();
    throw e;
  }
}

调用converter的convert方法转换响应结果，并返回响应结果。如果失败，则回调失败响应结果。