Retrofit如何在OkHttp进行封装和拓展

Retrofit简介

创新互联公司为您提适合企业的网站设计 让您的网站在搜索引擎具有高度排名，让您的网站具备超强的网络竞争力！结合企业自身，进行网站设计及把握，最后结合企业文化和具体宗旨等，才能创作出一份性化解决方案。从网站策划到成都网站设计、做网站， 我们的网页设计师为您提供的解决方案。

Retrofit是Square公司开源的一个高质量高效率的HTTP库，github上面star数量最多的Android网络库就是这个，底层封装了okhttp，JakeWharton大神的经典作品之一。

OKhttp网络框架

一个处理网络请求的开源项目,是安卓端最火热的轻量级框架,由移动支付Square公司贡献

基本使用

我们首先来看看 Retrofit 的基本使用，来对它有个大致的了解。

首先，我们可以构建一个如下的请求 Service 类，它里面对各个请求的方法及参数通过注解进行了标注：

  public interface GitHubService {
    @GET("users/{user}/repos")
    Call> listRepos(@Path("user") String user);
  }

之后，我们可以构建一个 Retrofit 对象，并通过 Retrofit.create 方法传入对应 class 从而构建对应的 Service 对象：

  Retrofit retrofit = new Retrofit.Builder()
     baseUrl("https://api.github.com/")
     build();
  }
  GitHubService service = retrofit.create(GitHubService.class);

之后，我们调用 service 中对应的方法，就可以获取到 Call 对象了。

通过对 Call 对象调用 enqueue 就可以实现对请求的异步调用，而通过 execute 方法则可以实现请求的同步调用。

Retrofit 对象的构建

Retrofit 采用了 Builder 模式进行了构建，在 Builder 中可以进行非常多的配置，其中可以对 baseUrl、okhttpClient、converterFactory、callAdapterFactory 等进行设置。

这里没什么特别的，都是一些简单的赋值，就不再关注了，我们只需要看看最后 Retrofit 被传入了哪些参数。它最后调用了下面这个构造函数对参数进行了初始化。

  Retrofit(okhttp3.Call.Factory callFactory, HttpUrl baseUrl,
      List converterFactories, List 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;
  }

Service 对象的创建

动态代理创建 Service 代理类

接着我们看到自己定义的 interface 是如何仅仅靠传递 class 给 Retrofit.create 就能实现实例的获取的，它明明只是个接口呀？

  public  T create(final Class service) {
     // 对 Service 的接口进行检测
    validateServiceInterface(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);
            }
            // 如果是对应平台本身的类就有的方法，照常调用
            if (platform.isDefaultMethod(method)) {
              return platform.invokeDefaultMethod(method, service, proxy, args);
            }
            // 否则通过 loadServiceMethod 方法获取到对应 Method 并 invoke
            return loadServiceMethod(method).invoke(args != null ? args : emptyArgs);
            }
         });
  }

可以看到，实际上 Service 对象的获取是通过动态代理实现的。这里首先通过 validateServiceInterface 方法对接口进行了检测，之后通过动态代理对该接口进行了代理。

对于 Object 类本身独有以及对应平台本身就存在的方法，就照常调用，否则通过 loadServiceMethod 对 Service 中对应的 Method 对象进行处理，之后对其调用 invoke 方法。

这里说明了 Retrofit 不是在创建 Service 接口对应对象时就立即对所有该接口中的所有方法都进行注解的解析，而是采用了在方法被调用时才进行注解的解析这种懒加载的思想。

接着我们看看 validateServiceInterface 方法：

  private void validateServiceInterface(Class service) {
      // 判断是否是接口
    if (!service.isInterface()) {
      throw new IllegalArgumentException("API declarations must be interfaces.");
    }
    // 判断该接口及其继承的所有接口是否包含了范型参数，如果包含则抛出异常
    Deque> check = new ArrayDeque<>(1);
    check.add(service);
    while (!check.isEmpty()) {
      Class candidate = check.removeFirst();
      if (candidate.getTypeParameters().length != 0) {
        StringBuilder message = new StringBuilder("Type parameters are unsupported on ").append(candidate.getName());
        if (candidate != service) {
          message.append(" which is an interface of ").append(service.getName());
        }
        throw new IllegalArgumentException(message.toString());
      }
      Collections.addAll(check, candidate.getInterfaces());
   }
   // 如果在创建Retrofit时设置了很急切地对Service的方法进行处理，则对非平台独有且非static的方法通过 loadServiceMethod 方法进行处理。
   if (validateEagerly) {
     Platform platform = Platform.get();
     for (Method method : service.getDeclaredMethods()) {
       if (!platform.isDefaultMethod(method) && !Modifier.isStatic(method.getModifiers())) {
         loadServiceMethod(method);
       }
     }
   }
  }

