v1.0 1st Edition

本文主要说明Retrofit中关于retrofit2.Converter和retrofit2.CallAdapter的相关内容，不可避免的会牵扯到一部分okhttp3和RxJava的内容。

在使用Retrofit的时候首先会对其使用动态代理的方式做http请求的方式非常喜欢，这里个人觉得一是因为用接口做模板非常简洁清晰，其次也正是因为这种原因隐藏了http请求的繁琐步骤，同时也减少了不必要的出错。

其次对于默认的数据转换感觉非常神奇，仅仅是声明一个泛型就可以把http返回转换成对象。并且其拥有非常好的扩展性，特别是对RxJava的支持在第一次用的时候令人印象深刻。

那么接下来开始读代码，如果不关心okhttp的实现那么看Retrofit的源代码，会觉得非常的简洁并且文档注释写的非常详细。

TL;DR

一、总体流程

1
2
3
4
5
Retrofit.Builder builder = new Retrofit.Builder();
...
Retrofit retrofit = builder.build();
...
ExampleServiceTest exampleService = retrofit.create(ExampleServiceTest.class);

Retrofit.java为入口类同时也是核心类，一般使用的时候这个类的对象是由Retrofit.Builder创建的，并且调用Retrofit#create(CLass<t>):T</t>来创建代理对象。

GitHub上rxjava adapter的源代码为1.2，而Gradle依赖库中最新的为2.1.0。这里源码使用2.1.0避免示例代码的正确说明。

Retrofit.jpg

上图为一个非常简单的调用流程，简单来说使用Retrofit#create(class)创建一个代理对象。实际的http请求在调用此代理对象的方法时开始，而这里由calladapter去处理，在这里可以选择执行的方式。

每个代理对象的方法执行的操作与一个指定的ServiceMethod对象一一对应，并且不能动态改变，因为在第一次创建之后其就被缓存下来。在ServiceMethod的初始化中确定三个关键成员CallAdapter、Converter、ParameterHandler，他们分别是调用适配器、数据转换器、参数转换器，这三个对象如何工作在下文进行详细说明。

之后由ServiceMethod中获得的CallAdapter#adapt(OkHttpCall)返回对应的代理方法的返回值Type。

由于当前版本HttpClient使用OKHttpClient，所以核心操作其实上都在retrofit2.OkHttpCall这个类之中，同时其由于持有ServiceMethod实例。因此可以间接的将返回数据经由ServiceMethod传递给Converter进行处理。

接下来针对每个部分做详细说明。

二、Retrofit

虽然这是入口并且提供了很多功能，但是逻辑上并没有过多的说明，更多的是体现在编码上。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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();

        @Override public Object invoke(Object proxy, Method method, Object... args)
            throws Throwable {
          ...
          ServiceMethod serviceMethod = loadServiceMethod(method);
          OkHttpCall okHttpCall = new OkHttpCall<>(serviceMethod, args);
          return serviceMethod.callAdapter.adapt(okHttpCall);
        }
      });
}

java.lang.reflect.Proxy#newProxyInstance接口代理，简单可以理解为在内存中动态的生成一个此接口的子类并实例化它。对于做Java Web的朋友来说这个肯定非常熟悉了，更强的还有ASM这种工具。之后是java.lang.reflect.InvocationHandler在代理对象的方法被调用时InvocationHandler#invoke(...):Object将被回调。正因为如此写一个接口作为清单如此简洁的http请求调用才得以实现。

接下来值得关注的是ServiceMethod，这里可以看到起调用自身的CallAdapter#adapt(OkHttpCall)直接返回了最外层声明的返回值。

1
2
3
4
5
6
7
8
9
10
11
12
//Retrofit#loadServiceMethod
ServiceMethod loadServiceMethod(Method method) {
  ServiceMethod result;
  synchronized (serviceMethodCache) {
    result = serviceMethodCache.get(method);
    if (result == null) {
      result = new ServiceMethod.Builder(this, method).build();
      serviceMethodCache.put(method, result);
    }
  }
  return result;
}

这里是创建并缓存ServiceMethod的代码，可以看出这个对象和调用的方法是一一对应的，并且创建之后会被缓存下来。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//Retrifit.Builder()#build()

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

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

