类型安全的http客户端retrofit介绍、使用、实现原理分析

retrofit介绍

retrofit是一个http访问客户端，类似okhttp、apache httpclient，不过retrofit是类型安全的，也就是定义一个强类型的http客户端接口使用，而不是 请求url返回一个string的结果，再拿string去解析字段，这样开发时更加安全，能帮助开发者省去请求参数结果转换的繁琐重复工作，它的思想类似Mybatis、spring data等。

使用

添加maven依赖

<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>2.9.0</version>
</dependency>
<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>converter-jackson</artifactId>
    <version>2.9.0</version>
</dependency>

定义http接口

Repo是这个接口的返回结果字段对应的model类。

接口方法中的@Get注解表示当前使用Get请求，注解中的参数是请求的uri，支持使用{user}这样的占位符，接口方法中提供@Path("user")注解可以占位符的参数。

public interface GitHubService {
  @GET("users/{user}/repos")
  Call<List<Repo>> listRepos(@Path("user") String user);
}

通过@Query或@QueryMap定义url参数

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);

如果想使用Post方法可以使用@Post注解

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

通过FieldMap传递Map参数

@FormUrlEncoded
@POST("/things")
Call<ResponseBody> things(@FieldMap Map<String, String> fields);

通过@Body传入对象参数，如果我们使用jackson converter 会转成请求中的json request body

@POST("users/new")
Call<User> createUser(@Body User user);

可以通过@Header注解控制request header

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();

可以通过@Multipart和@Part进行文件上传

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

使用定义好的http接口

我们的请求返回要支持json编解码，需要传入一个converterFactory，这里选择JacksonConverterFactory，并且提供一个定制参数的jackson的ObjectMapper

baseUrl定义接口的url前缀，和http接口中的@Get@Post注解中的uri联合起来就是请求的完整url。

base

ObjectMapper objectMapper = new ObjectMapper()
        .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("https://api.github.com/")
        .addConverterFactory(JacksonConverterFactory.create(objectMapper))
        .build();

GitHubService service = retrofit.create(GitHubService.class);

try {
    Call<List<Repo>> test = GitHubService.getInstance().listRepos("test");
    Response<List<Repo>> execute = test.execute();
    List<Repo> githubRepos = execute.body();
    /// 使用返回的结果...
} catch (IOException e) {
    e.printStackTrace();
}

实现原理

看到接口，我们可以联想到jdk里的Proxy代理技术，我们之前的一篇设计和分析Java动态代理的技术实现文章中就降到了Java动态代理的设计思路和具体的实现，感兴趣的朋友可以查看这篇文章。

我们创建http接口时使用的Retrofit.create(final Class<T> service)方法，是通过Jdk的Proxy获取Http接口的运行时代理实现，这个实现的方法会调用代理创建时传入的InvocationHandler。InvocationHandler中对Object里方法、default方法做了特殊处理，详细可以查看注释备注。

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();
          private final Object[] emptyArgs = new Object[0];

          @Override public @Nullable Object invoke(Object proxy, Method method,
              @Nullable Object[] args) throws Throwable {
            // 如果是调用Object类里的方法，比如toString、equals、hashCode这些，直接使用生成的代理对象里的默认实现，也就是Object.class里的实现。
            // If the method is a method from Object then defer to normal invocation.
            if (method.getDeclaringClass() == Object.class) {
              return method.invoke(this, args);
            }

            if (platform.isDefaultMethod(method)) {
              return platform.invokeDefaultMethod(method, service, proxy, args);
            }
            return loadServiceMethod(method).invoke(args != null ? args : emptyArgs);
          }
        });
}

我们在接口中定义的抽象接口方法，会通过loadServiceMethod(method).invoke实现，返回ServiceMethod，也就是注解接口对应的方法信息。 ServiceMethod类的核心方法是abstract @Nullable T invoke(Object[] args);，也就是运行时http接口类被调用时调用到InvocationHandler中委托的调用。 loadServerMethod方法负责解析接口方法生成一个ServiceMethod，并且为了避免重复不必要的解析（重复执行、反射、内存等成本）加了一个 serviceMethodCache。