首先，这个方法对 service 进行了检测，保证了它是一个接口并且它和它继承的类中没有范型参数。

之后如果在 Retrofit 创建时设置 validateEagerly 为 true 的话，会对 Service 中所有非平台独有且非static的方法通过 loadServiceMethod 方法提前进行处理

Service 中方法的解析

那么我们来看看 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;
  }

首先它会采用 Double Check 的方式尝试从 serviceMethodCache 缓存中获取 ServiceMethod 对象，如果获取不到则通过 ServiceMethod.parseAnnotations 方法对该 Method 的注解进行处理并将得到的 ServiceMethod 对象加入了缓存。

也就是说为了避免多次对方法的注解进行处理，Retrofit 采用了一个 serviceMethodCache 对解析后的 ServiceMethod 进行缓存。

接着我们就来看看，parseAnnotations 方法是如何对方法的注解进行解析的。

  static  ServiceMethod 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);
   }

这里先通过 RequestFactory.parseAnnotations 方法对注解解析并获得了一个 RequestFactory 对象。

之后又通过 HttpServiceMethod.parseAnnotations 方法传入了 requestFactory继续进行注解的解析并获得 ServiceMethod 对象

注解解析

我们先看看 RequestFactory.parseAnnotations：

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

它把 Method 传入 Builder 从而构建了一个新的 RequestFactory：

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

Builder 中通过反射获取到method所包含的注解、参数包含的范型以及参数的注解。

接着看看 build 方法：

  RequestFactory build() {
    for (Annotation annotation : methodAnnotations) {
        // 遍历方法注解对每个注解进行解析
      parseMethodAnnotation(annotation);
    }
    // ...异常的处理

   // 对参数进行解析
    int parameterCount = parameterAnnotationsArray.length;
    parameterHandlers = new ParameterHandler[parameterCount];
    for (int p = 0, lastParameter = parameterCount - 1; p < parameterCount; p++) {
      parameterHandlers[p] = parseParameter(p, parameterTypes[p], parameterAnnotationsArray[p], p == lastParameter);
    }

    // ... 异常的处理
   return new RequestFactory(this);
  }

在 build 方法中主要是对方法的每个注解调用了 parseMethodAnnotation 进行了解析，并且对每个参数调用了 parseParamter 方法解析为了 ParamterHandler 对象。

parseMethodAnnotation 的代码如下：

  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 HEAD) {
      parseHttpMethodAndPath("HEAD", ((HEAD) annotation).value(), false);
    } else if (annotation instanceof PATCH) {
      parseHttpMethodAndPath("PATCH", ((PATCH) annotation).value(), true);
    } else if (annotation instanceof POST) {
      parseHttpMethodAndPath("POST", ((POST) annotation).value(), true);
    } else if (annotation instanceof PUT) {
      parseHttpMethodAndPath("PUT", ((PUT) annotation).value(), true);
    } else if (annotation instanceof OPTIONS) {
      parseHttpMethodAndPath("OPTIONS", ((OPTIONS) annotation).value(), false);
    } else if (annotation instanceof HTTP) {
      HTTP http = (HTTP) annotation;
      parseHttpMethodAndPath(http.method(), http.path(), http.hasBody());
    } 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;
   }
  }

这里实际上就是对每一种 HTTP 所支持的类型进行了支持，获取到了对应注解的中的 url，并调用parseHttpMethodAndPath 进行处理，同时对 Headers 注解则是通过 parseHeaders 进行了处理。

对 Http 请求方式和 Path 的处理

对于 Method 和 Path，通过 parseHttpMethodAndPath 进行了参数的赋值：

  private void parseHttpMethodAndPath(String httpMethod, String value, boolean hasBody) {
    if (this.httpMethod != null) {
      throw methodError(method, "Only one HTTP method is allowed. Found: %s and %s.",
          this.httpMethod, httpMethod);
    }
    this.httpMethod = httpMethod;
    this.hasBody = hasBody;
    if (value.isEmpty()) {
      return;
    }
    // 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);
  }

这里实际上就是对不同 HTTP 请求方式和 Path 进行了赋值，同时通过正则表达式保证了这个接口的 Path 中没有包含参数。

