1、前言
Hello，各位小伙伴，又見面了，回首過去，RxHttp 就要迎來一周年生日了(19年4月推出)，這一年，走過來真心....真心不容易，代碼維護、寫文章、寫文檔等等，經常都是干到零點之后，也是我首次花費大部分業余時間來維護一個開源項目，全程一個人維護，要知道，網絡請求庫不同於其它開源項目，各位同僚對這類項目的要求都非常高，而且前面有一座大山Retrofit，如何在這種情況下，殺出重圍？那就只有死磕細節，做到人無我有，人有我精。
幸運的是，RxHttp它做到了，截止本文發表，在Github上，已達到1600+star，在RxHttp&RxLife交流群（群號：378530627，經常會有技術交流，歡迎進群）也有了300+人，這次，RxHttp 更新到了2.x版本，給大家帶來不一樣的協程體驗，為啥不一樣？看完本文你會有答案
本文僅介紹RxHttp + 協程的使用，更多功能請查看
RxHttp 完美適配Android 10/11 上傳/下載/進度監聽
gradle依賴
1、必選
//使用kapt依賴rxhttp-compiler時必須
apply plugin: 'kotlin-kapt'
android {
//必須，java 8或更高
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
dependencies {
implementation 'com.ljx.rxhttp:rxhttp:2.5.2'
implementation 'com.squareup.okhttp3:okhttp:4.9.0' //rxhttp v2.2.2版本起，需要手動依賴okhttp
kapt 'com.ljx.rxhttp:rxhttp-compiler:2.5.2' //生成RxHttp類，純Java項目，請使用annotationProcessor代替kapt
}
2、可選
android {
defaultConfig {
javaCompileOptions {
annotationProcessorOptions {
arguments = [
rxhttp_package: 'rxhttp', //非必須，指定RxHttp類包名
//傳入你依賴的rxjava版本，可傳入rxjava2、rxjava3，依賴RxJava時必須
rxhttp_rxjava: 'rxjava3'
]
}
}
}
}
dependencies {
implementation 'com.ljx.rxlife:rxlife-coroutine:2.0.1' //管理協程生命周期，頁面銷毀，關閉請求
//rxjava2 (RxJava2/Rxjava3二選一，使用asXxx方法時必須)
implementation 'io.reactivex.rxjava2:rxjava:2.2.8'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'
implementation 'com.ljx.rxlife2:rxlife-rxjava:2.0.0' //管理RxJava2生命周期，頁面銷毀，關閉請求
//rxjava3
implementation 'io.reactivex.rxjava3:rxjava:3.0.6'
implementation 'io.reactivex.rxjava3:rxandroid:3.0.0'
implementation 'com.ljx.rxlife3:rxlife-rxjava:3.0.0' //管理RxJava3生命周期，頁面銷毀，關閉請求
//非必須，根據自己需求選擇 RxHttp默認內置了GsonConverter
implementation 'com.ljx.rxhttp:converter-fastjson:2.5.2'
implementation 'com.ljx.rxhttp:converter-jackson:2.5.2'
implementation 'com.ljx.rxhttp:converter-moshi:2.5.2'
implementation 'com.ljx.rxhttp:converter-protobuf:2.5.2'
implementation 'com.ljx.rxhttp:converter-simplexml:2.5.2'
}
本文只介紹RxHttp + 協程用法，如果你想了解RxHttp + RxJava的用法，請閱讀RxHttp 讓你眼前一亮的Http請求框架一文
如果你現在對協程還一知半解，沒有關系，那是因為你還沒有找到運用場景，而網絡請求正是一個很好的切入場景，本文會教你如何優雅，並且安全的開啟協程，以及用協程處理多任務，用着用着你就會了。
2、RxHttp 協程使用
2.1、請求三部曲
用過RxHttp的同學知道，RxHttp發送任意請求皆遵循請求三部曲，如下：
代碼表示
//Kotlin 協程
val str = RxHttp.get("/service/...") //第一步，確定請求方式，可以選擇postForm、postJson等方法
.toStr() //第二步，確認返回類型，這里代表返回String類型
.await() //第三步，使用await方法拿到返回值
//RxJava
RxHttp.get("/service/...") //第一步，確定請求方式，可以選擇postForm、postJson等方法
.asString() //第二步，使用asXXX系列方法確定返回類型
.subscribe(s -> { //第三步, 訂閱觀察者
//成功回調
}, throwable -> {
//失敗回調
});
注: await()是suspend掛斷方法，需要在另一個suspend方法或協程環境中調用
協程請求三部曲詳解
-
第一步，選擇
get、postForm、postJson等方法來確定請求方式，隨后便可通過add、addFile、addHeader等方法來添加參數、文件、請求頭等信息 -
第二步，調用
toXxx系列方法來確定返回類型，常用的有toStr、toClass、toList，隨后便可調用asFlow、retry、timeout、flowOn、filter、distinct、sort等30余個操作符來執行不同的業務邏輯，本文后續會一一介紹 -
第三步，最后，只需調用
await、tryAwait、awaitResult這三個中的任一操作符獲取返回值即可，這一步，需要在協程環境中才能調用
接着，如果我們要獲取一個Student對象或者List<Student>集合對象等等任意數據類型，也是通過await()方法，如下：
//Student對象
val student = RxHttp.get("/service/...")
.toClass<Student>()
.await()
//List<Student> 對象
val students = RxHttp.get("/service/...")
.toClass<List<Student>>()
.await()
注：toClass()方法是萬能的，你可以傳遞任意數據類型過去
以上就是RxHttp在協程中最常規的操作，掌握請求三部曲，就掌握了RxHttp了精髓
2.2、BaseUrl處理
RxHttp通過@DefaultDomain、@Domain注解來配置默認域名及非默認域名，如下：
public class Url {
@DefaultDomain //通過該注解設置默認域名
public static String BASE_URL = "https://www.wanandroid.com";
// name 參數在這會生成 setDomainToGoogleIfAbsent方法，可隨意指定名稱
// className 參數在這會生成RxGoogleHttp類，可隨意指定名稱
@Domain(name = "Google", className = "Google")
public static String GOOGLE = "https://www.google.com";
}
以上配置www.wanandroid.com為默認域名，www.google.com為非默認域名
多BaseUrl處理
//使用默認域名發請求
RxHttp.get("/service/...")
.toSrt().await()
//使用google域名方式一：傳入的url直接帶上google域名
RxHttp.get("https://wwww.google.com/service/...")
.toSrt().await()
//使用google域名方式二：調用setDomainToGoogleIfAbsent方法
RxHttp.get("/service/...")
.setDomainToGoogleIfAbsent()
.toSrt().await()
//使用google域名方式三：直接使用RxGoogleHttp類發送請求
RxGoogleHttp.get("/service/...")
.toSrt().await()
注意：手動傳入的域名優先級別最高，其次是調用setDomainToXxx方法，最后才會使用默認域名
動態域名處理
//直接對url重新賦值即可，改完立即生效
Url.BASE_URL = "https://www.baidu.com";
RxHttp.get("/service/...")
.toSrt().await()
//此時請求的url為 https://www.baidu.com/service/...
2.3、業務code統一判斷
我想大部分人的接口返回格式都是這樣的
class Response<T> {
var code = 0
var msg : String? = null
var data : T
}
拿到該對象的第一步就是對code做判斷，如果code != 200(假設200代表數據正確)，就會拿到msg字段給用戶一些錯誤提示，如果等於200，就拿到data字段去更新UI，常規的操作是這樣的
val response = RxHttp.get("/service/...")
.toClass<Response<Student>>()
.await()
if (response.code == 200) {
//拿到data字段(Student)刷新UI
} else {
//拿到msg字段給出錯誤提示
}
試想一下，一個項目少說也有30+個這樣的接口，如果每個接口讀取這么判斷，就顯得不夠優雅，也可以說是災難，相信也沒有人會這么干。而且對於UI來說，只需要data字段即可，錯誤提示啥的我管不着。
那有沒有什么辦法，能直接拿到data字段，並且對code做出統一判斷呢？有的，直接上代碼
val student = RxHttp.get("/service/...")
.toResponse<Student>() //調用此方法，直接拿到data字段，也就是Student對象
.await()
//直接開始更新UI
可以看到，這里調用了toResponse()方法，就直接拿到了data字段，也就是Student對象。
此時，相信很多人會有疑問，
-
業務code哪里判斷的？
-
業務code非200時，msg字段怎么拿到？
為此，先來回答第一個問題，業務code哪里判斷的？
其實toResponse()方法並不是RxHttp內部提供的，而是用戶通過自定義解析器，並用@Parser注解標注，最后由注解處理器rxhttp-compiler自動生成的，聽不懂？沒關系，直接看代碼
@Parser(name = "Response")
open class ResponseParser<T> : AbstractParser<T> {
//以下兩個構造方法是必須的
protected constructor() : super()
constructor(type: Type) : super(type)
@Throws(IOException::class)
override fun onParse(response: okhttp3.Response): T {
val type: Type = ParameterizedTypeImpl[Response::class.java, mType] //獲取泛型類型
val data: Response<T> = convert(response, type) //獲取Response對象
val t = data.data //獲取data字段
if (data.code != 200 || t == null) { //code不等於200，說明數據不正確，拋出異常
throw ParseException(data.code.toString(), data.msg, response)
}
return t
}
}
上面代碼只需要關注兩點即可，
第一點，我們在類開頭使用了@Parser注解，並為解析器取名為Response，所以就有了toResponse()方法（命名方式為：to + Parser注解里設置的名字）；
第二點，我們在if語句里，對code做了判斷，非200或者data為空時，就拋出異常，並帶上了code及msg字段，所以我們在異常回調的地方就能拿到這兩個字段
接着回答第二個問題，code非200時，如何拿到msg字段？直接上代碼，看一個使用協程發送請求的完整案例
//當前環境在Fragment中
fun getStudent() {
//rxLifeScope在rxLife-coroutine庫中，需要單獨依賴
rxLifeScope.launch({ //通過launch方法開啟一個協程
val student = RxHttp.get("/service/...")
.toResponse<Student>()
.await()
}, {
//異常回調，這里的it為Throwable類型
val code = it.code
val msg = it.msg
})
}
注：RxLifeScope 是 RxLife-Coroutine庫中的類，本文后續會詳細介紹
上面的代碼，在異常回調中便可拿到code及msg字段，需要注意的是，it.code及it.msg是我為Throwable類擴展的兩個屬性，代碼如下：
val Throwable.code: Int
get() {
val errorCode = when (this) {
is HttpStatusCodeException -> this.statusCode //Http狀態碼異常
is ParseException -> this.errorCode //業務code異常
else -> "-1"
}
return try {
errorCode.toInt()
} catch (e: Exception) {
-1
}
}
val Throwable.msg: String
get() {
return if (this is UnknownHostException) { //網絡異常
"當前無網絡，請檢查你的網絡設置"
} else if (
this is SocketTimeoutException //okhttp全局設置超時
|| this is TimeoutException //rxjava中的timeout方法超時
|| this is TimeoutCancellationException //協程超時
) {
"連接超時,請稍后再試"
} else if (this is ConnectException) {
"網絡不給力，請稍候重試！"
} else if (this is HttpStatusCodeException) { //請求失敗異常
"Http狀態碼異常"
} else if (this is JsonSyntaxException) { //請求成功，但Json語法異常,導致解析失敗
"數據解析失敗,請檢查數據是否正確"
} else if (this is ParseException) { // ParseException異常表明請求成功，但是數據不正確
this.message ?: errorCode //msg為空，顯示code
} else {
"請求失敗，請稍后再試"
}
}
到這，業務code統一判斷就介紹完畢，上面的代碼，大部分人都可以簡單修改后，直接用到自己的項目上，如ResponseParser解析器，只需要改下if語句的判斷條件即可
2.4、操作符介紹
map 轉換符號
map操作符很好理解，RxJava及協程的Flow都有該操作符，功能都是一樣，用於轉換對象，如下：
val student = RxHttp.postForm("/service/...")
.toStr()
.map { it.length } //String轉Int
.tryAwait() //這里返回 Student? 對象，即有可能為空
timeout 超時
OkHttp提供了全局的讀、寫及連接超時，有時我們也需要為某個請求設置不同的超時時長，此時就可以用到RxHttp的timeout(Long)方法，如下：
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.timeout(3000) //超時時長為3s
.await()
retry 失敗重試
OkHttp為我們提供了全局的失敗重試機制，然而，這遠遠不能滿足我們的需求，比如，我就部分接口需要失敗重試，而不是全局的；我需要根據某些條件來判斷是否需要重試；亦或者我需要周期性重試，即間隔幾秒后重試等等
如我們需要在網絡出現異常時，重試2次，每次間隔1秒，代碼如下：
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.retry(2, 1000) { //重試2次，每次間隔1s
it is ConnectException //如果是網絡異常就重試
}
.await()
retry()方法共有3個參數，分別是重試次數、重試周期、重試條件，都有默認值，3個參數可以隨意搭配，如下：
/**
* 失敗重試，該方法僅在使用協程時才有效
* @param times 重試次數, 默認Int.MAX_VALUE 代表不斷重試
* @param period 重試周期, 默認為0, 單位: milliseconds
* @param test 重試條件, 默認為true，只要出現異常就重試
*/
fun retry(
times: Int = Int.MAX_VALUE,
period: Long = 0,
test: suspend (Throwable) -> Boolean = { true }
)
filter 過濾操作
如果服務器返回列表數據，則我們可對列表進行過濾操作，如下：
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.filter{ it.age > 20 } //過濾年齡大於20歲的學生
.await()
還可以選用filterTo操作符，將過濾后的數據添加到指定列表中，如下：
val list = mutableListOf<Student>()
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.filterTo(list){ it.age > 20 } //過濾年齡大於20歲的學生
.await() //此時返回的列表對象就是我們傳入的列表對象
distinct 去重
該操作符可以對服務器返回的列表，做去重操作，如下：
//根據Student對象的hashCode去重
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.distinct()
.await()
//根據Student對象的id去重
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.distinctBy { it.id }
.await()
//將去重后的數據添加到指定列表中，並且去重時，會對指定列表數據做判斷
val list = mutableListOf<Student>()
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.distinctTo(list) { it.id }
.await()
sort 排序
排序有sortXxx、sortedXxx兩大類型操作符，區別在於sortXxx在列表內排序，排序完，返回自身，而sortedXxx在列表外排序，排序完，返回新的列表，這里只對sortXxx介紹，如下：
//根據id順序排序
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.sortBy { it.id }
.await()
//根據id、age兩個字段順序排序，id優先，其次age
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.sortBy({ it.id }, { it.age })
.await()
//返回兩個排序對象，自行實現排序規則
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.sortWith { student1, student2 ->
student1.id.compareTo(student2.id)
}
.await()
flowOn 指定上游所在線程
該操作符跟Flow里面的flowOn操作符一樣，用於指定上游所在線程，如下：
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.sortBy { it.id } //IO線程執行
.flowOn(Dispatchers.IO)
.distinctBy { it.id } //Default線程執行
.flowOn(Dispatchers.Default)
.filter{ it.age > 20 } //IO線程執行
.flowOn(Dispatchers.IO)
.flowOn(Dispatchers.Default)
.await()
asFlow 轉Flow對象
如果你喜歡kotlin的flow流，那么asFlow 就派上用場了，如下：
RxHttp.postForm("/service/...")
.toList<Student>()
.asFlow()
.collect {
//這里拿到List<Student>對象
}
注意：使用asFlow操作符后，需要使用collect替代await操作符
subList、take 截取列表
subList用於截取某段列表，截取范圍越界，則拋出越界異常；take用於從0開始，取n個數據，不足n個時，返回全部，如下：
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.subList(1，10) //截取9個數據
.take(5) //從9個中取前5個
.await()
async 異步操作
如果我們由兩個請求需要並行時，就可以使用該操作符，如下：
//同時獲取兩個學生信息
suspend void initData() {
val asyncStudent1 = RxHttp.postForm("/service/...")
.toResponse<Student>()
.async(this) //this為CoroutineScope對象，這里會返回Deferred<Student>
val asyncStudent2 = RxHttp.postForm("/service/...")
.toResponse<Student>()
.async(this) //this為CoroutineScope對象，這里會返回Deferred<Student>
//隨后調用await方法獲取對象
val student1 = asyncStudent1.await()
val student2 = asyncStudent2.await()
}
delay、startDelay 延遲
delay操作符是請求結束后，延遲一段時間返回；而startDelay操作符則是延遲一段時間后再發送請求，如下：
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.delay(1000) //請求回來后，延遲1s返回
.await()
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.startDelay(1000) //延遲1s后再發送請求
.await()
onErrorReturn、onErrorReturnItem異常默認值
有些情況，我們不希望請求出現異常時，直接走異常回調，此時我們就可以通過兩個操作符，給出默認的值，如下：
//根據異常給出默認值
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.timeout(100) //超時時長為100毫秒
.onErrorReturn {
//如果時超時異常，就給出默認值，否則，拋出原異常
return@onErrorReturn if (it is TimeoutCancellationException)
Student()
else
throw it
}
.await()
//只要出現異常，就返回默認值
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.timeout(100) //超時時長為100毫秒
.onErrorReturnItem(Student())
.await()
awaitResult 返回kotlin.Result
這個就直接看代碼吧
val result: Result<Student> = RxHttp
.postForm("/service/...")
.toClass<Student>()
.awaitResult()
if (result.isSuccess) {
//請求成功，拿到Student對象
val student = result.getOrThrow()
} else {
//請求出現異常，拿到Throwable對象
val throwable = result.exceptionOrNull()
}
拿到kotlin.Result對象后，我們需要判斷請求成功與否，隨后在執行相關邏輯
tryAwait 異常返回null
tryAwait會在異常出現時，返回null，如下：
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.timeout(100) //超時時長為100毫秒
.tryAwait() //這里返回 Student? 對象，如果出現異常，那它就是null
自定義操作符
RxHttp內置了一系列強大又好用的操作符，然而肯定滿足不了所有的業務場景，此時我們就可以考慮自定義操作符
自定義takeLast操作符
如我們有這樣一個需求，自定義需要在列表尾部取n條數據，不足n條，返回全部
前面我們介紹了take操作符，它是從0開始，取n條數據，如果不足n條，則全部返回，來看看源碼
fun <T> IAwait<out Iterable<T>>.take(
count: Int
): IAwait<List<T>> = newAwait {
await().take(count)
}
代碼解讀，
1、IAwait是一個接口，如下：
interface IAwait<T> {
suspend fun await(): T
}
該接口僅有一個await()方法，返回聲明的T
2、newAwait操作符，只是創建了一個IAwait接口的實現而已，如下：
inline fun <T, R> IAwait<T>.newAwait(
crossinline block: suspend IAwait<T>.() -> R
): IAwait<R> = object : IAwait<R> {
override suspend fun await(): R {
return this@newAwait.block()
}
}
3、由於我們是為IAwait<out Iterable<T>>對象擴展的take方法，故在內部，我們調用await()方法它返回Iterable<T>對象，最后就執行Iterable<T>對象的擴展方法take(Int)獲取從0開是的n條數據，take(Int)是系統提供的方法，源碼如下：
public fun <T> Iterable<T>.take(n: Int): List<T> {
require(n >= 0) { "Requested element count $n is less than zero." }
if (n == 0) return emptyList()
if (this is Collection<T>) {
if (n >= size) return toList()
if (n == 1) return listOf(first())
}
var count = 0
val list = ArrayList<T>(n)
for (item in this) {
list.add(item)
if (++count == n)
break
}
return list.optimizeReadOnlyList()
}
ok，回到前面的話題，如何自定義一個操作，實現在列表尾部取n條數據，不足n條，返回全部
看了上面的take(int)源碼，我們就可以很輕松的寫出如下代碼：
fun <T> IAwait<out List<T>>.takeLast(
count: Int
): IAwait<List<T>> = newAwait {
await().takeLast(count)
}
首先，我們對IAwait<out List<T>>擴展了takeLast(Int)方法，隨后調用newAwait創建了IAwait接口的實例對象，接着調用await()方法返回List<T>對象，最后調用系統為List<T>擴展的takeLast(Int)方法
定義好了，我們就可直接使用，如下：
val students = RxHttp.postForm("/service/...")
.toList<Student>()
.takeLast(5) //取列表尾部5條數據，不足時，全部返回
.await()
以上操作符隨意搭配
以上操作符，可隨意搭配使用，但調用順序的不同，產生的效果也不一樣，這里先告訴大家，以上操作符僅會對上游代碼產生影響。
如timeout及retry：
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.timeout(50)
.retry(2, 1000) { it is TimeoutCancellationException }
.await()
以上代碼，只要出現超時，就會重試，並且最多重試兩次。
但如果timeout、retry互換下位置，就不一樣了，如下：
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.retry(2, 1000) { it is TimeoutCancellationException }
.timeout(50)
.await()
此時，如果50毫秒內請求沒有完成，就會觸發超時異常，並且直接走異常回調，不會重試。為什么會這樣？原因很簡單，timeout及retry操作符，僅對上游代碼生效。如retry操作符，下游的異常是捕獲不到的，這就是為什么timeout在retry下，超時時，重試機制沒有觸發的原因。
在看timeout和startDelay操作符
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.startDelay(2000)
.timeout(1000)
.await()
以上代碼，必定會觸發超時異常，因為startDelay，延遲了2000毫秒，而超時時長只有1000毫秒，所以必定觸發超時。
但互換下位置，又不一樣了，如下：
val student = RxHttp.postForm("/service/...")
.toResponse<Student>()
.timeout(1000)
.startDelay(2000)
.await()
以上代碼正常情況下，都能正確拿到返回值，為什么？原因很簡單，上面說過，操作符只會對上游產生影響，下游的startDelay延遲，它是不管的，也管不到。
3、上傳/下載
RxHttp對文件的優雅操作是與生俱來的，在協程的環境下，依然如此，沒有什么比代碼更具有說服力，直接上代碼
3.1、文件上傳
val result = RxHttp.postForm("/service/...")
.addFile("file", File("xxx/1.png")) //添加單個文件
.addFile("fileList", ArrayList<File>()) //添加多個文件
.toResponse<String>()
.await()
只需要通過addFile系列方法添加File對象即可，就是這么簡單粗暴，想監聽上傳進度？簡單，再加一個upload操作符即可，如下：
val result = RxHttp.postForm("/service/...")
.addFile("file", File("xxx/1.png"))
.addFile("fileList", ArrayList<File>())
.upload(this) { //此this為CoroutineScope對象，即當前協程對象
//it為Progress對象
val process = it.progress //已上傳進度 0-100
val currentSize = it.currentSize //已上傳size，單位：byte
val totalSize = it.totalSize //要上傳的總size 單位：byte
}
.toResponse<String>()
.await()
我們來看下upload方法的完整簽名，如下：
/**
* 調用此方法監聽上傳進度
* @param coroutine CoroutineScope對象，用於開啟協程，回調進度，進度回調所在線程取決於協程所在線程
* @param progress 進度回調
* 注意：此方法僅在協程環境下才生效
*/
fun RxHttpFormParam.upload(
coroutine: CoroutineScope? = null,
progress: (Progress) -> Unit
):RxHttpFormParam
3.2、文件下載
接着再來看看下載，直接貼代碼
val localPath = "sdcard//android/data/..../1.apk"
val student = RxHttp.get("/service/...")
.toDownload(localPath) //下載需要傳入本地文件路徑
.await()
下載調用toDownload(String)方法，傳入本地文件路徑即可，要監聽下載進度？也簡單，如下：
val localPath = "sdcard//android/data/..../1.apk"
val student = RxHttp.get("/service/...")
.toDownload(localPath, this) { //此this為CoroutineScope對象
//it為Progress對象
val process = it.progress //已下載進度 0-100
val currentSize = it.currentSize //已下載size，單位：byte
val totalSize = it.totalSize //要下載的總size 單位：byte
}
.await()
看下toDownload方法完整簽名
/**
* @param destPath 本地存儲路徑
* @param coroutine CoroutineScope對象，用於開啟協程，回調進度，進度回調所在線程取決於協程所在線程
* @param progress 進度回調
*/
fun IRxHttp.toDownload(
destPath: String,
coroutine: CoroutineScope? = null,
progress: (Progress) -> Unit
): IAwait<String>
如果你需要斷點下載，用toAppendDownload方法替換toDownload方法即可，如下：
val localPath = "sdcard//android/data/..../1.apk"
val student = RxHttp.get("/service/...")
.toAppendDownload(localPath, this) { //此this為CoroutineScope對象
//it為Progress對象
val process = it.progress //已下載進度 0-100
val currentSize = it.currentSize //已下size，單位：byte
val totalSize = it.totalSize //要下的總size 單位：byte
}
.await()
到這，RxHttp協程的基礎Api基本介紹完畢，那么問題了，以上介紹的Api都依賴與協程環境，那我這么開啟協程呢？亦或者說，我對協程不是很懂，你只要保證安全的前提下，告訴怎么用就行了，ok，那下面如何安全的開啟一個協程，做到自動異常捕獲，且頁面銷毀時，自動關閉協程及請求
4、協程開啟及關閉
此時就要引入本人開源的另一個庫RxLife-Coroutine，用於開啟/關閉協程，並自動異常捕獲，依賴如下：
implementation 'com.ljx.rxlife:rxlife-coroutine:2.0.1'
本文在介紹業務code統一處理的時候，我們用到rxLifeScope屬性開啟協程，那這個是什么類型呢？看代碼
val ViewModel.rxLifeScope: RxLifeScope
get() {
val scope: RxLifeScope? = this.getTag(JOB_KEY)
if (scope != null) {
return scope
}
return setTagIfAbsent(JOB_KEY, RxLifeScope())
}
val LifecycleOwner.rxLifeScope: RxLifeScope
get() = lifecycle.rxLifeScope
可以看到，我們為ViewModel及LifecycleOwner都擴展了一個名為rxLifeScope的屬性，類型為RxLifeScope，ViewModel相信大家都知道了，這里就簡單講一下LifecycleOwner接口，我們的Fragment及FragmentActivity都實現了LifecycleOwner接口，而我們的Activity一般繼承於AppCompatActivity，而AppCompatActivity繼承於FragmentActivity，所以我們在FragmentActivity/Fragment/ViewModel環境下，可以直接使用rxLifeScope開啟協程，如下：
rxLifeScope.lanuch({
//協程代碼塊，運行在UI線程
}, {
//異常回調，協程代碼塊出現任何異常，都會直接走這里
})
通過這種方式開啟的協程，會在頁面銷毀時，會自動關閉協程，當然，如果你的協程代碼塊里還有RxHttp請求的代碼，協程關閉的同時，也是關閉請求，所以在這種情況下，只需要知道如何開啟協程就行，其它一律不管。
現在，我們來看下rxLifeScope.lanuch方法的完整簽名
/**
* @param block 協程代碼塊，運行在UI線程
* @param onError 異常回調，運行在UI線程
* @param onStart 協程開始回調，運行在UI線程
* @param onFinally 協程結束回調，不管成功/失敗，都會回調，運行在UI線程
*/
fun launch(
block: suspend CoroutineScope.() -> Unit,
onError: ((Throwable) -> Unit)? = null,
onStart: (() -> Unit)? = null,
onFinally: (() -> Unit)? = null
): Job
可以看到，不僅有失敗回調，還有開始及結束回調，這對於我們發請求來說，真的非常方便，如下：
rxLifeScope.launch({
//協程代碼塊
val students = RxHttp.postJson("/service/...")
.toResponse<List<Student>>()
.await()
//可以直接更新UI
}, {
//異常回調，這里可以拿到Throwable對象
}, {
//開始回調，可以開啟等待彈窗
}, {
//結束回調，可以銷毀等待彈窗
})
以上代碼均運行在UI線程中，請求回來后，便可直接更新UI
也許你還有疑問，我在非FragmentActivity/Fragment/ViewModel環境下，如何開啟協程，又如何關閉，其實也很簡單，如下：
val job = RxLifeScope().launch({
val students = RxHttp.postJson("/service/...")
.toResponse<List<Student>>()
.await()
}, {
//異常回調，這里可以拿到Throwable對象
}, {
//開始回調，可以開啟等待彈窗
}, {
//結束回調，可以銷毀等待彈窗
})
job.cancel() //關閉協程
以上代碼，需要注意兩點，第一，我們需要手動創建RxLifeScope()對象，隨后開啟協程；第二，開啟協程后，可以拿到Job對象，我們需要通過該對象手動關閉協程。其它就沒啥區別了。
5、協程多任務處理
我們知道，協程最大的優勢就是：能以看起來同步的代碼，寫出異步的邏輯，這使得我們可以非常優雅的實現多任務場景，比如多請求的並行/串行
5.1、協程串行多個請求
假設，我們有這么一種場景，首先獲取Student對象，隨后通過studentId獲取學生的家庭成員列表，后者依賴於前者，這是典型的串行場景
看看通過協程如何解決這個問題，如下：
class MainActivity : AppCompatActivity() {
//啟動協程，發送請求
fun sendRequest() {
rxLifeScope.launch({
//當前運行在協程中，且在主線程運行
val student = getStudent()
val personList = getFamilyPersons(student.id) //通過學生Id，查詢家庭成員信息
//拿到相關信息后，便可直接更新UI，如：
tvName.text = student.name
}, {
//出現異常，就會到這里，這里的it為Throwable類型
it.show("發送失敗,請稍后再試!") //show方法是在Demo中擴展的方法
})
}
//掛斷方法，獲取學生信息
suspend fun getStudent(): Student {
return RxHttp.get("/service/...")
.add("key", "value")
.addHeader("headKey", "headValue")
.toClass<Student>()
.await()
}
//掛斷方法，獲取家庭成員信息
suspend fun getFamilyPersons(studentId: Int): List<Person> {
return RxHttp.get("/service/...")
.add("studentId", "10000")
.toClass<List<Person>>()
.await()
}
}
我們重點看下協程代碼塊，首先通過第一個請求拿到Student對象，隨后拿到studentId，發送第二個請求獲取學習家庭成員列表，拿到后，便可以直接更新UI，怎么樣，是不是看起來同步的代碼，寫出了異步的邏輯。
串行請求中，只要其中一個請求出現異常，協程便會關閉（同時也會關閉請求），停止執行剩下的代碼，接着走異常回調
5.2、協程並行多個請求
請求並行，在現實開發中，也是家常便飯，在一個Activity中，我們往往需要拿到多種數據來展示給用戶，而這些數據，都是不同接口下發的。
如我們有這樣一個頁面，頂部是橫向滾動的Banner條，Banner條下面展示學習列表，此時就有兩個接口，一個獲取Banner條列表，一個獲取學習列表，它們兩個互不依賴，便可以並行執行，如下：
class MainActivity : AppCompatActivity() {
//啟動協程，發送請求
fun sendRequest() {
rxLifeScope.launch({
//當前運行在協程中，且在主線程運行
val asyncBanner = getBanners(this) //這里返回Deferred<List<Banner>>對象
val asyncPersons = getStudents(this) //這里返回Deferred<List<Student>>對象
val banners = asyncBanner.await() //這里返回List<Banner>對象
val students = asyncPersons.await() //這里返回List<Student>對象
//開始更新UI
}, {
//出現異常，就會到這里，這里的it為Throwable類型
it.show("發送失敗,請稍后再試!") //show方法是在Demo中擴展的方法
})
}
//掛斷方法，獲取學生信息
suspend fun getBanners(scope: CoroutineScope): Deferred<List<Banner>> {
return RxHttp.get("/service/...")
.add("key", "value")
.addHeader("headKey", "headValue")
.toClass<List<Banner>>()
.async(scope) //注意這里使用async異步操作符
}
//掛斷方法，獲取家庭成員信息
suspend fun getStudents(scope: CoroutineScope): Deferred<List<Student>> {
return RxHttp.get("/service/...")
.add("key", "value")
.toClass<List<Student>>()
.async(scope) //注意這里使用async異步操作符
}
}
在上述代碼的兩個掛斷方法中，均使用了async異步操作符，此時這兩個請求就並行發送請求，隨后拿到Deferred<T>對象，調用其await()方法，最終拿到Banner列表及Student列表，最后便可以直接更新UI。
划重點
並行跟串行一樣，如果其中一個請求出現了異常，協程便會自動關閉（同時關閉請求），停止執行剩下的代碼，接着走異常回調。如果想多個請求互不影響，就可以使用上面介紹的onErrorReturn、onErrorReturnItem操作符，出現異常時，給出一個默認對象，又或者使用tryAwait操作符獲取返回值，出現異常時，返回null，這樣就不會影響其它請求的執行。
6、總結
看完本文，相信你已經領悟到了RxHttp優雅及簡便，業務code的統一處理，失敗重試、超時、文件上傳/下載及進度監聽，到后面rxLifeScope協程的開啟/關閉/異常處理/多任務處理，一切都是那么的優雅。
其實，RxHttp遠不止這些，本文只是講解了RxHttp與協程相關的東西，更多優雅的功能，如：多/動態baseUrl的處理、公共參數/請求頭的添加、請求加解密、緩存等等，請查看
最后，開源不易，寫文章更不易，還需要勞煩大家給本文點個贊，可以的話，再給個star，我將感激不盡，🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