Retrofit解密：接口请求是如何适配suspend协程？

携手创作，共同成长！这是我参与「掘金日新计划 · 8 月更文挑战」的第5天，点击查看活动详情

本篇文章主要是带领大家研究retrofit源码一个知识点：如何适配suspend关键字并开启协程执行网络请求的。

最初的retrofit请求

我们先看下原来如何通过retrofit发起一个网络请求的，这里我们直接以官网的例子举例：

动态代理创建请求服务

interface GitHubService {
    //创建get请求方法
    @GET("users/{user}/repos")
    fun listRepos(@Path("user") user: String?): Call<Response>
}

//动态代理创建GitHubService
fun createService(): GitHubService {
    val retrofit = Retrofit.Builder()
        .baseUrl("https://api.github.com/")
        .build()

    return retrofit.create(GitHubService::class.java)
}

retrofit.create底层是通过动态代理创建的GitHubService的一个子实现类；
创建的这个GitHubService一般作为单例进行使用，这里只是简单举例没有实现单例；

发起网络请求

fun main() {
    //异步执行网络请求
    createService().listRepos("").enqueue(object : Callback<Response> {
        override fun onResponse(call: Call<Response>, response: retrofit2.Response<Response>) {
            //主线程网络请求成功回调
        }

        override fun onFailure(call: Call<Response>, t: Throwable) {
            //主线程网络请求失败回调
        }
    })
}

这种调用enqueue()异步方法并执行callback的方式是不是感觉很麻烦，如果有下一个请求依赖上一个请求的执行结果，那就将会形成回调地狱这种可怕场景。

而协程suspend本就有着以同步代码编写执行异步操作的能力，所以天然是解决回调地狱好帮手。接下来我们看下如何使用协程suspend。

借助`suspend`发起网络请求

suspend声明接口方法

interface GitHubService {
    @GET("users/{user}/repos")
    suspend fun listRepos(@Path("user") user: String?): Response<String>
}

可以看到就是在listRepos方法声明前加了个suspend关键字就完了。

创建协程执行网络请求

fun main() {
    //1.创建协程作用域，需要保证协程的调度器是分发到主线程执行
    val scope = MainScope()
    scope.launch(CoroutineExceptionHandler { _, _ ->
        //2.捕捉请求异常
    }) {
        //3.异步执行网络请求
        val result = createService().listRepos("")
        
        val content = result.body()?
    }
}

首先创建一个协程作用域，需要保证协程调度器类型为Dispatchers.Main，这样整个协程的代码块都会默认在主线程中执行，我们就可以直接在里面执行UI相关操作
创建一个CoroutineExceptionHandler捕捉协程执行过程中出现的异常，这个捕捉异常的粒度比较大，是捕捉整个协程块的异常，可以考虑使用try-catch专门捕获网络请求执行的异常：
```
//异步执行网络请求
try {
    val result = createService().listRepos("")
} catch (e: Exception) {
    //可以考虑执行重连等逻辑或者释放资源
}
```
直接调用listRepos()方法即可，不需要传入任何回调，并直接返回方法结果。这样我们就实现了以同步的代码实现了异步网络请求。

接下来我们就看下如何retrofit源码是如何实现这一效果的。

`retrofit`如何适配`suspend`

直接定位到HttpServiceMethod.parseAnnotations()方法：

static <ResponseT, ReturnT> HttpServiceMethod<ResponseT, ReturnT> parseAnnotations(
    Retrofit retrofit, Method method, RequestFactory requestFactory) {
  //1.判断是否为suspend挂起方法
  boolean isKotlinSuspendFunction = requestFactory.isKotlinSuspendFunction;

  //省略一堆和当前分析主题不想关的代码

  if (!isKotlinSuspendFunction) {
    return new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
  } else if (continuationWantsResponse) {
    //挂起执行
    return (HttpServiceMethod<ResponseT, ReturnT>) new SuspendForResponse<>();
  } else {
    //挂起执行
    return (HttpServiceMethod<ResponseT, ReturnT>) new SuspendForBody<>();
  }
}

1.判断是否为suspend挂起方法

