遵循 Google 应用指南的 Retrofit + Coroutine 封装

2021-06-18
Kotlin Android

前言

Retrofit 从 2.6.0 以后对 Kotlin 协程提供了原生支持，使得异步请求从写法上更像同步调用，配合 Google 出的 Jetpack 全家桶可以使得网络请求更加优雅简单，而且可以完全遵循 Google 给出的应用架构指南。

另外我们有一个更加多样的需求：我们的应用使用了多套服务接口，每套接口返回的参数模板不同，baseUrl 则更多样化，因此带来了更复杂的封装逻辑。

应用架构指南

首先来看一下 Google 给出的应用架构指南：

应用架构

每个组件仅依赖于其下一级的组件，可以避免 Activity 中冗余了大量逻辑，真正让 View 层只进行视图相关处理，可以非常灵活变更上层 UI，数据处理则能够多处复用。

为达成这个架构，就需要将数据请求和初步处理工作封装在 Repository 中，ViewModel 中做请求的发起和将网络请求反序列化后的结果使用 LiveData 交给 View 层进行显示。

了解协程

本文基于协程对 Retrofit 进行封装，所以需要对协程有初步了解。

协程的构成和基本使用

首先看一个最简单的协程例子：

 1GlobalScope.launch(Dispatchers.Main) {
 2    val result = requestNetWork()
 3    updateUI(result)
 4}
 5
 6suspend fun requestNetWork() = withContext(Dispatchers.IO) {
 7    delay(1000)
 8    System.currentTimeMillis().toString()
 9}
10
11fun updateUI(nowTime: String) {
12    textView.text = nowTime
13}

这个例子使用一个 GlobalScope 启动了一个位于主线程的协程，切换到 IO 线程延时了 1 秒来模拟网络请求，然后返回当前时间后自动切回了主线程，最后主线程进行 UI 更新操作。

由此可见协程由如下几部分组成：

  • CoroutineScope（协程作用域）：用于管理协程的启动取消执行范围等。GlobalScope 是 CoroutineScope 的一个单例实现类，不与生命周期组件相关联。
  • CoroutineContext（协程上下文）：协程的配置参数，例如协程名称、工作线程等，使用 plus 运算符相连接。Dispatchers.Main 即为其实现，用于指定主线程运行协程。
  • CoroutineBuilder（协程构建器）：创建和启动协程。launch、async、runBlocking 都是协程构建器。
  • suspend function（挂起函数）：使用 suspend 关键字标识的函数。对调用者声明可能存在耗时操作，挂起函数只能在其他挂起函数内或通过协程构建器调用。

协程的原理和作用

Kotlin 协程从原理上讲，编译器通过 suspend 关键字对函数进行了 CPS（Continuation Passing Style）变换，从而避免了我们手写 CallBack 的繁琐。每个 suspend 函数调用处 Kotlin 称之为“挂起点”，根据“挂起点”将代码分割成不同的代码块，使用状态机对状态的流转而执行不同的代码块来实现“挂起”和“恢复”，规避了 CPS 变换后创建大量 CallBack 对象。

虽然在某种程度上可以简单认为协程是优化版 CallBack 的语法糖，并通过一些库函数帮助我们方便的切换线程。但是它改变了我们进行异步处理的编程方式，以一种同步的方式进行异步处理。

使用 Retrofit

构建 OkHttp

Retrofit 是基于 OkHttp 的封装，所以首先构建 OkHttpClient。此处还可以添加 cookie、user-agent，配置各种拦截器等常规操作，如下仅构建一个简单的 OkHttpClient 作为示例：

 1object HttpClient {
 2    private val okHttpClient: OkHttpClient by lazy {
 3        OkHttpClient.Builder()
 4            .addInterceptor(HttpLoggingInterceptor().apply {
 5                level = if (BuildConfig.DEBUG) {
 6                    HttpLoggingInterceptor.Level.BODY
 7                } else {
 8                    HttpLoggingInterceptor.Level.BASIC
 9                }
10            })
11            .build()
12    }
13}

通过单例和 lazy 委托确保全局只有一个 OkHttpClient 被构建。

构建 Retrofit

遇到的第一个问题就是构建 Retrofit 时 baseUrl 有多个，解决方案多种多样，比如通过拦截器解决、通过 @Url 注解传完整 url 等，我们的解决方案是最常见的——为每个 baseUrl 构建一个 Retrofit 实例，因为虽然有多个 Retrofit 对象，但是如上代码最后发起请求的 OkHttpClient 对象只有一个，所以并不会造成内存方面的担忧。

 1object HttpClient {
 2    private val retrofits = HashMap<String, Retrofit>(8)
 3
 4    fun <S> getService(service: Class<S>, baseUrl: String): S {
 5        return retrofits.getOrPut(baseUrl) {
 6            Retrofit.Builder()
 7                .client(okHttpClient)
 8                .baseUrl(baseUrl)
 9                .addConverterFactory(GsonConverterFactory.create())
10                .build()
11        }.create(service)
12    }
13
14    inline fun <reified S> getService(baseUrl: String): S = getService(S::class.java, baseUrl)
15}

