一、简单使用
具体使用流程和方法说明详见：使用教程
简单的代码示例：
//步骤1：创建接口类
public interface WanAndroidService {
@GET("article/list/{index}/json")
Call<JsonObject> getArticles(@Path("index") int index);
}
//步骤2:构建Retrofit实例
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://wanandroid.com/")
.addConverterFactory(GsonConverterFactory.create())
.build();
//步骤3:通过Retrofit.create方法创建接口类的代理对象
WanAndroidService wanAndroidService = retrofit.create(WanAndroidService.class);
//步骤4:调用接口代理对象方法返回Call类实例或者其他自定义请求类
Call<JsonObject> articles = wanAndroidService.getArticles(0);
//步骤5:调用Call类实例的同步或者异步请求方法，发起网络请求（.body()方法为获取请求成功后返回的实体数据对象）
JsonObject body = articles.execute().body();
二、原理分析
2.1、创建接口对象
2.1.1、源码
步骤1和2比较简单，创建接口类，然后根据实际的情况构建Retrofit类实例即可
源码分析从步骤3Retrofit.create方法开始：
public <T> T create(final Class<T> service) {
//校验是否接口是否存在类型变量，存在则抛出异常
//如果Retrofit实例设置了立即校验，会先解析注解，将结果保存到缓存中备用（详解loadServiceMethod方法分析）
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类，则调用Object类方法的默认实现，不做任何处理.
if (method.getDeclaringClass() == Object.class) {
return method.invoke(this, args);
}
args = args != null ? args : emptyArgs;
//isDefaultMethod(method)，判断是否是java8并且是默认实现方法
//如果是，则直接调用方法实现，不做任何处理
return platform.isDefaultMethod(method)
? platform.invokeDefaultMethod(method, service, proxy, args)
//请求方法真正的调用逻辑
: loadServiceMethod(method).invoke(args);
}
});
}
2.1.2、总结
通过JDK动态代理技术生成我们定义请求接口的代理对象。
接口方法的调用最终会调用到
InvocationHandler的invoke方法。invoke方法内部接口是否合法（非泛型接口），并且不是Object的方法，接口方法也不存在默认实现（JAVA8开始支持），则最终调用
loadServiceMethod(method).invoke(args);方法开始解析封装网络请求。
2.2、接口方法调用
按照2.1的结论，接口方法的调用最终会调用到loadServiceMethod(method).invoke(args);方法，具体源码分析如下：
2.2.1、源码
loadServiceMethod(method)
a. 解析注解，生成ServiceMethod对象（loadServiceMethod(method)）
ServiceMethod<?> loadServiceMethod(Method method) {
//先从缓存获取，缓存获取到直接返回
ServiceMethod<?> result = serviceMethodCache.get(method);
if (result != null) return result;
synchronized (serviceMethodCache) {
//double check 再检查一次缓存
result = serviceMethodCache.get(method);
if (result == null) {
//开始解析方法注解，生成ServiceMethod对象
result = ServiceMethod.parseAnnotations(this, method);
//缓存该方法对应的ServiceMethod解析结果，下次请求可以直接从缓存获取
serviceMethodCache.put(method, result);
}
}
return result;
}
b. 解析注解，返回ServiceMethod对象（ServiceMethod.parseAnnotations(this, method)）
static <T> ServiceMethod<T> parseAnnotations(Retrofit retrofit, Method method) {
//生成RequestFactory对象，创建实例的同时会解析注解获取网络请求数据，解析的同时会校验各个注解的合法性（比如请求方法注解必须是默认GET/POST/...等等校验）
RequestFactory requestFactory = RequestFactory.parseAnnotations(retrofit, method);
//获取返回参数类型
Type returnType = method.getGenericReturnType();
//校验返回参数类型，类型不能为以下类型：
//1、类型变量类型(T,E等等)、通配符表达式、
//2、参数类型<>中的参数类型不能存在类型变量或者通配符(即可以是List<String>、不能是List<T>或者List<?>、
//3、泛型数组类型元素类型也不能存在类型变量或者通配符类型)
if (Utils.hasUnresolvableType(returnType)) {
throw methodError(
method,
"Method return type must not include a type variable or wildcard: %s",
returnType);
}
//返回类型也不能是void.class
if (returnType == void.class) {
throw methodError(method, "Service methods cannot return void.");
}
//校验通过调用HttpServiceMethod的parseAnnotations方法解析注解
return HttpServiceMethod.parseAnnotations(retrofit, method, requestFactory);
}
c. 继续解析注解，返回HttpServiceMethod对象（HttpServiceMethod.parseAnnotations(this, method, requestFactory)）
//关键代码
static <ResponseT, ReturnT> HttpServiceMethod<ResponseT, ReturnT> parseAnnotations(
Retrofit retrofit, Method method, RequestFactory requestFactory) {
......
boolean continuationWantsResponse = false;
boolean continuationBodyNullable = false;
Annotation[] annotations = method.getAnnotations();
Type adapterType;
if (isKotlinSuspendFunction) {
......
} else {
//获取方法的返回参数类型
adapterType = method.getGenericReturnType();
}
//创建请求适配器（内部通过CallAdpater.Factory创建，如果不自定义，并且方法返回值是Call；则使用DefaultCallAdapterFactory创建CallAdapter；可以通过Retrofit配置新增Factory改变默认行为）
CallAdapter<ResponseT, ReturnT> callAdapter =
createCallAdapter(retrofit, method, adapterType, annotations);
Type responseType = callAdapter.responseType();
......
//创建响应数据转换器(流程类似请求适配器创建)
Converter<ResponseBody, ResponseT> responseConverter =
createResponseConverter(retrofit, method, responseType);
okhttp3.Call.Factory callFactory = retrofit.callFactory;
if (!isKotlinSuspendFunction) {
//返回CallAdapted实例，传递的参数说明：
//1、requestFactory：内部保存注解解析到的请求方法，请求参数，URL等等数据；
//2、callFactory：即OkHttpClient；
//3、responseConverter：数据解析转换器；
//4、callAdapter：请求适配器，可以自定义实现线程切换等逻辑，Android默认适配器功能是将异步请求响应回调切换到主线程)
return new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
} else if (continuationWantsResponse) {
......
} else {
......
}
}
默认的DefaultCallAdapterFactory请求适配器创建工厂源码如下：
final class DefaultCallAdapterFactory extends CallAdapter.Factory {
private final @Nullable Executor callbackExecutor;
//如果是Android 默认传入的是Platform.MainThreadExecutor实例（可以通过Retrofit配置修改）
DefaultCallAdapterFactory(@Nullable Executor callbackExecutor) {
this.callbackExecutor = callbackExecutor;
}
@Override
public @Nullable CallAdapter<?, ?> get(
Type returnType, Annotation[] annotations, Retrofit retrofit) {
//返回值类型不为Call.class，则返回null
if (getRawType(returnType) != Call.class) {
return null;
}
//检查返回参数类型
if (!(returnType instanceof ParameterizedType)) {
throw new IllegalArgumentException(
"Call return type must be parameterized as Call<Foo> or Call<? extends Foo>");
}
//获取Call<xxx>，xxx参数对应的类型
final Type responseType = Utils.getParameterUpperBound(0, (ParameterizedType) returnType);
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) {
//如果是Android，最终会调用到ExecutorCallbackCall里，JAVA不做处理
return executor == null ? call : new ExecutorCallbackCall<>(executor, call);
}
};
}
static final class ExecutorCallbackCall<T> implements Call<T> {
final Executor callbackExecutor;
final Call<T> delegate;
ExecutorCallbackCall(Executor callbackExecutor, Call<T> delegate) {
this.callbackExecutor = callbackExecutor;
this.delegate = delegate;
}
@Override
public void enqueue(final Callback<T> callback) {
Objects.requireNonNull(callback, "callback == null");
delegate.enqueue(
new Callback<T>() {
@Override
public void onResponse(Call<T> call, final Response<T> response) { //切换线程（默认是切换到主线程）
callbackExecutor.execute(
() -> {
if (delegate.isCanceled()) {
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(() -> callback.onFailure(ExecutorCallbackCall.this, t));
}
});
}
@Override
public boolean isExecuted() {
return delegate.isExecuted();
}
@Override
public Response<T> execute() throws IOException {
return delegate.execute();
}
......
}
}
ServiceMehod.invoke(Object args)
接上一步，loadServiceMethod(method)返回的是个HttpServerMethod子类的实例，invoke具体实现在HttpServerMethod中，源码如下：
@Override
final @Nullable ReturnT invoke(Object[] args) {
//创建OkHttpCall实例
Call<ResponseT> call = new OkHttpCall<>(requestFactory, args, callFactory, responseConverter);
//调用adapt方法，Java最终会调用到CallAdapted的adapt方法中（Kotlin类似稍微有点区别），最终会调用callAdapter的adapt方法，源码如下
return adapt(call, args);
}
protected abstract @Nullable ReturnT adapt(Call<ResponseT> call, Object[] args);
static final class CallAdapted<ResponseT, ReturnT> extends HttpServiceMethod<ResponseT, ReturnT> {
private final CallAdapter<ResponseT, ReturnT> callAdapter;
CallAdapted(
RequestFactory requestFactory,
okhttp3.Call.Factory callFactory,
Converter<ResponseBody, ResponseT> responseConverter,
CallAdapter<ResponseT, ReturnT> callAdapter) {
super(requestFactory, callFactory, responseConverter);
this.callAdapter = callAdapter;
}
@Override
protected ReturnT adapt(Call<ResponseT> call, Object[] args) {
//callAdapter如上一步所述，默认情况下Android平台返回的是ExecutorCalbackCall(内部默认实现仅是将异步请求返回回调切回主线程)，当然我们可以通过配置callbackExecutor和新增自定义callAdapter的方式改变返回值或者默认行为
return callAdapter.adapt(call);
}
}
2.2.2、总结
1、loadServiceMethod(method).invoke(args);调用结束，默认情况下返回的是一个OKHttpCall的实例（Android 平台返回的是ExecutorCalbackCall，它是OKHttpCall实例的装饰器，扩展了OKHttpCall异步请求回调处理逻辑）。
2、可以通过Retrofit.Builder的callbackExecutor方法设置异步回调处理器的方式改变ExecutorCalbackCall默认切换异步请求回调至主线程的行为。
3、可以通过Retrofit.Builder的addCallAdapterFactory方法，新增适配器工厂，改变和扩展方法返回值以及方法执行，异步请求回调线程切换等逻辑。
4、Retrofit+RxJava的模式，就是通过上述3的方式，新增适配器工厂，从而达到改变方法返回值，扩展功能的目的。
2.3、发起网络请求
接上面2.2逻辑，返回的是OkHttpCall(Android平台默认ExecutorCalbackCall仅仅是个装饰器，最终方法调用也会调用到OkHttpCall里面)
（如果新增了CallAdapter，改变了返回值，最终还是需要调用到OkHttpCall方法来实现网络请求，流程和默认行为类似）
2.3.1、源码
同步请求
Call.execute() 方法
@Override
public Response<T> execute() throws IOException {
okhttp3.Call call;
synchronized (this) {
//一个Call只能执行一次，否则抛出一次
if (executed) throw new IllegalStateException("Already executed.");
executed = true;
//获取okhttp3.Call实例，通过callFactory和requestFactory创建
//最终会调用OkHttpClient.newCall(Request request)方法创建okhttp3.Call实例
call = getRawCall();
}
if (canceled) {
call.cancel();
}
//最终调用okhttp3.Call的execute方法发起同步请求
//parseResponse解析响应数据
return parseResponse(call.execute());
}
2.3.2、异步请求
Call.enqueue(final Callback\<T> callback) 方法
@Override
public void enqueue(final Callback<T> callback) {
Objects.requireNonNull(callback, "callback == null");
okhttp3.Call call;
Throwable failure;
synchronized (this) {
//一个Call只能执行一次请求
if (executed) throw new IllegalStateException("Already executed.");
executed = true;
call = rawCall;
failure = creationFailure;
if (call == null && failure == null) {
try {
//获取okhttp3.Call实例，通过callFactory和requestFactory创建
//最终会调用OkHttpClient.newCall(Request request)方法创建okhttp3.Call实例
call = rawCall = createRawCall();
} catch (Throwable t) {
throwIfFatal(t);
failure = creationFailure = t;
}
}
}
if (failure != null) {
callback.onFailure(this, failure);
return;
}
if (canceled) {
call.cancel();
}
//调用okhttp3.Call的enqueue异步方法发起异步请求
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) {
throwIfFatal(t);
t.printStackTrace(); // TODO this is not great
}
}
@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) {
throwIfFatal(t);
t.printStackTrace(); // TODO this is not great
}
}
});
}
解析数据
OkHttpCall.parseResponse(okhttp3.Response rawResponse)方法
Response<T> parseResponse(okhttp3.Response rawResponse) throws IOException {
ResponseBody rawBody = rawResponse.body();
// 删除请求体主体数据，以便后面使用无主体数据的Response传递响应结果
rawResponse =
rawResponse
.newBuilder()
.body(new NoContentResponseBody(rawBody.contentType(), rawBody.contentLength()))
.build();
int code = rawResponse.code();
//判断请求状态码
if (code < 200 || code >= 300) {
//非200，请求失败
try {
//缓存错误响应主体数据
ResponseBody bufferedBody = Utils.buffer(rawBody);
//生成Retrofit的Response实例并返回
return Response.error(bufferedBody, rawResponse);
} finally {
rawBody.close();
}
}
if (code == 204 || code == 205) {
rawBody.close();
//204，205判断响应体没有主体内容，直接返回成功无数据的Retrofit.Response实例
return Response.success(null, rawResponse);
}
//使用Okio.buffer读取响应体主体数据到ExceptionCatchingResponseBody（ResponseBody的子类）实例中
ExceptionCatchingResponseBody catchingBody = new ExceptionCatchingResponseBody(rawBody);
try {
//解析主体数据，返回我们需要的数据实体对象
T body = responseConverter.convert(catchingBody);
//返回成功有数据的Retrofit.Response实例
return Response.success(body, rawResponse);
} catch (RuntimeException e) {
catchingBody.throwIfCaught();
throw e;
}
}
2.3.2、总结
广告请求最终会调用到
okhttp3.Call的同步或者异步方法。通过
OkHttpCall.parseResponse方法解析okhttp3.Call请求返回的okhttp3.Response响应数据。最后会调用responseConverter.convert（转换器的转换方法）解析转换不同的数据结构。可以通过
Retrofit.Builder的addConverterFactory的方法，新增数据转换器，支持解析不同的数据结构。解析数据之后，会将响应结果，成功数据实体或者失败数据包装成
Retrofit.Response的实例返回。可以通过Retrofit.Response类的code()或者isSuccessful()方法判断是否成功。通过body()方法获取请求成功状态下的返回的数据实体（可能为空）。如果不新增ConverterFactory，默认情况只能返回
okhttp3.ResponseBody类的对象实例。即Retrofit.Response.body()获取的实例只能是okhttp3.ResponseBody类的对象(java8+也可以是Optional)，同时定义接口方法的返回值实际参数类型只能是okhttp3.ResponseBody.class。
三、最后总结
Retrofit框架让开发者可以通过接口注解的方式描述网络请求，然后通过JDK动态代理的方式真正实现接口方法调用逻辑。方法的调用会对接口注解进行解析，最后将网络请求解析结果和相关配置封装到
OkHttpCall中。OkHttpCall调用方法开始网络请求，最终还是会调用okHttp3.call类中的同步或者异步请求方法，实现真正的网络请求（即网络请求的实现还是通过OkHttp框架实现的）。CallAdapter数据请求适配器是为了扩展OkHttpCall的功能，最后还是会通过OkHttpCall来组织网络请求。ConverAdapter数据转换器的作用是在请求成功之后，将数据结构转换成我们想要是实体对象。