List<CallAdapter.Factory> adapterFactories = new ArrayList<>(this.adapterFactories);
adapterFactories.add(platform.defaultCallAdapterFactory(callbackExecutor));

对于Android平台来说默认的执行器Executor为Handler(Looper.getMainLooper())，使用Handler#post(Runnable)执行线程。这里添加了一个默认的回调适配器DefaultCallAdapterFactory，其中的关键点是返回类型为Call的方法，而其返回的Adapter中更是直接返回Call对象。而这个Call对象就是在Retrofit#create(class)方法中初始化的OkHttpCall。这就是一些默认值，而其他内容则是在代理对象的方法调用时动态确定的。

另外值得注意的是以下几个方法

1
2
3
4
5
6
7
8
9
10
11
public CallAdapter<?> nextCallAdapter(CallAdapter.Factory skip, Type type,
    Annotation[] a) {
  ...
  int start = adapterFactories.indexOf(skipPast) + 1;
  for (int i = start, count = adapterFactories.size(); i < count; i++) {
    CallAdapter<?> adapter = adapterFactories.get(i).get(returnType, annotations, this);
    if (adapter != null) {
      return adapter;
    }
  }
  ...

获取CallAdapter的最终方法，其在ServiceMethod被创建时调用并把返回值储存起来。这里值得注意的是其通过泛型返回值Type和方法注解Annotation[]在所有缓存的Factory中做测试，并将第一个符合条件的返回值返回并结束，同时我们也可以传入一个Factory做排他选项。因此这里为多个回调适配器的使用成为可能，即当http调用情况比较复杂时可以提供多种候选项。同样的Retrofit#nextRequestBodyConverter和Retrofit#stringConverter两个方法非常相似，在此就不过多说明了。

三、ServiceMethod

ServiceMethod就如其名字所说，它主要处理和代理对象方法的相关操作。其必须的两个参数为Retrofit和Method，这可以看出其主要与Retrofit对象做交互。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//ServiceMethod.Builder#build()

callAdapter = createCallAdapter();
responseType = callAdapter.responseType();

responseConverter = createResponseConverter();

parseMethodAnnotation(annotation);

int parameterCount = parameterAnnotationsArray.length;
parameterHandlers = new ParameterHandler<?>[parameterCount];

for (int p = 0; p < parameterCount; p++) {
  Type parameterType = parameterTypes[p];
  ...

  Annotation[] parameterAnnotations = parameterAnnotationsArray[p];
  parameterHandlersp] = parseParameter(p, parameterType, parameterAnnotations);
  
  ...
}
return new ServiceMethod<>(this);

这里的#createCallAdapter():CallAdapter和#createResponseConverter():Converter都是直接调用Retrofit对象中的方法。之后的parseMethodAnnotation主要是处理方法注解中的@GET、@POST等关键字。之后的parseParameter方法是将对应的参数类型转换器和ParameterHandler对象进行关联，用于处理参数的类型转换。并且默认的转换器为BuiltInConverters.ToStringConverter.INSTANCE，其默认直接将参数转换为字符串。

另外值得注意的是方法#toResponse(ResponseBody):T是直接调用内部的responseConverter将ResponseBody转换为方法返回的泛型。#toRequest(Object...):Request方法则是将参数转换为okhttp3的最终请求对象。

四、OkHttpCall

OKHttpCall <t>implements Call</t>其实是对okhttp3.Call的包装，也许是对将来支持更多的底层请求做准备吧(我记得之前的版本确实是支持很多底层实现的)。接下来我们关注一下几个问题：如何发送请求，如何获得返回值，如何解析返回值，返回值是如何转换到方法返回的泛型中。

就如同okhttp3的Call一样，OkHttpCall提供了同样的几个接口。execute():Response同步请求接口，enqueue(Callback<t>)</t>异步回调接口。

1
2
3
4
5
6
7
8
9
10
public Response<T> execute(){
  okhttp3.Call call;
  ...

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

  return parseResponse(call.execute());
}

默认的CallAdapter由于返回retrofit.Call，所以此时我们是直接调用到这里。而通过一些使用我想有些朋友已经感觉到代理对象调用时的返回值是由CallAdapter提供的，因此有些实现可以完全隐藏Call，比如直接返回泛型对象或者返回RxJava中的Observable。

