一，使用方式
1.添加依赖，当前使用2.9.0版本，源码分析也基于此版本
dependencies {
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
}
2.使用官方Demo，获取retrofit的信息
class MainActivity : AppCompatActivity() {
val API_URL = "https://api.github.com"
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
//1.创建Retrofit实例
val retrofit = Retrofit.Builder()
.baseUrl(API_URL)
.addConverterFactory(GsonConverterFactory.create())
.build()
//2.创建GitHub的实例
val github = retrofit.create(GitHub::class.java)
//3.调用方法返回Call
val call: Call<List<Contributor>> = github.contributors("square", "retrofit")
//4.开始请求网络
call.enqueue(object : Callback<List<Contributor>> {
override fun onFailure(call: Call<List<Contributor>>, t: Throwable) {
println("onFailure")
}
override fun onResponse(
call: Call<List<Contributor>>,
response: Response<List<Contributor>>
) {
for (contributor in response.body()!!) {
println(contributor.login + " (" + contributor.contributions + ")")
}
}
})
}
}
class Contributor(val login: String, val contributions: Int)
interface GitHub {
@GET("/repos/{owner}/{repo}/contributors")
fun contributors(
@Path("owner") owner: String,
@Path("repo") repo: String
): Call<List<Contributor>>
}
二，创建Retrofit实例
使用建造者模式创建Retrofit实例，传入baseUrl，添加数据转换器和请求适配器工厂。构建Retrofit的方法放在Builder的build方法中。如果不配置请求的实际工具，则会使用OkHttpClient来实际发起请求。这里也会根据具体的平台来添加调度器。这里使用Demo的是Android平台，后面也默认使用该平台。会添加2个默认的请求转换器CompletableFutureCallAdapterFactory和DefaultCallAdapterFactory。添加默认的数据转换器BuiltInConverters，OptionalConverterFactory和我们自己添加的GsonConverterFactory
public final class Retrofit {
//Github这个类中所用方法的信息的缓存。
private final Map<Method, ServiceMethod<?>> serviceMethodCache = new ConcurrentHashMap<>();
//实际发起请求call的工厂，默认使用OkHttpClient
final okhttp3.Call.Factory callFactory;
//基地址
final HttpUrl baseUrl;
//数据转换器集合
final List<Converter.Factory> converterFactories;
//请求适配器集合
final List<CallAdapter.Factory> callAdapterFactories;
//请求完成后回调主线程的调度器
final @Nullable Executor callbackExecutor;
//是否要急切的验证请求方法，开启则会马上加载所有方法。一般不用
final boolean validateEagerly;
public static final class Builder {
public Retrofit build() {
if (baseUrl == null) {
throw new IllegalStateException("Base URL required.");
}
okhttp3.Call.Factory callFactory = this.callFactory;
//默认OkHttpClient
if (callFactory == null) {
callFactory = new OkHttpClient();
}
//这里会加载Android平台的调度器
Executor callbackExecutor = this.callbackExecutor;
if (callbackExecutor == null) {
callbackExecutor = platform.defaultCallbackExecutor();
}
//添加默认的请求适配器
List<CallAdapter.Factory> callAdapterFactories = new ArrayList<>(this.callAdapterFactories);
callAdapterFactories.addAll(platform.defaultCallAdapterFactories(callbackExecutor));
List<Converter.Factory> converterFactories =
new ArrayList<>(
1 + this.converterFactories.size() + platform.defaultConverterFactoriesSize());
//添加默认的数据转换器
converterFactories.add(new BuiltInConverters());
converterFactories.addAll(this.converterFactories);
converterFactories.addAll(platform.defaultConverterFactories());
return new Retrofit(
callFactory,
baseUrl,
unmodifiableList(converterFactories),
unmodifiableList(callAdapterFactories),
callbackExecutor,
validateEagerly);
}
三，创建“GitHub”的实例
val github = retrofit.create(GitHub::class.java)
通过动态代理来创建Github实例。动态代理原理不清晰可以阅读参考文章。通过Debug模式也能了解动态代理的机制，通过下图可以看出系统帮我们生成了一个名为Proxy3的类，它继承自Proxy，实现了GitHub这个接口。在我们调用方法时就会先执行InvocationHandler的invoke方法。
动态代理.png
public <T> T create(final Class<T> 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);
}
args = args != null ? args : emptyArgs;
return platform.isDefaultMethod(method) //接口中的default方法
? platform.invokeDefaultMethod(method, service, proxy, args)
: loadServiceMethod(method).invoke(args); //一般方法使用该方法加载
}
});
}
四，调用方法返回Call
1.loadServiceMethod
val call: Call<List<Contributor>> = github.contributors("square", "retrofit")
上面分析到通过代理模式生成了github这个实例，具体对象为Proxy3,在它调用contributors时会执行InvocationHandler的invoke方法。所以在这会调用loadServiceMethod方法然后在调用invoke返回。loadServiceMethod方法主要作用是将Method转为ServiceMethod对象并缓存起来。
ServiceMethod<?> loadServiceMethod(Method method) {
ServiceMethod<?> result = serviceMethodCache.get(method);
if (result != null) return result;
synchronized (serviceMethodCache) {
result = serviceMethodCache.get(method);
if (result == null) {
//解析method
result = ServiceMethod.parseAnnotations(this, method);
serviceMethodCache.put(method, result);
}
}
return result;
}
abstract class ServiceMethod<T> {
static <T> ServiceMethod<T> parseAnnotations(Retrofit retrofit, Method method) {
RequestFactory requestFactory = RequestFactory.parseAnnotations(retrofit, method);
....
return HttpServiceMethod.parseAnnotations(retrofit, method, requestFactory);
}
abstract @Nullable T invoke(Object[] args);
}
2.RequestFactory
通过RequestFactory来解析方法的注解参数等，首先也是通过构建者模式创建RequestFactory。
- 首先通过
parseMethodAnnotation解析注解，获取它的HTTP方法类型，HTTP的Header，HTTP地址相对路径，需要填充的地址绝对值，是否有body等信息。 - 通过
ParameterHandler的parseParameter来解析参数的注解，这里使用的是Path，2个参数都有注解，则会创建2个ParameterHandler.Path放进parameterHandlers中来记录参数的注解信息 - 信息记录完毕返回
RequestFactory对象
final class RequestFactory {
static RequestFactory parseAnnotations(Retrofit retrofit, Method method) {
return new Builder(retrofit, method).build();
}
//请求的方法
private final Method method;
private final HttpUrl baseUrl;
final String httpMethod;
private final @Nullable String relativeUrl;
private final @Nullable Headers headers;
private final @Nullable MediaType contentType;
private final boolean hasBody;
private final boolean isFormEncoded;
private final boolean isMultipart;
private final ParameterHandler<?>[] parameterHandlers;
final boolean isKotlinSuspendFunction;
static final class Builder {
final Retrofit retrofit;
final Method method;
//方法的注解数组（可能有多个注解）
final Annotation[] methodAnnotations;
//方法参数的注解数组（每个参数都可能有多个注解）
final Annotation[][] parameterAnnotationsArray;
//方法参数类型的数组
final Type[] parameterTypes;
//方法类型如GET
@Nullable String httpMethod;
boolean hasBody;
boolean isFormEncoded;
boolean isMultipart;
//相对地址如/repos/{owner}/{repo}/contributors
@Nullable String relativeUrl;
@Nullable Headers headers;
@Nullable MediaType contentType;
//方法注解上需要填写的参数的名称
@Nullable Set<String> relativeUrlParamNames;
@Nullable ParameterHandler<?>[] parameterHandlers;
//是否为kotlin的suspend方法
boolean isKotlinSuspendFunction;
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);
}
3.HttpServiceMethod
-
kotlin的suspend方法判断 - 获取适配的类型也就就方法的返回类型
- 找到一个请求适配器
CallAdapter，规则是在前面声明的请求适配器中找到一个能够处理这个返回类型的CallAdapter，所以这里方法声明返回Call，则会使用系统添加的DefaultCallAdapterFactory来处理，方法声明用RXJava来处理，则需要添加一个RXJava的适配器CallAdapter。
static <ResponseT, ReturnT> HttpServiceMethod<ResponseT, ReturnT> parseAnnotations(
Retrofit retrofit, Method method, RequestFactory requestFactory) {
boolean isKotlinSuspendFunction = requestFactory.isKotlinSuspendFunction;
boolean continuationWantsResponse = false;
boolean continuationBodyNullable = false;
Annotation[] annotations = method.getAnnotations();
Type adapterType;
//是否为kotlin的suspend方法
if (isKotlinSuspendFunction) {
Type[] parameterTypes = method.getGenericParameterTypes();
Type responseType =
Utils.getParameterLowerBound(
0, (ParameterizedType) parameterTypes[parameterTypes.length - 1]);
if (getRawType(responseType) == Response.class && responseType instanceof ParameterizedType) {
responseType = Utils.getParameterUpperBound(0, (ParameterizedType) responseType);
continuationWantsResponse = true;
} else {
}
adapterType = new Utils.ParameterizedTypeImpl(null, Call.class, responseType);
annotations = SkipCallbackExecutorImpl.ensurePresent(annotations);
} else {//不是kotlin方法则获取方法的返回类型
adapterType = method.getGenericReturnType();
}
//找到一个合适的CallAdapter，很重要。
CallAdapter<ResponseT, ReturnT> callAdapter =
createCallAdapter(retrofit, method, adapterType, annotations);
//方法的实际返回类型。真正能使用的类型
Type responseType = callAdapter.responseType();
//找到一个合适的数据转换器Converter，和createCallAdapter类似
Converter<ResponseBody, ResponseT> responseConverter =
createResponseConverter(retrofit, method, responseType);
okhttp3.Call.Factory callFactory = retrofit.callFactory;
if (!isKotlinSuspendFunction) {
return new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
} else if (continuationWantsResponse) {
//noinspection unchecked Kotlin compiler guarantees ReturnT to be Object.
return (HttpServiceMethod<ResponseT, ReturnT>)
new SuspendForResponse<>(
requestFactory,
callFactory,
responseConverter,
(CallAdapter<ResponseT, Call<ResponseT>>) callAdapter);
} else {
//noinspection unchecked Kotlin compiler guarantees ReturnT to be Object.
return (HttpServiceMethod<ResponseT, ReturnT>)
new SuspendForBody<>(
requestFactory,
callFactory,
responseConverter,
(CallAdapter<ResponseT, Call<ResponseT>>) callAdapter,
continuationBodyNullable);
}
}
4.createCallAdapter分析
HttpServiceMethod.java
private static <ResponseT, ReturnT> CallAdapter<ResponseT, ReturnT> createCallAdapter(
Retrofit retrofit, Method method, Type returnType, Annotation[] annotations) {
try {
//noinspection unchecked
return (CallAdapter<ResponseT, ReturnT>) 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.java
public CallAdapter<?, ?> callAdapter(Type returnType, Annotation[] annotations) {
return nextCallAdapter(null, returnType, annotations);
}
//从callAdapterFactories列表里找到一个适合处理这个method的CallAdapter
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++) {
//匹配的原则就是这个CallAdapter要能处理这个返回类型
CallAdapter<?, ?> adapter = callAdapterFactories.get(i).get(returnType, annotations, this);
if (adapter != null) {
return adapter;
}
}
5.createResponseConverter分析
和createCallAdapter类似
HttpServiceMethod.java
private static <ResponseT> Converter<ResponseBody, ResponseT> createResponseConverter(
Retrofit retrofit, Method method, Type responseType) {
Annotation[] annotations = method.getAnnotations();
try {
return retrofit.responseBodyConverter(responseType, annotations);
} catch (RuntimeException e) { // Wide exception range because factories are user code.
throw methodError(method, e, "Unable to create converter for %s", responseType);
}
}
Retrofit.java
public <T> Converter<ResponseBody, T> responseBodyConverter(Type type, Annotation[] annotations) {
return nextResponseBodyConverter(null, type, annotations);
}
public <T> Converter<ResponseBody, T> nextResponseBodyConverter(
@Nullable Converter.Factory skipPast, Type type, Annotation[] annotations) {
Objects.requireNonNull(type, "type == null");
Objects.requireNonNull(annotations, "annotations == null");
int start = converterFactories.indexOf(skipPast) + 1;
for (int i = start, count = converterFactories.size(); i < count; i++) {
Converter<ResponseBody, ?> converter =
converterFactories.get(i).responseBodyConverter(type, annotations, this);
if (converter != null) {
//noinspection unchecked
return (Converter<ResponseBody, T>) converter;
}
}
6. loadServiceMethod(method).invoke(args)分析
ServiceMethod执行invoke方法时，会执行HttpServiceMethod的invoke方法，然后创建一个OkHttpCall，经过adapt方法后Call会被包装为ExecutorCallbackCall类型。然后返回此对象。ExecutorCallbackCall的作用在与包装OkHttpCall，把它的返回结果放到主线程。
HttpServiceMethod.java
final @Nullable ReturnT invoke(Object[] args) {
Call<ResponseT> call = new OkHttpCall<>(requestFactory, args, callFactory, responseConverter);
return adapt(call, args);
}
CallAdapted.java
@Override
protected ReturnT adapt(Call<ResponseT> call, Object[] args) {
return callAdapter.adapt(call);
}
DefaultCallAdapterFactory.java
public @Nullable CallAdapter<?, ?> get(
Type returnType, Annotation[] annotations, Retrofit retrofit) {
if (getRawType(returnType) != Call.class) {
return null;
}
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) {
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()) {
// Emulate OkHttp's behavior of throwing/delivering an IOException on
// cancellation.
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));
}
});
}
五，开始请求网络
1.enqueue
call.enqueue(object : Callback)
在前面分析到，此Call是ExecutorCallbackCall对象，delegate则是OkHttpCall对象，调用enqueue入队，则会调用OkHttpCall的enqueue方法
OkHttpCall.java
public void enqueue(final Callback<T> callback) {
Objects.requireNonNull(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
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) {
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
}
}
});
}
2.createRawCall，创建一个Okhttp的Request和Okhttp的Call
OkHttpCall.java
private okhttp3.Call createRawCall() throws IOException {
okhttp3.Call call = callFactory.newCall(requestFactory.create(args));
if (call == null) {
throw new NullPointerException("Call.Factory returned null.");
}
return call;
}
RequestFactory.java
//创建Request
okhttp3.Request create(Object[] args) throws IOException {
ParameterHandler<Object>[] handlers = (ParameterHandler<Object>[]) parameterHandlers;
int argumentCount = args.length;
RequestBuilder requestBuilder =
new RequestBuilder(
httphMethod,
baseUrl,
relativeUrl,
headers,
contentType,
hasBody,
isFormEncoded,
isMultipart);
if (isKotlinSuspendFunction) {
// The Continuation is the last parameter and the handlers array contains null at that index.
argumentCount--;
}
List<Object> argumentList = new ArrayList<>(argumentCount);
for (int p = 0; p < argumentCount; p++) {
argumentList.add(args[p]);
上面分析的这里是处理Path注解的handler
handlers[p].apply(requestBuilder, args[p]);
}
把拼好的url，header，httphMethod，contentType等各种信息转为Request对象
return requestBuilder.get().tag(Invocation.class, new Invocation(method, argumentList)).build();
}
ParameterHandler.Path
@Override
void apply(RequestBuilder builder, @Nullable T value) throws IOException {
if (value == null) {
throw Utils.parameterError(
method, p, "Path parameter \"" + name + "\" value must not be null.");
}
builder.addPathParam(name, valueConverter.convert(value), encoded);
}
RequestBuilder.java
把url上{}的用参数替换，完成真正url的拼装
void addPathParam(String name, String value, boolean encoded) {
if (relativeUrl == null) {
// The relative URL is cleared when the first query parameter is set.
throw new AssertionError();
}
String replacement = canonicalizeForPath(value, encoded);
String newRelativeUrl = relativeUrl.replace("{" + name + "}", replacement);
if (PATH_TRAVERSAL.matcher(newRelativeUrl).matches()) {
throw new IllegalArgumentException(
"@Path parameters shouldn't perform path traversal ('.' or '..'): " + value);
}
relativeUrl = newRelativeUrl;
}
3.parseResponse解析结果
用前面找好的responseConverter来将body转换为想要的类型。
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;
}
}
六，总结
使用到的设计模式
- 构建者模式：Retrofit创建
- 外观模式：Retrofit类提供了整个系统的入口
- 代理模式：（service接口的创建）
- 工厂模式 （GsonConverterFactory.create()）
- 策略模式 （到底选择那种Converter，Adapter）
- 适配器模式 ：adapt方法将OkHttpCall适配为ExecutorCallbackCall
本文参考
用大白话讲Java动态代理的原理
