Retrofit 进阶：Converter 的原理及使用【附 R
现在大多数的网络请求框架都是使用 Retrofit，本篇文章根据 Retrofit 中，Flowable 创建 和 OkhttpCall 执行，来说明 Convert 的使用。本篇文章根据 Body 如何进行 convert 的介绍，如果有需要对Path，Header 等 进行 convert 操作，可以根据 ParameterHandler 和 RequestBuilder 等源码，进行更改。
目录：
一、什么是 Converter？
二、什么时候进行 convert？（包含：Flowable 创建；ParameterHandler 介绍；OkHttpCall 执行）
三、为什么使用 Converter ？
四、与拦截器有什么区别？
五、怎么使用 Converter？
六、那些年踩过的坑
一、什么是 Converter？
Converter 是将对象与它们在 HTTP 中的表示进行转换，实例是在 Factory 中被创建的。
Converter.Factory 是一个抽象类，其中有三个方法，用于创建 Converter：
public Converter<ResponseBody, ?> responseBodyConverter(Type type, Annotation[] annotations, Retrofit retrofit) {
return null;
}
public Converter<?, RequestBody> requestBodyConverter(Type type, Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {
return null;
}
public Converter<?, String> stringConverter(Type type, Annotation[] annotations, Retrofit retrofit) {
return null;
}
二、什么时候进行 convert？
Retrofit 的请求流程
1）Flowable 创建时序图
图1 Flowable 创建时序图
说明：
1、每次进行网络请求操作，调用自定义 HTTP API 的方法时，实际上调用的是 HttpServiceMethod 的 invoke 方法。
2、ServiceMethod 中 parseAnnotations 是对方法进行解析。
3、RequestFactory 的 parseMethodAnnotation 是方法的注解进行解析。
4、RequestFactory 的 parseParameter 是对每一个参数进行解析，并且返回一个ParameterHandler。
2）ParameterHandler 是什么？
RequestFactory parseParameter 方法中遍历每一个参数，并调用 parseParameterAnnotation 方法，对该参数的所有注解进行遍历，根据 Retrofit 规定的参数注解：例如 @Path，@Body，@Field 等，返回一个 ParameterHandler。
问题1. stringConverter 和 requestBodyConverter 有什么区别？
parseParameterAnnotation 方法里，根据不同的参数注解，调用 Retrofit 的 requestBodyConverter 和 stringConverter 方法。其中只有@Body和 @Part、@PartMap 使用的 requestBodyConverter。
问题2. 添加了多个 Converter.Factory 将如何执行?
以 Retrofit 的 stringConverter 方法为例。遍历 converterFactories 根据参数类型，参数注解数组，返回第一个不为空的 Converter。
public <T> Converter<T, String> stringConverter(Type type, Annotation[] annotations) {
checkNotNull(type, "type == null");
checkNotNull(annotations, "annotations == null");
for (int i = 0, count = converterFactories.size(); i < count; i++) {
Converter<?, String> converter = converterFactories.get(i).stringConverter(type, annotations, this);
if (converter != null) { //noinspection unchecked
return (Converter<T, String>) converter;
}
}
}
因此，使用哪个 Converter 是根据添加 Converter.Factory 的顺序查找，第一个匹配对应处理的 Converter。
抽象类 ParameterHandler 有一个抽象方法 apply。在子类实现中调用了 converter.convert(value)。
abstract class ParameterHandler<T> {
abstract void apply(RequestBuilder builder, @Nullable T value) throws IOException;
}
实现 ParameterHandler 的子类：
图2 ParameterHandler子类
3）OkHttpCall 执行时序图
图3 OkHttpCall 时序图
说明：
1、RequestFactory 的 create方法，通过 RequestBuilder 返回了一个 Request。
2、RealCall 的 getResponseWithInterceptorChain 是 HTTP 请求，拦截器链条，因此这里也是拦截器的处理。
3、OkHttpCall 的 parseResponse 方法中，执行了 responseConverter.convert(catchingBody);
4）Request 的创建
RequestFactory 的 create 方法：
okhttp3.Request create(Object[] args) throws IOException {
@SuppressWarnings("unchecked") // It is an error to invoke a method with the wrong arg types.
ParameterHandler<Object>[] handlers = (ParameterHandler<Object>[]) parameterHandlers;
int argumentCount = args.length;
if (argumentCount != handlers.length) {
throw new IllegalArgumentException("Argument count (" + argumentCount+ ") doesn't match expected count (" + handlers.length + ")");
}
RequestBuilder requestBuilder = new RequestBuilder(httpMethod, baseUrl, relativeUrl, headers, contentType, hasBody, isFormEncoded, isMultipart);
List<Object> argumentList = new ArrayList<>(argumentCount);
for (int p = 0; p < argumentCount; p++) {
argumentList.add(args[p]);
handlers[p].apply(requestBuilder, args[p]);
}
return requestBuilder.get().tag(Invocation.class, new Invocation(method, argumentList)).build();
}
1、创建 RequestBuilder 对象。
2、遍历参数，对每个参数调用对应的 ParameterHandler 的 apply 方法，会调用对应的 Converter 的 convert 方法。
3、调用 RequestBuilder 的 get 方法，对参数进行组装。
4、创建 Request 对象。
RequestBuilder 的 get 方法：
Request.Builder get() {
//...
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]);
}
}
//...
}
图4 body赋值 对应注解
三、为什么使用 Converter ？
Converter 是将对象与它们在 HTTP 中的表示进行转换，并且是在线程中处理的。对于调用对象来讲，只需要关注传递的参数，以及返回的对象。参数如何组装，转换成 HTTP 请求的参数，加密解密，并不需要关注。
四、与拦截器有什么区别？
图5 客户端到服务器的请求流程
拦截器是对 OkHttpClient 与服务器之间的 HTTP 请求进行拦截，处理。
Converter 是 Retrofit 对于请求的对象和返回的 Body 等进行转换。
五、怎么使用 Converter？
1）三个方法说明：
override fun stringConverter(type: Type, annotations: Array<Annotation>, retrofit: Retrofit): Converter<*, String>?
说明：stringConverter 方法
参数：
type：参数的类型，通过 getRawType(type) 方法得到声明类型的 Class
annotations：参数的注解数组
返回：
Converter<*, String>：返回 null 则 Retrofit 继续读取下一个 Factory
override fun requestBodyConverter(type: Type, parameterAnnotations: Array<Annotation>, methodAnnotations: Array<Annotation>, retrofit: Retrofit): Converter<*, RequestBody>?
说明：requestBodyConverter 方法
参数：
type：参数的类型，通过 getRawType(type) 方法得到声明类型的 Class
parameterAnnotations：参数的注解数组
methodAnnotations：方法的注解数组
返回：
Converter<*, RequestBody>：返回 null 则 Retrofit 继续读取下一个 Factory
override fun responseBodyConverter(type: Type, annotations: Array<Annotation>, retrofit: Retrofit): Converter<ResponseBody, *>?
说明：responseBodyConverter 方法
参数：
type：返回值类型，通过 getRawType(type) 方法得到声明类型的 Class
annotations：方法的注解数组
返回：
Converter<ResponseBody, *>：返回 null 则 Retrofit 继续读取下一个 Factory
2）自定义步骤：
1、创建 Converter.Factory ，重写三个获取 Converter 的方法。
2、新建需要处理的注解。
3、对于参数的类型，参数的注解数组，返回一个 Converter 处理。
4、添加到 Retrofit.Builder 中，addConverterFactory ，注意添加顺序会影响获取的 Converter。
六、那些年踩过的坑
1、ParameterHandler 的 apply 方法对于 value 值的判断，例如：Field，当 value 为空时直接 return，不会处理 stringConverter。
2、Part 中的 Header 是写死的，如果需要传递文件名，需要额外处理。
Headers headers = Headers.of("Content-Disposition", "form-data; name=\"" + partName + "\"", "Content-Transfer-Encoding", part.encoding());
