拆轮子系列:Retrofit2

阅读 151
收藏 6
2018-12-02
原文链接:www.jianshu.com

拆轮子系列:Retrofit2

[TOC]

Retrofit本质上是对OkHttpClient网络交互的封装,它接管的是网络请求前和网络请求后,即HttpRequest封装,HttpResponse处理,网络请求过程则交给OkHttpClient。Retrofit采用了一套非常好的设计思想,使得其提供的各部分功能扩展性强,耦合度低。

Retrofit设计流程如下:


image

Retrofit详细过程梳理如下:

定义网络接口

ResultType 为原始的 retrofit2.Call:

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

ResultType为RxJava Observable:

public interface StudioApiService {
    @GET("/studio/doctors/{docId}/clinics/{clinicId}")
    Observable<UserClinic> getClinicItem(
            @Path("docId") String docId, @Path("clinicId") String clinicId);

    @PUT("/studio/doctors/{docId}/clinics/{clinicId}")
    Observable<UserClinic> putClinic(
            @Path("docId") String docId, @Path("clinicId") String clinicId,
            @Body UserClinic clinic);

    @DELETE("/studio/doctors/{docId}/clinics/{clinicId}")
    Observable<Void> deleteClinic(
            @Path("docId") String docId, @Path("clinicId") String clinicId);

    @POST("/studio/doctors/{docId}/clinics")
    Observable<UserClinic> postClinic(@Path("docId") String docId, @Body UserClinic clinic);
}

创建Retrofit实例

new Retrofit.Builder()
    .baseUrl(url)
    .addConverterFactory(GsonConverterFactory.create(new GsonBuilder().setLenient().create()))
    .addCallAdapterFactory(RxErrorHandlingCallAdapterFactory.create(context))
    .client(setupClient())
    .build();

API 接口的调用

API接口的调用过程:

StudioAPiService apiService = retrofit.create(StudioAPiService.class);

Create过程采用的是动态代理方式,Retrofit为接口类生成一个动态代理,通过这种方式调用接口时Retrofit自动接管了调用的过程。代码如下,其中Proxy.newProxyInstance就是一个标准的动态代理过程

public <T> T create(final Class<T> service) {
    ... 
    return (T) Proxy.newProxyInstance(service.getClassLoader(), new Class<?>[] { service },
        new InvocationHandler() {
          private final Platform platform = Platform.get();

          @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);
            }
            ServiceMethod<Object, Object> serviceMethod =
                (ServiceMethod<Object, Object>) loadServiceMethod(method);
            OkHttpCall<Object> okHttpCall = new OkHttpCall<>(serviceMethod, args);
            return serviceMethod.callAdapter.adapt(okHttpCall);
          }
        });
  }

调用过程中有关键的三个步骤。

ServiceMethod<Object, Object> serviceMethod = (ServiceMethod<Object, Object>) loadServiceMethod(method);
OkHttpCall<Object> okHttpCall = new OkHttpCall<>(serviceMethod, args);
return serviceMethod.callAdapter.adapt(okHttpCall);

这是Retrofit调用的关键三步:

  1. 创建ServiceMethod:根据传入的method创建,这一步涉及到Annotation的解析等,后面会详解;
  2. 创建OkHttpCall:根据ServiceMethod创建;
  3. 执行OkHttpCall进行网络请求,涉及到CallAdapter切换

ServiceMethod

看看 ServiceMethod 的构造函数:

ServiceMethod(Builder<R, T> builder) {
  this.callFactory = builder.retrofit.callFactory();
  this.callAdapter = builder.callAdapter;
  this.baseUrl = builder.retrofit.baseUrl();
  this.responseConverter = builder.responseConverter;
  this.httpMethod = builder.httpMethod;
  this.relativeUrl = builder.relativeUrl;
  this.headers = builder.headers;
  this.contentType = builder.contentType;
  this.hasBody = builder.hasBody;
  this.isFormEncoded = builder.isFormEncoded;
  this.isMultipart = builder.isMultipart;
  this.parameterHandlers = builder.parameterHandlers;
}