ServiceMethod<?> loadServiceMethod(Method method) {
    ServiceMethod<?> result = serviceMethodCache.get(method);
    if (result != null) return result;

    synchronized (serviceMethodCache) {
      result = serviceMethodCache.get(method);
      if (result == null) {
        result = ServiceMethod.parseAnnotations(this, method);
        serviceMethodCache.put(method, result);
      }
    }
    return result;
}

parseAnnotations创建了一个RequestFactory对象，做了一些接口返回类型的校验（返回值必须要包含泛型、不能返回void），然后交给HttpServiceMethod.parseAnnotations。 RequestFactory对象负责具体的发送请求，其中封装了对底层的http客户端okhttp的调用。

static <T> ServiceMethod<T> parseAnnotations(Retrofit retrofit, Method method) {
  RequestFactory requestFactory = RequestFactory.parseAnnotations(retrofit, method);

  Type returnType = method.getGenericReturnType();
  if (Utils.hasUnresolvableType(returnType)) {
    throw methodError(method,
        "Method return type must not include a type variable or wildcard: %s", returnType);
  }
  if (returnType == void.class) {
    throw methodError(method, "Service methods cannot return void.");
  }

  return HttpServiceMethod.parseAnnotations(retrofit, method, requestFactory);
}

HttpServiceMethod.parseAnnotations的代码比较多，我们可以整理一下其中要做的事情。

当我们调用retrofit的http接口类时，内部要执行的事情是，准备好相关的请求参数，构建好请求的url，发送http请求，等待http结果， 然后把http返回的结果数据，转换成接口的返回类型。

为代码看起来更清晰，我删除了一些kotlin suspend功能、异常检查等代码。

static <ResponseT, ReturnT> HttpServiceMethod<ResponseT, ReturnT> parseAnnotations(
      Retrofit retrofit, Method method, RequestFactory requestFactory) {
  // 获取方法上的注解
  Annotation[] annotations = method.getAnnotations();
  Type adapterType = method.getGenericReturnType();

  //创建CallAdapter
  CallAdapter<ResponseT, ReturnT> callAdapter =
      createCallAdapter(retrofit, method, adapterType, annotations);
  Type responseType = callAdapter.responseType();
  
  // 创建repsonse对应的converter，Converter能把okhttp的ResponseBody转换成方法返回类型的对象，我们这里使用的是
  Converter<ResponseBody, ResponseT> responseConverter =
      createResponseConverter(retrofit, method, responseType);

  okhttp3.Call.Factory callFactory = retrofit.callFactory;
 
  return new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
}

1. createCallAdapter

createCallAdapter创建一个CallAdapter对象，Call是Retrofit对于http底层访问的抽象，目前默认的实现是OkHttpCall和异步版本的ExecutorCallbackCall。 创建Call对象的类有DefaultCallAdapterFactory，CompletableFutureCallAdapterFactory（针对返回CompletableFuture的接口方法），GuavaCallAdapterFactory（针对返回guava里的ListenableFuture的接口方法）

2. createResponseConverter

createResponseConverter会在所有的ConverterFactory中去找哪个ConverterFactory支持convert当前的类型，找到返回使用。

3. new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);

CallAdapted是对上述数据的封装，最终HttpServiceMethod.invoke调用的时候，会通过创建好一个OkHttpCall，然后传给CallAdapted.adapt方法调用， 编码参数，调用拿到http结果，转换参数返回。

@Override final @Nullable ReturnT invoke(Object[] args) {
  Call<ResponseT> call = new OkHttpCall<>(requestFactory, args, callFactory, responseConverter);
  return adapt(call, args);
}

更多资料

• retrofit官网