这里我们使用 Gson 作为 json 反序列化库，使用 HashMap 的扩展方法可以方便地获取和缓存 Retrofit 对象，第二个重载方法通过 inline 和 reified 关键字简化了调用方式，后面使用时会有所体现。

声明 ApiService

如果不关心网络状态和服务器状态，可以非常简单粗暴的创建：

1interface ApiService {
2    @GET("home/feed")
3    suspend fun getHomeFeed(@Query("cityId") cityId: Int): HomeFeedDataAndResponse
4}

在函数前面使用 suspend 关键字表示挂起函数，无需使用任何 CallAdapter，Retrofit 在使用协程时支持返回值就是反序列化的实体对象。

发起和处理请求

单一数据模板

每个接口将服务器返回的固定参数都要放到 Bean 中解析十分麻烦，因此可以将服务器的固定参数做成一个固定模板类，变化字段通过泛型来解决。

假设服务器的参数模板如下：

1{
2    "code": 200,
3    "msg": "成功",
4    "data": {}
5}

可以定义一个 XXXResponse 的模板类：

1class XXXResponse<out T>(val code: Int, val msg: String, val data: T) : Serializable {
2    override fun toString(): String {
3        return JSONObject().apply {
4            put("code", code)
5            put("msg", msg)
6            put("data", data)
7        }.toString()
8    }
9}

ApiService 中的返回值也就相应变化为：

1interface ApiService {
2    @GET("home/feed")
3    suspend fun getHomeFeed(@Query("cityId") cityId: Int): XXXResponse<HomeFeedData>
4}

定义 HttpResult

实际开发中 View 层通常需要根据网络和服务器返回值处理各种异常情况，为此我们总结了三种状态。

  • 成功：一切都如我们期待的状态
  • 失败：网络请求成功但是因为业务逻辑错误由后端主动报出的异常状态
  • 错误：因为网络和服务器原因造成的 404、502 或者 DNS 请求失败等错误状态

由此将最终的网络请求结果封装为：

 1sealed class HttpResult<out T : Any> {
 2
 3    data class Success<out T : Any>(val data: T) : HttpResult<T>()
 4    data class Failure(val reason: String) : HttpResult<Nothing>()
 5    data class Error(val exception: Exception) : HttpResult<Nothing>()
 6
 7    override fun toString(): String {
 8        return when (this) {
 9            is Success<*> -> "Success[data=$data]"
10            is Failure -> "Failure[reason=$reason]"
11            is Error -> "Error[exception=$exception]"
12        }
13    }
14}

未使用枚举而选择密封类是因为不同状态下携带的数据类型不同，所以通过密封类来封装这三种状态。

注：其实当只有一个数据模板时 HttpResult 的 Failure 能包装更结构化的数据，此处 reason 为字符串是为了多套数据模板时包装 json 传递更加通用的信息。

发起请求并处理 Response

已经有了后端返回的模板类和最终抛给 View 层的 HttpResult，根据最初的架构分析，需要在 Repository 中进行数据请求和处理将模板类转换成 HttpResult。

1object XXXRepository {
2    suspend fun <T : Any> executeResponse(response: XXXResponse<T>): HttpResult<T> {
3        return if (response.code != 200) {
4            HttpResult.Failure(response.toString())
5        } else {
6            HttpResult.Success(response.data)
7        }
8    }
9}

通过 baseUrl 获取相应的 ApiService，然后发起网络请求：

1object XXXRepository {
2    private val service = HttpClient.getService<ApiService>("http://app.demo.com/")
3
4    suspend fun getHomeFeed(cityId: Int): HttpResult<HomeFeedData> {
5        return executeResponse(service.getHomeFeed(cityId))
6    }
7}

后面请求一旦断网会发现应用崩溃，因为出现网络错误时 Retrofit 会抛出异常，所以需要通过 try-catch 来捕获异常并交给之前预设的 HttpResult.Error。但是每个接口都 try-catch 不但麻烦，而且一旦忘记就可能造成应用崩溃，所以我们可以使用高阶函数来封装调用：

 1object XXXRepository {
 2    private val service = HttpClient.getService<ApiService>("http://app.demo.com/")
 3
 4    suspend fun <T : Any> call(request: suspend () -> XXXResponse<T>): HttpResult<T> {
 5        return try {
 6            executeResponse(request())
 7        } catch (e: Exception) {
 8            HttpResult.Error(e)
 9        }
10    }
11
12    fun <T : Any> executeResponse(response: XXXResponse<T>): HttpResult<T> {
13        return if (response.code != 200) {
14            HttpResult.Failure(response.toString())
15        } else {
16            HttpResult.Success(response.data)
17        }
18    }
19
20    suspend fun getHomeFeed(cityId: Int): HttpResult<HomeFeedData> {
21        return call { service.getHomeFeed(cityId) }
22    }
23}