成员很多,但这里我们重点关注四个成员:callFactory,callAdapter, responseConverter 和 parameterHandlers。

  1. callFactory 负责创建 HTTP 请求,HTTP 请求被抽象为了 okhttp3.Call 类,它表示一个已经准备好,可以随时执行的 HTTP 请求;
  2. callAdapter 把 retrofit2.Call<T> 转为 T(注意和 okhttp3.Call 区分开来,retrofit2.Call<T> 表示的是对一个 Retrofit 方法的调用),这个过程会发送一个 HTTP 请求,拿到服务器返回的数据(通过 okhttp3.Call 实现),并把数据转换为声明的 T 类型对象(通过 Converter<F, T> 实现);
  3. responseConverter 是 Converter<ResponseBody, T> 类型,负责把服务器返回的数据(JSON、XML、二进制或者其他格式,由 ResponseBody 封装)转化为 T 类型的对象;
  4. parameterHandlers 则负责解析 API 定义时每个方法的参数,并在构造 HTTP 请求时设置参数;

callFactory

this.callFactory = builder.retrofit.callFactory(),所以 callFactory 实际上由 Retrofit 类提供,而我们在构造 Retrofit 对象时,可以指定 callFactory,如果不指定,将默认设置为一个 okhttp3.OkHttpClient。

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

callFactory具体在什么时候使用呢?

private okhttp3.Call createRawCall() throws IOException {
  Request request = serviceMethod.toRequest(args);
  okhttp3.Call call = serviceMethod.callFactory.newCall(request);
  if (call == null) {
    throw new NullPointerException("Call.Factory returned null.");
  }
  return call;
}

serviceMethod.callFactory.newCall(request);这就是她的作用,用来创建一个 okhttp3.Call对象,然后通过这个call对象发起网络请求。

callAdapter

关于Retrofit中的call,涉及到以下三个:

retrofit2.Call接口如下:

public interface Call<T> extends Cloneable {
  
  Response<T> execute() throws IOException;

  void enqueue(Callback<T> callback);

  boolean isExecuted();

  void cancel();

  boolean isCanceled();

  Call<T> clone();

  Request request();
}

retrofit2.OkHttpCall类,这是对retrofit2.Call的实现。Retrofit下的网络请求会被转换成retrofit2.OkHttpCall,其背后则是转换成okhttp3.Call,执行,这里就把具体的网络请求委托给了OkHttpClient执行了。

final class OkHttpCall<T> implements Call<T> {

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

    okhttp3.Call call;
    Throwable failure;

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

      @Override public void onFailure(okhttp3.Call call, IOException e) {
        try {
          callback.onFailure(OkHttpCall.this, e);
        } catch (Throwable t) {
          t.printStackTrace();
        }
      }

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

      private void callSuccess(Response<T> response) {
        try {
          callback.onResponse(OkHttpCall.this, response);
        } catch (Throwable t) {
          t.printStackTrace();
        }
      }
    });
  }
}

下面再来讲讲serviceMethod.callAdapter.adapt(okHttpCall),以RxJavaCallAdapterFactory中的RxJavaCallAdapter,前者是后者的工厂类。

下来看一下RxJavaCallAdapterFactory的构造方法,注意到isAsync,默认是false,即网络请求默认是同步的。

private RxJavaCallAdapterFactory(@Nullable Scheduler scheduler, boolean isAsync) {
  this.scheduler = scheduler;
  this.isAsync = isAsync;
}

再来看一下RxJavaCallAdapter究竟如何实现Call对象的adapter(), 很简单,为call对象创建一个RxJava的Observable。其中CallEnqueueOnSubscribe、CallExecuteOnSubscribe最终调用的又是OkHttpCall中的相应的enqueue()、execute()方法

@Override public Object adapt(Call<R> call) {
    OnSubscribe<Response<R>> callFunc = isAsync
        ? new CallEnqueueOnSubscribe<>(call)
        : new CallExecuteOnSubscribe<>(call);

    OnSubscribe<?> func;
    if (isResult) {
      func = new ResultOnSubscribe<>(callFunc);
    } else if (isBody) {
      func = new BodyOnSubscribe<>(callFunc);
    } else {
      func = callFunc;
    }
    Observable<?> observable = Observable.create(func);

    if (scheduler != null) {
      observable = observable.subscribeOn(scheduler);
    }

    if (isSingle) {
      return observable.toSingle();
    }
    if (isCompletable) {
      return observable.toCompletable();
    }
    return observable;
  }

responseConverter