看下requestFactory.isKotlinSuspendFunction赋值的地方，经过一番查找（省略...），最终方法在RequestFactory的parseParameter间接赋值：

private @Nullable ParameterHandler<?> parseParameter() {
//...
    //1.是否是方法最后一个参数
    if (allowContinuation) {
      try {
        if (Utils.getRawType(parameterType) == Continuation.class) {
          //2.标识为suspend挂起方法
          isKotlinSuspendFunction = true;
          return null;
        }
      } catch (NoClassDefFoundError ignored) {
      }
    }
}

如果一个方法被声明为suspend，该方法翻译成java代码就会给该方法添加一个Continuation类型的参数，并且放到方法参数的最后一个位置，比如：

private suspend fun test66(name: String) {  
}

会被翻译成：

private final Object test66(String name, Continuation $completion) {
   return Unit.INSTANCE;
}

所以上面的代码就可以判断出请求的接口方法是否被suspend声明，是isKotlinSuspendFunction将会被置为true。

2.挂起则创建`SuspendForResponse`或`SuspendForBody`

这个地方我们以SuspendForBody进行分析，最终会执行到其adapt()方法：

@Override
protected Object adapt(Call<ResponseT> call, Object[] args) {
  call = callAdapter.adapt(call);
  //1.获取参数
  Continuation<ResponseT> continuation = (Continuation<ResponseT>) args[args.length - 1];
  
  try {
    return isNullable
        ? KotlinExtensions.awaitNullable(call, continuation)
        //2.调用真正的挂起方法
        : KotlinExtensions.await(call, continuation);
  } catch (Exception e) {
    return KotlinExtensions.suspendAndThrow(e, continuation);
  }
}

获取调用的suspend声明的接口方法中获取最后一个Continuation类型参数
调用await方法，由于这是一个kotlin定义的接收者为Call的挂起方法，如果在java中调用，首先第一个参数要传入接收者，也就是call，其实await()是一个挂起方法，翻译成java还会增加一个Continuation类型参数，所以调用await()还要传入第一步获取的Continuation类型参数。

3.核心调用`await()`方法探究

await()就是retrofit适配suspend实现同步代码写异步请求的关键，也是消除回调地狱的关键：

suspend fun <T : Any> Call<T>.await(): T {
  return suspendCancellableCoroutine { continuation ->
    continuation.invokeOnCancellation {
      cancel()
    }
    enqueue(object : Callback<T> {
      override fun onResponse(call: Call<T>, response: Response<T>) {
        if (response.isSuccessful) {
          val body = response.body()
          if (body == null) {
              //关键
            continuation.resumeWithException(KotlinNullPointerException())
          } else {
              //关键
            continuation.resume(body)
          }
        } else {
            //关键
          continuation.resumeWithException(HttpException(response))
        }
      }

      override fun onFailure(call: Call<T>, t: Throwable) {
          //关键
        continuation.resumeWithException(t)
      }
    })
  }
}

使用到了协程的一个非常关键的方法suspendCancellableCoroutine{}，该方法就是用来捕获传入的Continuation并决定什么恢复挂起的协程执行的，比如官方的delay()方法也是借助该方法实现的。

所以当我们执行调用enqueue()方法时在网络请求没有响应(成功或失败)前，协程一直处于挂起的状态，之后收到网络响应后，才会调用resume()或resumeWithException()恢复挂起协程的执行，这样我们就实现了同步代码实现异步请求的操作，而不需要任何的callback嵌套地狱。

总结

本篇文章详细分析retrofit如何适配suspend协程的，并且不用编写任何的callback回调，直接以同步代码编写实现异步请求的操作。

Retrofit解密：接口请求是如何适配suspend协程？

最初的retrofit请求

动态代理创建请求服务

发起网络请求

借助suspend发起网络请求

suspend声明接口方法

创建协程执行网络请求

retrofit如何适配suspend

1.判断是否为suspend挂起方法

2.挂起则创建SuspendForResponse或SuspendForBody

3.核心调用await()方法探究

总结

借助`suspend`发起网络请求

`retrofit`如何适配`suspend`

2.挂起则创建`SuspendForResponse`或`SuspendForBody`

3.核心调用`await()`方法探究