不同数据模板

如果只有单一数据模板，上面的封装部分就已经完成了，但是我们遇到了第二个问题：数据模板不同。假设我们有第二套不同的固定参数模板如下：

1{
2    "data": {},
3    "error": {}//当业务出现错误时会返回
4}

真实场景中无论是模板还是规则都很复杂，难以糅合成一套模板，所以我们选择每套模板对应一套处理逻辑。根据每套模板定义 XXXResponse 和 YYYResponse ，同时对应 XXXRepository 和 YYYRepository ，相似代码不再赘述。

然后是抽象出公共部分：

 1abstract class BaseRepository {
 2
 3    suspend fun <T : Any> call(request: suspend () -> Any): HttpResult<T> {
 4        return try {
 5            executeResponse(request())
 6        } catch (e: Exception) {
 7            HttpResult.Error(e)
 8        }
 9    }
10
11    abstract fun <T : Any> executeResponse(response: Any): HttpResult<T>
12}

其中 executeResponse 方法是抽象方法，必须被子类实现。最后是各自的实现类：

 1object XXXRepository : BaseRepository() {
 2    @Suppress("UNCHECKED_CAST")
 3    override fun <T : Any> executeResponse(response: Any): HttpResult<T> {
 4        return if ((response as XXXResponse<T>).code != 200) {
 5            HttpResult.Failure(response.toString())
 6        } else {
 7            HttpResult.Success(response.data)
 8        }
 9    }
10}

使用

至此，对于网络请求的封装就结束了，下面看一下如何使用：

在 ViewModel 中调用并使用 LiveData 承载返回结果：

1// ViewModel
2val homeFeed = MutableLiveData<HttpResult<HomeFeedData>>()
3
4fun getHomeFeed(cityId: Int) {
5    return viewModelScope.launch {
6        homeFeed.value = XXXRepository.getHomeFeed(cityId)
7    }
8}

在 View 层调用和观察 LiveData 即可：

 1// Activity
 2viewModel.getHomeFeed(cityId)
 3
 4viewModel.homeFeed.observe(this) { result ->
 5    when (result) {
 6        is HttpResult.Success -> {
 7            Log.d(TAG, "homeFeed Success: ${result.data}")
 8        }
 9        is HttpResult.Failure -> {
10            Log.w(TAG, "homeFeed Failure: ${result.reason}")
11        }
12        is HttpResult.Error -> {
13            Log.e(TAG, "homeFeed Error: ${result.exception}")
14        }
15    }
16}

Tips

在上面我们使用的是 viewModelScope 启动的协程，而非最初使用的 GlobalScope，因为 viewModelScope 可以和 ViewModel 的生命周期相关联，当 ViewModel 调用 clear() 方法时会自动取消协程。使用 viewModelScope 是为了减少样板代码，如果使用自己构造的 CoroutineScope，同样需要在 ViewModel 的 onCleared() 中自行取消协程，否则可能造成内存泄漏。

另外值得注意的一点是，根据 viewModelScope 的源码，协程是在主线程启动的：

1val ViewModel.viewModelScope: CoroutineScope
2        get() {
3            val scope: CoroutineScope? = this.getTag(JOB_KEY)
4            if (scope != null) {
5                return scope
6            }
7            return setTagIfAbsent(JOB_KEY,
8                CloseableCoroutineScope(SupervisorJob() + Dispatchers.Main.immediate))
9        }

但是调用时我们并没有使用 withContext(Dispatchers.IO) 切换到 IO 线程，原因其实来自于 Retrofit 的协程适配实现，虽然看似是同步写法，但是最终实现是调用 enqueue() 进行异步请求，我们熟悉的 enqueue() 是在线程池中完成请求并回调回主线程，可以在主线程调用。

总结

最后总结一下根据应用架构指南封装之后的调用图：

架构调用对照图

根据 Google 的应用架构指南可以做到层次清晰，特别是得益于 ViewModel 和 LiveData 对于生命周期的感知能力，无需主动取消网络请求或者其他方案的解注册却不用担心造成 View 层的内存泄露。协程使得异步请求如同步般使用，在线程池中执行请求并在主线程返回网络请求的结果，所以最后 View 层是在主线程观察的 LiveData，因此无需担心网络请求会阻塞 UI 线程。

除协程之外本文封装也用到了很多 Kotlin 的高级语法，比如：高阶函数、HashMap 的扩展方法、reified 泛型实化、密封类等，这些高级语法让我们的封装和调用都简洁明了了很多。

另外本文主要针对使用 Retrofit 网络请求部分进行封装，根据 Google 的应用架构指南 Repository 中还会使用 Room 进行本地缓存，虽与本文无关而未加入，但是因为分层架构的清晰，很容易加入相关功能。

深入源码排查 FLAG_ACTIVITY_NEW_TASK 导致的 Activity 无法正常启动
时间格式化的趣事：YYYY 示年