由于http请求底层是由okhttp3提供，它返回是okhttp3.Response，而经过封装之后的retrofit.Call中返回的却是retrofit.Response。其中不仅包括原始的http请求信息，还包括一个我们经过转换之后的泛型T。这里请参加以下代码。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
//retrofit.OkHttpCall

Response<T> parseResponse(okhttp3.Response rawResponse) throws IOException {
    ResponseBody rawBody = rawResponse.body();
    rawResponse = rawResponse.newBuilder()
        .body(new NoContentResponseBody(rawBody.contentType(), rawBody.contentLength()))
        .build();

    int code = rawResponse.code();
    if (code < 200 || code >= 300) {
      try {
        ResponseBody bufferedBody = Utils.buffer(rawBody);
        return Response.error(bufferedBody, rawResponse);
      } finally {
        rawBody.close();
      }
    }

    if (code == 204 || code == 205) {
      return Response.success(null, rawResponse);
    }

    ExceptionCatchingRequestBody catchingBody = new ExceptionCatchingRequestBody(rawBody);
    try {
      T body = serviceMethod.toResponse(catchingBody);
      return Response.success(body, rawResponse);
    } catch (RuntimeException e) {
      ...
    }
}

网络请求的返回是okhttp3.Response，通过以上方法将其转换为retrofit.Response对象。在默认的情况下，要么直接返回返回Response，要么通过retrofit.Call回调返回Response。这里值得注意的是T body = serviceMethod.toResponse(catchingBody)，在上文ServiceMethod中已经很清楚，这里是直接调用缓存的Converter将返回值转换为泛型T并且保存到返回的Response中。所以这里可以很明确的看出我们的转换器只能获得实际对象为ExceptionCatchingRequestBody的返回数据，并将其转换为我们需要的泛型而最终返回的实际上是Response。但是整个外部流程是由CallAdapter控制的，而这个Response最终也是要经过CallAdapter返回。所以实际上我们要做的可以远比从API上看到的多。

从API上来看默认返回retrofit.Call，我们拿到的无论是异步还是同步最终返回的是Response，那么我们是否可以通过重写CallAdapter直接返回T呢？答案自然是肯定的，我在上一篇《Android Retrofit》中简单的说明了一下，即可以通过CallAdapter<t>#adapt(Call<r>):T</r></t>方法直接返回T，这里也是一个R转T的过程，因此我想rxjava的话会更加自然。

五、数据转换器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public interface Converter<F, T> {
  T convert(F value) throws IOException;

  abstract class Factory {
  
    public Converter<ResponseBody, ?> responseBodyConverter(Type t, Annotation[] a,
        Retrofit r)
        ...
  public Converter<?, RequestBody> requestBodyConverter(Type t,
        Annotation[] pa, Annotation[] ma, Retrofit r)
        ...
  public Converter<?, String> stringConverter(Type t, Annotation[] a,
        Retrofit r) 
        
  }
}

以上为转换器接口基本代码，为了篇幅和排版删除了一些类结构。首先对于Converter<f, t="">#convert(F):T</f,>来说，由于结构限制实际我们能做的也仅仅是将泛型F转换为T。但是正因为是两个泛型，实际上它是一个通用接口其作用远远的超过之前的Converter这种转换返回值到我们自定义类型的方式。

框架内部实际上为我们规定的使用方法参见它内部的工厂类Converter.Factory，其提供三个方法。分别是ResponseBody转换为任意类型?，任意类型?转换为RequestBody，任意类型?转换为String。那么在框架内这三个方法的实际调用地方在哪里呢？

  1. responseBodyConverter：ServiceMethod#toResponse(ResponseBody):T，是在OkHttpCall中获得okhttp3.Response之后将其转换为我们定义的泛型T，并重新封装到retrofit.Response中过程被调用的。
  2. requestBodyConverter：ServiceMethod#toRequest(Object ...):okhttp3.Request，是在OkHttpCall中发起http请求前根据我们的代理对象生成请求对象时调用。另外Retrofit封装了httpResponse对象，但是没有封装httpRequest对象。
  3. stringConverter：实际上是在retrofit.ParameterHandler中被多个实例调用。从内部实现来说有Header、Path、Query、QueryMap、HeaderMap、Field、FieldMap、PartMap。这里可以看出这些转换器都是将参数转换为String，而向另外的一些实现，Part、Body是使用的Converter转换器。而这些转换器都是在ServiceMethod#parseMethodAnnotation(Annotation)实例化的，毕竟可能性和情况比较多，这里感觉非常繁杂。

