Retrofit 2.x上传文件的两种方式及源码分析

古月有三木
1,347 阅读4分钟

A 使用@Part注解

@Multipart
@POST("update/img")
Call<ResponseBody> postImg(@Part("param1") RequestBody param1, @Part MultipartBody.Part img);

构造请求数据时采用如下方式：

RequestBody requestFile = RequestBody.create(img, MediaType.parse("image/jpeg"));
// MultipartBody.Part is used to send also the actual filename
MultipartBody.Part img = MultipartBody.Part.createFormData("img", img.getName(), requestFile);

RequestBody param1 = RequestBody.create("param1", null);

Call<ResponseBody> call = service.postImg(param1, body);

如果是多文件：

@Multipart
@POST("update/img")
Call<ResponseBody> postImg(@Part("param1") RequestBody param1, @Part MultipartBody.Part[] imgs);
// Call<ResponseBody> postImg(@Part("param1") RequestBody param1, @Part List<MultipartBody.Part> imgs);

构造请求数据时传数组/List即可。

B 使用@Body注解

@POST("update/img")
Call<ResponseBody> postImg(@Body RequestBody requestBody);

注意：此处不能添加@Multipart或@FormUrlEncoded注解，不然会报错。

构造请求数据时采用如下方式：

MultipartBody.Builder builder = new MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart("param1","param1")
    	.addFormDataPart("img", img.getName(), RequestBody.create(img, MediaType.parse("image/jpeg")));

postImg(builder.build());

如果是多文件，接口注解不变，在添加文件时在继续执行addFormDataPart即可。

实际应用中，两种方式效果完全相同，那么，这两种方式在实现上有什么区别吗？

源码分析

Retrofit解析注解的步骤如下：

  1. 解析方法注解；
  2. 解析参数和参数注解。

RequestFactory类中解析方法注解部分代码如下：

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

观察代码，发现如果方法注解中含有Multipart，则另isMultipart为true。

下面我们来观察RequestFactory类中解析参数注解的部分代码：

  1. 对@Part的解析

    首先会根据isMultipart判断方法是否含有Multipart注解，没有注解就报错：

    if (!isMultipart) {
  throw parameterError(
      method, p, "@Part parameters can only be used with multipart encoding.");
}

    然后得到@Part的值，对于@Part的值有以下几种可能。

    • @Part值为空，此时认为参数类型必须为Multipart.body、Multipart.body数组或Iterable类型，如果不为以上三者，则报异常：

      throw parameterError(
      method,
      p,
      "@Part annotation must supply a name or use MultipartBody.Part parameter type.");

    • @Part值为空，参数类型为Multipart.body:

      if (MultipartBody.Part.class.isAssignableFrom(rawParameterType)) {
   return ParameterHandler.RawPart.INSTANCE;
}

    • @Part值为空，参数类型为Iterable：

      if (Iterable.class.isAssignableFrom(rawParameterType)) { 
   if (!(type instanceof ParameterizedType)) {
     throw parameterError(
         method,
         p,
         rawParameterType.getSimpleName()
             + " must include generic type (e.g., "
             + rawParameterType.getSimpleName()
             + "<String>)");
   }
   ParameterizedType parameterizedType = (ParameterizedType) type;
   Type iterableType = Utils.getParameterUpperBound(0, parameterizedType); 
   if (!MultipartBody.Part.class.isAssignableFrom(Utils.getRawType(iterableType))) {
     throw parameterError(
         method,
         p,
         "@Part annotation must supply a name or use MultipartBody.Part parameter type.");
   }
   return ParameterHandler.RawPart.INSTANCE.iterable();
}

      这里首先判断泛型是否确定类型，然后判断泛型类型是否为MultipartBody.Part。

    • @Part值为空，参数类型为Array：

      if (rawParameterType.isArray()) {
   Class<?> arrayComponentType = rawParameterType.getComponentType();
   if (!MultipartBody.Part.class.isAssignableFrom(arrayComponentType)) {
     throw parameterError(
         method,
         p,
         "@Part annotation must supply a name or use MultipartBody.Part parameter type.");
   }
   return ParameterHandler.RawPart.INSTANCE.array();
}

    • @Part值不为空，参数类型为MultipartBody.Part，则报错

      if (MultipartBody.Part.class.isAssignableFrom(rawParameterType)) {
    throw parameterError(
        method,
        p,
        "@Part parameters using the MultipartBody.Part must not "
        + "include a part name in the annotation.");
}

    • @Part值不为空，参数类型不为MultipartBody.Part。

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

  2. 对@PartMap的解析

    同@Part，首先会根据isMultipart判断方法是否含有Multipart注解，没有注解就报错。

    接着获取参数类型。

    • 判断参数类型是否为Map，不是则报错。

      if (!Map.class.isAssignableFrom(rawParameterType)) {
    throw parameterError(method, p, "@PartMap parameter type must be Map.");
}

    • 判断Map是否指定泛型类型，未指定则报错。

      if (!(mapType instanceof ParameterizedType)) {
   throw parameterError(
       method, p, "Map must include generic types (e.g., Map<String, String>)");
}

    • 判断Map键类型是否为String，不是则报错。

      if (String.class != keyType) {
  throw parameterError(method, p, "@PartMap keys must be of type String: " + keyType);
}

    • 判断Map值类型是否为Multipart.body，是则报错。

      if (MultipartBody.Part.class.isAssignableFrom(Utils.getRawType(valueType))) {
  throw parameterError(
      method,
      p,
      "@PartMap values cannot be MultipartBody.Part. "
          + "Use @Part List<Part> or a different value type instead.");
}

  3. 对@Body的解析

    首先会判断是否方法注解是否包含@FormUrlEncoded和@Multipart注解，有则报错。

    if (isFormEncoded || isMultipart) {
  throw parameterError(
      method, p, "@Body parameters cannot be used with form or multi-part encoding.");
}

    然后调用转换器，尝试将数据转换为RequestBody。

    Converter<?, RequestBody> converter;