这个很好理解,对Response的解析,将Response转换成最终对象,跟踪代码可以看到。在OkHttpCall中拿到最终的response之后,会调用

T body = serviceMethod.toResponse(catchingBody);

R toResponse(ResponseBody body) throws IOException {
  return responseConverter.convert(body);
}

以GsonConverterFactory提供的GsonResponseBodyConverter为例:

@Override public T convert(ResponseBody value) throws IOException {
  JsonReader jsonReader = gson.newJsonReader(value.charStream());
  try {
    return adapter.read(jsonReader);
  } finally {
    value.close();
  }
}

parameterHandlers

每个参数都会有一个 ParameterHandler,由 ServiceMethod#parseParameter 方法负责创建,其主要内容就是解析每个参数使用的注解类型(诸如 Path,Query,Field 等),对每种类型进行单独的处理。构造 HTTP 请求时,我们传递的参数都是字符串,那 Retrofit 是如何把我们传递的各种参数都转化为 String 的呢?还是由 Retrofit 类提供 converter!

其关系流程为:

API Method--(ParameterHandler)--> retrofit2.RequestBuilder --> okhttp3.Request

先来看看ServiceMethod中的toRequest方法:

Request toRequest(@Nullable Object... args) throws IOException {
    RequestBuilder requestBuilder = new RequestBuilder(httpMethod, baseUrl, relativeUrl, headers,
    contentType, hasBody, isFormEncoded, isMultipart);

    @SuppressWarnings("unchecked") // It is an error to invoke a method with the wrong arg types.
    ParameterHandler<Object>[] handlers = (ParameterHandler<Object>[]) parameterHandlers;

    int argumentCount = args != null ? args.length : 0;
    if (argumentCount != handlers.length) {
      throw new IllegalArgumentException("Argument count (" + argumentCount
          + ") doesn't match expected count (" + handlers.length + ")");
    }

    for (int p = 0; p < argumentCount; p++) {
      handlers[p].apply(requestBuilder, args[p]);
    }

    return requestBuilder.build();
  }

再来看看RequestBuilder.build() 方法:

Request build() {
    HttpUrl url;
    HttpUrl.Builder urlBuilder = this.urlBuilder;
    if (urlBuilder != null) {
      url = urlBuilder.build();
    } else {
      // No query parameters triggered builder creation, just combine the relative URL and base URL.
      //noinspection ConstantConditions Non-null if urlBuilder is null.
      url = baseUrl.resolve(relativeUrl);
      if (url == null) {
        throw new IllegalArgumentException(
            "Malformed URL. Base: " + baseUrl + ", Relative: " + relativeUrl);
      }
    }

    RequestBody body = this.body;
    if (body == null) {
      // Try to pull from one of the builders.
      if (formBuilder != null) {
        body = formBuilder.build();
      } else if (multipartBuilder != null) {
        body = multipartBuilder.build();
      } else if (hasBody) {
        // Body is absent, make an empty body.
        body = RequestBody.create(null, new byte[0]);
      }
    }

    MediaType contentType = this.contentType;
    if (contentType != null) {
      if (body != null) {
        body = new ContentTypeOverridingRequestBody(body, contentType);
      } else {
        requestBuilder.addHeader("Content-Type", contentType.toString());
      }
    }

    return requestBuilder
        .url(url)
        .method(method, body)
        .build();
  }

Multipart 处理

@Multipart 是Retrofit2对多文件上传处理的封装,本质上是对multipart/form-data的封装,这个封装依赖于OkHttp中提供的MultipartBody。先来看一下@Multipart的使用方式:

public interface UploadService {

    /**
     * @Multipart 这个标记很重要,Retrofit会判断是否有这个标记来对参数重新封装
     *
     * 针对接口2,参数为MultipartBody, 它本身就是一个RequestBody,Retrofit据此判断不进行再次封装
     */
    @Multipart
    @POST("/upload")
    Call<Void> uploadImages(@Part() List<MultipartBody.Part> parts);

    @Multipart
    @POST("/upload")
    Call<Void> uploadImages(@Part() MultipartBody.Part part, @Part("description") RequestBody description);

    @POST("/upload")
    Call<Void> uploadImages(@Body MultipartBody body);
}

其中,可以将MultipartBody.Part、MultipartBody的创建封装成通用的两个方法,它们的创建方式都是由OKHttp提供的,目的都是将之转换成OKHttp中的MultipartBody。如下:

public class FileToHttpBody {

    public static MultipartBody filesToMultiBody(List<File> files) {
        MultipartBody.Builder builder = new MultipartBody.Builder();
        for (File file: files) {
            RequestBody requestBody = RequestBody.create(MediaType.parse("image/png"), file);
            builder.addFormDataPart("file", file.getName(), requestBody);
        }
        builder.setType(MultipartBody.FORM);
        MultipartBody multipartBody = builder.build();
        return multipartBody;
    }


    public static List<MultipartBody.Part> filesToMultiParts(List<File> files) {
        List<MultipartBody.Part> parts = new ArrayList<>();
        for (File file: files) {
            RequestBody requestBody = RequestBody.create(MediaType.parse("image/png"), file);
            parts.add(MultipartBody.Part.createFormData("file", file.getName(), requestBody));
        }
        return parts;
    }
}

下面我们再来看一下Retrofit对@Multipart、@Part这两个标签分别干了什么。

@Multipart

private void parseMethodAnnotation(Annotation annotation) {
     ...
      
     } else if (annotation instanceof Multipart) {
        if (isFormEncoded) {
          throw methodError("Only one encoding annotation is allowed.");
        }
        isMultipart = true;
     } 

    ...
}

Retrofit根据@Multipart打上标记isMultipart,后续依此封装成MultipartBody。

@Part

private ParameterHandler<?> parseParameterAnnotation(
        int p, Type type, Annotation[] annotations, Annotation annotation) {
     if (annotation instanceof Part) {
        if (!isMultipart) {
          throw parameterError(p, "@Part parameters can only be used with multipart encoding.");
        }
        Part part = (Part) annotation;
        gotPart = true;

        String partName = part.value();
        Class<?> rawParameterType = Utils.getRawType(type);
        if (partName.isEmpty()) {
          if (Iterable.class.isAssignableFrom(rawParameterType)) {

            ...
            else if (MultipartBody.Part.class.isAssignableFrom(rawParameterType)) {
            return ParameterHandler.RawPart.INSTANCE;
          } else {
            throw parameterError(p,
                "@Part annotation must supply a name or use MultipartBody.Part parameter type.");
          }
        } else {
          Headers headers =
              Headers.of("Content-Disposition", "form-data; name=\"" + partName + "\"",
                  "Content-Transfer-Encoding", part.encoding());

            ...
            Converter<?, RequestBody> converter =
                retrofit.requestBodyConverter(type, annotations, methodAnnotations);
            return new ParameterHandler.Part<>(headers, converter);
          }
        }
    }
}

这里,提到了两个ParameterHandler:ParameterHandler.RawPart, ParameterHandler.Part。这两个ParameterHandler直接调用了MultipartBody 中的addPart()方法,其源码如下:

static final class RawPart extends ParameterHandler<MultipartBody.Part> {
  static final RawPart INSTANCE = new RawPart();

  private RawPart() {
  }

  @Override void apply(RequestBuilder builder, @Nullable MultipartBody.Part value)
      throws IOException {
    if (value != null) { // Skip null values.
      builder.addPart(value);
    }
  }
}
static final class Part<T> extends ParameterHandler<T> {
  private final Headers headers;
  private final Converter<T, RequestBody> converter;

  Part(Headers headers, Converter<T, RequestBody> converter) {
    this.headers = headers;
    this.converter = converter;
  }

  @Override void apply(RequestBuilder builder, @Nullable T value) {
    if (value == null) return; // Skip null values.

    RequestBody body;
    try {
      body = converter.convert(value);
    } catch (IOException e) {
      throw new RuntimeException("Unable to convert " + value + " to RequestBody", e);
    }
    builder.addPart(headers, body);
  }
}

总结

retrofit2一个将工厂模式发挥到极致的优秀库,值得细细体味。它的整个过程可以总结为以下几个步骤:

  1. 对网络请求方式的封装,直接以接口呈现;
  2. 对接口的解析,转换成RequestBuilder,最终转成为okhttp3.Request;
  3. 将Request构造成retrofit2.OkHttpCall,转换成okhttp3.Call执行;
  4. 通过CallAdapter接管Call执行回调,回调中涉及到Response的解析转换等
评论