六、调用适配器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public interface CallAdapter<T> {

  Type responseType();

  <R> T adapt(Call<R> call);

  abstract class Factory {

    public abstract CallAdapter<?> get(Type returnType, Annotation[] annotations,
        Retrofit retrofit);

    protected static Type getParameterUpperBound(int index, ParameterizedType type) {
      return Utils.getParameterUpperBound(index, type);
    }
    protected static Class<?> getRawType(Type type) {
      return Utils.getRawType(type);
    }
  }
}

看结构和Converter非常相似，实例也是由工厂对象生成。首先看工厂类方法Factory#get(...):CallAdapter生成一个实例，同样也是根据返回对象的类型和方法方法注解判断是否生成实例，如果返回null则查找下一个注册的Factory。

另外这里提供了两个工具方法Factory#getParameterUpperBound(...):Type，作用是返回参数中的泛型上界。泛型上界简单说就是中后面的V。方法Factory#getRawType(...):Class则是返回原始的类型，比如List则返回List.class。

官方的默认实现为retrofit.DefaultCallAdapterFactory，其中CallAdapter#adapt(Call<r>):Call</r>方法更是直接返回了Call对象。

1
2
3
4
5
public <R> R adapt(Call<R> call) {
  ...
  return call.execute().body();
  ...
}

如上述代码也可以直接返回泛型对象，这里的方法是使用Call进行同步Http请求。其返回的对象为经过我们Converter处理过的retrofit.Response对象，然后使用retrofit.Response#body():R方法返回我们真正想要的对象。然后就是请尽量不要这样写。

RxJava CallAdapter

1
2
3
4
5
Retrofit.Builder builder = new Retrofit.Builder();
builder.addCallAdapterFactory(RxJavaCallAdapterFactory.create());
builder.build();
...
Observable<T> rxQuery();

以上为RxJava调用的基本方式，其返回的基本数据形式为Observable。注意这里和Call是一个意思并没有开始HTTP请求，按照RxJava的规则开始订阅才执行。

之前已经提到无论外面是如何实现，其内部依旧是OkHttpCall执行请求并最终返回retrofit.Response。那么在添加一个RxJavaCallAdapterFactory之后返回值为什么会变成Observable呢？这也是我第一次用RxJava的回调适配器时比较感兴趣的。

首先看适配器的关键方法CallAdapter<t>#adapt(Call<r>):T</r></t>，其实质是一个从R转换到T的过程，当然了这里T可以和R相同。那么来看看官方是如何实现的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public final class RxJavaCallAdapterFactory extends CallAdapter.Factory{
  ...
  public CallAdapter<?> get(Type t, Annotation[] a, Retrofit r) {
    Class<?> rawType = getRawType(returnType);
    String canonicalName = rawType.getCanonicalName();
    boolean isSingle = "rx.Single".equals(canonicalName);
    boolean isCompletable = "rx.Completable".equals(canonicalName);
    if (rawType != Observable.class && !isSingle && !isCompletable) {
      return null;
    }
    if (!isCompletable && !(returnType instanceof ParameterizedType)) {
      throw new IllegalStateException(...)
    if (isCompletable) {
      return CompletableHelper.createCallAdapter(scheduler);
    }
    
    CallAdapter<Observable<?>> callAdapter = getCallAdapter(returnType, scheduler);
    if (isSingle) {
      return SingleHelper.makeSingle(callAdapter);
    }
    return callAdapter;
  }
  ...
}

首先从代码来看其支持Observable、Single和Completable三种返回类型，而且泛型还可以做些文章(这里稍后说明)。那么直接用代码说明，这里的CallAdapter有五个实现。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
static class CompletableCallAdapter implements CallAdapter<Completable>{
  ...
  @Override public Completable adapt(Call call){
    Completable completable = Completable.create(new CompletableCallOnSubscribe(call));
      if (scheduler != null) {
        return completable.subscribeOn(scheduler);
      }
      return completable;
  }
}