try {
  converter = retrofit.requestBodyConverter(type, annotations, methodAnnotations);
} catch (RuntimeException e) {
  // Wide exception range because factories are user code.
  throw parameterError(method, e, p, "Unable to create @Body converter for %s", type);
}
gotBody = true;
return new ParameterHandler.Body<>(method, p, converter);

解析成功之后，会将数据传至ParameterHandler类进一步解析，下面让我们看看该类做了什么。

  1. 对于@Part注解，涉及到ParameterHandler.Part和ParameterHandler.RawPart内部类，其中当@Part值不为空时，使用Part类解析，否则使用RawPart解析。

  2. 对于@PartMap注解，使用ParameterHandler.Part进行解析。

  3. 对于@Body注解，使用ParameterHandler.Body进行解析。

他们都含有一个共同的方法：

Part

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 Utils.parameterError(method, p, "Unable to convert " + value + " to RequestBody", e);
  }
  builder.addPart(headers, body);
}

PartMap

void apply(RequestBuilder builder, @Nullable Map<String, T> value) throws IOException {
  if (value == null) {
    throw Utils.parameterError(method, p, "Part map was null.");
  }

  for (Map.Entry<String, T> entry : value.entrySet()) {
    String entryKey = entry.getKey();
    if (entryKey == null) {
      throw Utils.parameterError(method, p, "Part map contained null key.");
    }
    T entryValue = entry.getValue();
    if (entryValue == null) {
      throw Utils.parameterError(
          method, p, "Part map contained null value for key '" + entryKey + "'.");
    }

    okhttp3.Headers headers =
        okhttp3.Headers.of(
            "Content-Disposition",
            "form-data; name=\"" + entryKey + "\"",
            "Content-Transfer-Encoding",
            transferEncoding);

    builder.addPart(headers, valueConverter.convert(entryValue));
  }
}

RawPart

void apply(RequestBuilder builder, @Nullable MultipartBody.Part value) {
  if (value != null) { // Skip null values.
    builder.addPart(value);
  }
}

Body

void apply(RequestBuilder builder, @Nullable T value) {
    if (value == null) {
      throw Utils.parameterError(method, p, "Body parameter value must not be null.");
    }
    RequestBody body;
    try {
      body = converter.convert(value);
    } catch (IOException e) {
      throw Utils.parameterError(method, e, p, "Unable to convert " + value + " to RequestBody");
    }
    builder.setBody(body);
  }
}

我们只关系builder.addPart和builder.setBody方法。

  • 查看addPart方法源码，该方法在RequestBuilder类中：

    private @Nullable MultipartBody.Builder multipartBuilder;

void addPart(Headers headers, RequestBody body) {
  multipartBuilder.addPart(headers, body);
}

void addPart(MultipartBody.Part part) {
  multipartBuilder.addPart(part);
}

    对于RawPart类型，将采用addPart(MultipartBody.Part part)方法，对于Part类型，将采用addPart(Headers headers, RequestBody body)方法。然后，我们查看MultipartBody.Builder中的addPart方法为：

    fun addPart(part: Part) = apply {
  parts += part
}

  • 查看setBody源码

    private @Nullable RequestBody body;

void setBody(RequestBody body) {
  this.body = body;
}

  • 获得Request.Builder方法

    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]);
    }
  }

  ...
}

    在该方法中，首先判断body是否为空，如果为空则调用formBuilder或multipartBuilder创建一个body。

  • 最后，我们再看一下MultipartBody.Builder中的addFormDataPart方法

    fun addFormDataPart(name: String, filename: String?, body: RequestBody) = apply {
  addPart(Part.createFormData(name, filename, body))
}

fun addFormDataPart(name: String, value: String) = apply {
  addPart(Part.createFormData(name, value))
}

    可以看出最终还是调用了addPart方法。

    fun addPart(part: Part) = apply {
  parts += part
}

分析到这里，我们可以明白，原来两种上传文件方式只是表达方式不同，实际上都会调用MultipartBody.Builder的build方法创建RequetBody，只不过第一种方式创建是交给了Retrofit中的RequestBuilder类，而第二种是由我们自己调用MultipartBody.Builder的build方法创建而已。

avatar
文章
阅读
粉丝