对 Headers 的处理

  private Headers parseHeaders(String[] headers) {
    Headers.Builder builder = new Headers.Builder();
    for (String header : headers) {
      int colon = header.indexOf(':');
      if (colon == -1 || colon == 0 || colon == header.length() - 1) {
        throw methodError(method,
            "@Headers value must be in the form \"Name: Value\". Found: \"%s\"", header);
      }
      String headerName = header.substring(0, colon);
      String headerValue = header.substring(colon + 1).trim();
      if ("Content-Type".equalsIgnoreCase(headerName)) {
        try {
          contentType = MediaType.get(headerValue);
        } catch (IllegalArgumentException e) {
          throw methodError(method, e, "Malformed content type: %s", headerValue);
        }
      } else {
        builder.add(headerName, headerValue);
      }
    }
    return builder.build();
  }

而对于 Headers 则是将传递进来的 Headers 列表解析为了对应的 Headers 对象。

对方法参数的处理

最后我们看看对方法参数的处理：

  private @Nullable ParameterHandler parseParameter(
      int p, Type parameterType, @Nullable Annotation[] annotations, boolean allowContinuation) {
    ParameterHandler result = null;
    if (annotations != null) {
      for (Annotation annotation : annotations) {
          // 对每个注解通过 parseParameterAnnotation 进行解析
        ParameterHandler annotationAction =
            parseParameterAnnotation(p, parameterType, annotations, annotation);
        if (annotationAction == null) {
          continue;
        }
        if (result != null) {
          throw parameterError(method, p,
              "Multiple Retrofit annotations found, only one allowed.");
        }
        result = annotationAction;
      }
    }
    if (result == null) {
        // 在协程的情况下对进行特殊处理
      if (allowContinuation) {
        try {
          if (Utils.getRawType(parameterType) == Continuation.class) {
            isKotlinSuspendFunction = true;
            return null;
          }
        } catch (NoClassDefFoundError ignored) {
        }
      }
      throw parameterError(method, p, "No Retrofit annotation found.");
    }
    return result;
  }

而 parseParamterAnnotation 方法的代码太长了，这里就不再贴了，它对方法的每个注解都进行了独有的处理，并返回了对应的 ParamterHandler。

可以发现，RequestFactory.parseAnnotations 的主要作用就是完成对方法注解信息的解析，从而用于产生对应的 Request。

ServiceMethod 的创建

之后我们接着看看 HttpServiceMethod.parseAnnotations：

  static  HttpServiceMethod 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) {
        // 如果方法是 kotlin 中的 suspend 方法
      Type[] parameterTypes = method.getGenericParameterTypes();
      // 获取 Continuation 的范型参数，它就是 suspend 方法的返回值类型
      Type responseType = Utils.getParameterLowerBound(0,
          (ParameterizedType) parameterTypes[parameterTypes.length - 1]);
      // 如果 Continuation 的范型参数是 Response，则说明它需要的是 Response，那么将 continuationWantsResponse 置为 true;
      if (getRawType(responseType) == Response.class && responseType instanceof ParameterizedType) {
        // Unwrap the actual body type from Response.
        responseType = Utils.getParameterUpperBound(0, (ParameterizedType) responseType);
        continuationWantsResponse = true;
      } else {
          // TODO figure out if type is nullable or not
         // Metadata metadata = method.getDeclaringClass().getAnnotation(Metadata.class)
        // Find the entry for method
       // Determine if return type is nullable or not
      }
      adapterType = new Utils.ParameterizedTypeImpl(null, Call.class, responseType);
      annotations = SkipCallbackExecutorImpl.ensurePresent(annotations);
    } else {
        // 否则获取方法返回值的范型参数，即为请求需要的返回值的类型
      adapterType = method.getGenericReturnType();
    }
    // 通过 createCallAdapter 方法创建 CallAdapter 对象
    CallAdapter callAdapter =
        createCallAdapter(retrofit, method, adapterType, annotations);
    Type responseType = callAdapter.responseType();
    if (responseType == okhttp3.Response.class) {
      throw methodError(method, "'"
          + getRawType(responseType).getName()
          + "' is not a valid response body type. Did you mean ResponseBody?");
    }
    if (responseType == Response.class) {
      throw methodError(method, "Response must include generic type (e.g., Response)");
    }
    // TODO support Unit for Kotlin?
    if (requestFactory.httpMethod.equals("HEAD") && !Void.class.equals(responseType)) {
      throw methodError(method, "HEAD method must use Void as response type.");
    }
    // 通过 createResponseConverter 方法创建 Converter对象
    Converter responseConverter =
        createResponseConverter(retrofit, method, responseType);
    okhttp3.Call.Factory callFactory = retrofit.callFactory;
    if (!isKotlinSuspendFunction) {
        // 不是suspend方法的话则直接创建并返回一个 CallAdapted 对象
      return new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
    } else if (continuationWantsResponse) {
      //noinspection unchecked Kotlin compiler guarantees ReturnT to be Object.
      return (HttpServiceMethod) new SuspendForResponse<>(requestFactory,
          callFactory, responseConverter, (CallAdapter>) callAdapter);
    } else {
      //noinspection unchecked Kotlin compiler guarantees ReturnT to be Object.
      return (HttpServiceMethod) new SuspendForBody<>(requestFactory,
          callFactory, responseConverter, (CallAdapter>) callAdapter,
          continuationBodyNullable);
    }
  }