static final class ResponseCallAdapter implements CallAdapter<Observable<?>> {
  public <R> Observable<Response<R>> adapt(Call<R> call) {
      Observable<Response<R>> observable = Observable.create(new CallOnSubscribe<>(call));
      if (scheduler != null) {
        return observable.subscribeOn(scheduler);
      }
      return observable;
  }
}

static final class ResultCallAdapter implements CallAdapter<Observable<?>>{
  public <R> Observable<Result<R>> adapt(Call<R> call) {
      Observable<Result<R>> observable = Observable.create(new CallOnSubscribe<>(call))
          .map(new Func1<Response<R>, Result<R>>() {
            @Override public Result<R> call(Response<R> response) {
              return Result.response(response);
            }
          });
          ...
      }
      return observable;
    }
  }
}

static final class SimpleCallAdapter implements CallAdapter<Observable<?>> {
  public <R> Observable<R> adapt(Call<R> call) {
    Observable<R> observable = Observable.create(new CallOnSubscribe<>(call)) //
        .lift(OperatorMapResponseToBodyOrError.<R>instance());
    if (scheduler != null) {
      return observable.subscribeOn(scheduler);
    }
    return observable;
  }
}

new CallAdapter<Single<?>>() {
  ...
  @Override public <R> Single<?> adapt(Call<R> call) {
    Observable<?> observable = callAdapter.adapt(call);
    return observable.toSingle();
  }
}

首先CompletableCallAdapter的内部仅仅是将Observable替换为Completable，而SingleAdapter更是直接使用Observable的回调包装一下将结果转换为Single而已，因此这两个就不多说了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
private CallAdapter<Observable<?>> getCallAdapter(Type t, Scheduler s) {
    Type observableType = getParameterUpperBound(0, (ParameterizedType) returnType);
    Class<?> rawObservableType = getRawType(observableType);
    if (rawObservableType == Response.class) {
      ...
      Type responseType = getParameterUpperBound(0, (ParameterizedType) observableType);
      return new ResponseCallAdapter(responseType, scheduler);
    }

    if (rawObservableType == Result.class) {
      ...
      Type responseType = getParameterUpperBound(0, (ParameterizedType) observableType);
      return new ResultCallAdapter(responseType, scheduler);
    }

    return new SimpleCallAdapter(observableType, scheduler);
}

这是当返回值为Observable时的三种CallAdapter实现。可以看出，这里设计上是支持两种嵌套泛型和一种通常泛型的。分别是Observable<response<t>></response<t>、Observable<result<t>></result<t>和Observable，当然这里的泛型T还可以再次嵌套泛型，这是由Converter决定的。

retrofit2.adapter.rxjava.Result实际上是对retrofit.Response的再次封装，在ResultCallAdapter中直接使用rxjava的map运算符将Response转换为Result(这里map理解为一对一映射就好了)。而ResultCallAdapter中使用了rxjava的lift操作，执行操作为OperatorMapResponseToBodyOrError <t>implements Operator<t, response<t="">></t,></t>，简单理解为将Response解包为T的操作。但是会不会觉得如此明确的操作和转换，各种map和lift简直是多此一举。就目前的实现来说rxjava在控制http请求的时候都是调用的OkHttpCall做同步请求，再使用rxjava自己的线程控制器进行处理。而RxJava更多时候是保证流程和逻辑上的清晰与合理，面对比较单纯的情况确实会感觉反而更复杂了。

到了这里，可以解决上一篇文章提出的疑问使用Observable形式如何获得Http返回信息？这里的回答是将泛型再次包装一层如Observable<response<t>></response<t>和Observable<result<t>></result<t>，这里就可以在RxJava的观察者回调中获得Response和Result进而获得http请求的返回信息。

关于RxJava

关于RxJava使用上其实非常简单，但是逻辑上要说清楚是比较困难。当面对比较复杂的逻辑时也是考验我们对RxJava的理解的时候。随后的文章将从逻辑上和实现上对RxJava进行详细说明。