这里的代码非常非常长，大致可归纳为下面的步骤：

1.如果这个方法是 Kotlin 中的 suspend 方法，由于由协程实现，因此需要获取 Continuation 的范型参数，这个参数就是请求返回值的真正类型。
2.如果 suspend 方法返回值是 Response，则说明它需要的是 Response 而不是具体的类型，那么将 continuationWantsResponse 置为 true;
3.如果不是 suspend 方法，则返回值的范型参数的类型就是请求返回值的真正类型（Call<ReturnType> 则 ReturnType 才是真正经过转换后需要的类型）。
4.通过 createCallAdapter 方法创建 CallAdapter 对象，它是用于将 Call<ResponseT> 对象适配为需要的类型 ReturnT 对象的。
5.拿到 CallAdapter 后，获取到了 Response 的类型，并进行了校验。
6.通过 createResponseConverter 方法获取 Converter 对象，它可以完成从 ResponseBody 到 Response 类型 ResponseT 的转换。
7.如果并非 Kotlin 的 suspend 方法，则直接传入 CallAdapter 及 Converter，创建 CallAdapted 对象。
8.否则根据 suspend 方法需要的是 Response 还是具体的类型，分别返回 SuspendForResponse 和 SuspendForBody 对象。

可以发现，新版的 Retrofit 对 Kotlin 的协程进行了支持。HttpServiceMethod.parseAnnotations 的主要作用就是创建 CallAdapter 以及 Converter 对象，并构建对应 HttpServiceMethod。

CallAdapter

CallAdapter 是用于将Call<R>对象适配为需要的类型 T 对象的。它的声明如下：

  public interface CallAdapter {

      // 返回 Response 的类型
    Type responseType();
       // 将 Call 转换为 T 类型 
    T adapt(Call call);
  }

我们先看看 createCallAdapter 方法是如何对它创建的：

  private static  CallAdapter createCallAdapter(
      Retrofit retrofit, Method method, Type returnType, Annotation[] annotations) {
    try {
      //noinspection unchecked
      return (CallAdapter) 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.callAdapter 方法：

  public CallAdapter callAdapter(Type returnType, Annotation[] annotations) {
    return nextCallAdapter(null, returnType, annotations);
  }

之后调用到 retrofit.nextCallAdapter 方法：

  public CallAdapter nextCallAdapter(@Nullable CallAdapter.Factory skipPast, Type returnType,
      Annotation[] annotations) {
    Objects.requireNonNull(returnType, "returnType == null");
    Objects.requireNonNull(annotations, "annotations == null");
    int start = callAdapterFactories.indexOf(skipPast) + 1;
    for (int i = start, count = callAdapterFactories.size(); i < count; i++) {
         // 遍历 callAdapterFactories，尝试创建 CallAdapter
      CallAdapter adapter = callAdapterFactories.get(i).get(returnType, annotations, this);
      if (adapter != null) {
        return adapter;
      }
    }
    // ...不存在对应的 CallAdapterFactory，抛出异常
  }

这里实际上是遍历了创建 Retrofit 对象时传递的 CallAdapter.Factory 列表尝试去创建 CallAdapter。如果这些 CallAdapter.Factory 都无法处理这个对应的 returnType 以及 annotations 的话，则会抛出异常。（前面 Factory 的优先级更高）

Retrofit 中有一个默认的 CallAdapter 工厂 DefaultCallAdapterFactory，它的优先级比所有自定义工厂要低，它在创建时会传入一个 Executor，我们可以看到它的 get 方法：

  @Override public @Nullable CallAdapter get(
      Type returnType, Annotation[] annotations, Retrofit retrofit) {
    if (getRawType(returnType) != Call.class) {
      return null;
    }
    if (!(returnType instanceof ParameterizedType)) {
      throw new IllegalArgumentException(
          "Call return type must be parameterized as Call or Call");
    }
    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() {
        return responseType;
      }
      @Override public Call