1、前言

一直有人问我，RxHttp跟Retrofit相比有什么优势？我做了个对比图，一看就明白了

首先我声明一点，RxHttp的出现，并不是要干掉谁，而是给大家多一个选择，多一个不一样的选择。

RxHttp与Retrofit对比

功能说明	RxHttp	Retrofit
版本	v3.0.1	v2.9.0
状态	维护中	维护中
标准RESTful风格	✅	✅
学习成本	低	高
扩展性	高	高
源码大小	73k	75k
jar包大小	213k	123k
RxJava	RxJava ❌ RxJava2✅ RxJava3✅	RxJava ✅ RxJava2✅ RxJava3✅
Kotlin协程	✅	✅
Flow流	✅	✅
Converter	Gson✅ Jackson✅ fastJson✅ Moshi✅ Protobuf✅ simplexml✅ kotlinx.serialization✅ 自定义✅	Gson✅ Jackson✅ fastJson✅ Moshi✅ Protobuf✅ simplexml✅ kotlinx.serialization✅ 自定义✅
关闭请求	手动✅ 自动✅ 批量✅	手动✅ 自动✅ 批量✅
文件上传/下载/进度监听	✅	❌需再次封装
Android 10分区存储	✅	❌需再次封装
公共参数	✅	❌需再次封装
多域名/动态域名	✅好用	✅一般
日志打印	✅	✅
Json数据格式化输出	✅	❌需再次封装
业务code统一判断	✅	❌需再次封装
请求缓存	✅	❌需再次封装
全局加解密	✅	❌需再次封装
部分字段解密	✅	❌需再次封装

RxHttp&RxLife交流群（群号：378530627）

本文仅介绍RxHttp + 协程的使用，更多功能请查看

RxHttp 让你眼前一亮的Http请求框架

RxHttp 完美适配Android 10/11 上传/下载/进度监听

RxHttp 全网Http缓存最优解

gradle依赖

1、必选

将jitpack添加到项目的build.gradle文件中，如下：

allprojects {
    repositories {
        maven { url "https://jitpack.io" }
    }
}
复制代码

注：RxHttp 2.6.0版本起，已全面从JCenter迁移至jitpack

//使用kapt依赖rxhttp-compiler时必须
apply plugin: 'kotlin-kapt'

android {
    //必须，java 8或更高
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    def rxhttp_version = '3.0.1'
    implementation 'com.squareup.okhttp3:okhttp:4.10.0' 
    implementation "com.github.liujingxing.rxhttp:rxhttp:$rxhttp_version"
    kapt "com.github.liujingxing.rxhttp:rxhttp-compiler:$rxhttp_version" //生成RxHttp类，纯Java项目，请使用annotationProcessor代替kapt
 }
复制代码

2、可选

android {
    kapt {
        arguments {
            //依赖了RxJava时，rxhttp_rxjava参数为必须，传入RxJava版本号
            arg("rxhttp_rxjava", "3.1.4")  
            arg("rxhttp_package", "rxhttp")  //指定RxHttp类包名，非必须
        }
    }
    //如果项目未集成kotlin，通过javaCompileOptions方法传参，在defaultConfig标签下
    annotationProcessorOptions {
        arguments = [
            rxhttp_rxjava: '3.1.4',
            rxhttp_package: 'rxhttp'
        ]
    }
}
dependencies {    
    //rxjava2   (RxJava2/Rxjava3二选一，使用asXxx方法时必须)
    implementation 'io.reactivex.rxjava2:rxjava:2.2.8'
    implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'
    implementation 'com.github.liujingxing.rxlife:rxlife-rxjava2:2.2.2' //管理RxJava2生命周期，页面销毁，关闭请求

    //rxjava3
    implementation 'io.reactivex.rxjava3:rxjava:3.1.4'
    implementation 'io.reactivex.rxjava3:rxandroid:3.0.0'
    implementation 'com.github.liujingxing.rxlife:rxlife-rxjava3:2.2.2' //管理RxJava3生命周期，页面销毁，关闭请求

    //非必须，根据自己需求选择 RxHttp默认内置了GsonConverter
    implementation "com.github.liujingxing.rxhttp:converter-serialization:$rxhttp_version"
    implementation "com.github.liujingxing.rxhttp:converter-fastjson:$rxhttp_version"
    implementation "com.github.liujingxing.rxhttp:converter-jackson:$rxhttp_version"
    implementation "com.github.liujingxing.rxhttp:converter-moshi:$rxhttp_version"
    implementation "com.github.liujingxing.rxhttp:converter-protobuf:$rxhttp_version"
    implementation "com.github.liujingxing.rxhttp:converter-simplexml:$rxhttp_version"
}
复制代码

遇到问题，点这里，点这里，点这里，99%的问题都能自己解决

本文只介绍RxHttp + 协程用法，如果你想了解RxHttp + RxJava的用法，请阅读RxHttp 让你眼前一亮的Http请求框架一文

如果你现在对协程还一知半解，没有关系，那是因为你还没有找到运用场景，而网络请求正是一个很好的切入场景，本文会教你如何优雅，并且安全的开启协程，以及用协程处理多任务，用着用着你就会了。

2、RxHttp 协程使用

2.1、请求三部曲

用过RxHttp的同学知道，RxHttp发送任意请求皆遵循请求三部曲，如下：

代码表示

//Kotlin 协程
val str = RxHttp.get("/service/...") //第一步，确定请求方式，可以选择postForm、postJson等方法
    .toAwaitString()    //第二步，确认返回类型，这里代表返回String类型
    .await()    //第三步，使用await方法拿到返回值
    
//RxJava
RxHttp.get("/service/...") //第一步，确定请求方式，可以选择postForm、postJson等方法
    .toObervableString()            //第二步，使用toObservableXxx系列方法确定返回类型
    .subscribe(s -> {      //第三步, 订阅观察者
        //成功回调
    }, throwable -> {
        //失败回调
    });
复制代码

注: await()是suspend挂断方法，需要在另一个suspend方法或协程环境中调用

协程请求三部曲详解

• 第一步，选择get、postForm、postJson等方法来确定请求方式，随后便可通过add、addFile、addHeader等方法来添加参数、文件、请求头等信息

• 第二步，调用toAwaitXxx系列方法来确定返回类型，常用的有toAwaitString、toAwait<T>、toAwaitList<T>，随后便可调用asFlow、retry、timeout、flowOn等操作符来执行不同的业务逻辑，本文后续会一一介绍

• 第三步，最后，只需调用await、tryAwait、awaitResult这三个中的任一操作符获取返回值即可，这一步，需要在协程环境中才能调用

接着，如果我们要获取一个Student对象或者List<Student>集合对象等等任意数据类型，也是通过await()方法，如下：

//Student对象
val student = RxHttp.get("/service/...")
    .toAwait<Student>()
    .await()
    
//List<Student> 对象   
val students = RxHttp.get("/service/...")
    .toAwaitClass<List<Student>>()
    .await()
复制代码

注：toAwait()方法是万能的，你可以传递任意数据类型过去

以上就是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/...")
    .toAwaitString()
    .await()
   
//使用google域名方式一：传入的url直接带上google域名
RxHttp.get("https://wwww.google.com/service/...")
    .toAwaitSrting()
    .await()
    
//使用google域名方式二：调用setDomainToGoogleIfAbsent方法
RxHttp.get("/service/...")
    .setDomainToGoogleIfAbsent()
    .toAwaitString()
    .await()
 
//使用google域名方式三：直接使用RxGoogleHttp类发送请求
RxGoogleHttp.get("/service/...")
    .toAwaitString()
    .await()
复制代码

注意：手动传入的域名优先级别最高，其次是调用setDomainToXxx方法，最后才会使用默认域名

动态域名处理

//直接对url重新赋值即可，改完立即生效
Url.BASE_URL = "https://www.baidu.com";
RxHttp.get("/service/...")
    .toAwaitString()
    .await()
//此时请求的url为 https://www.baidu.com/service/...
复制代码

2.3、业务code统一判断

我想大部分人的接口返回格式都是这样的

class BaseResponse<T> {
    var code = 0
    var msg : String? = null
    var data : T 
}
复制代码

拿到该对象的第一步就是对code做判断，如果code != 200(假设200代表数据正确)，就会拿到msg字段给用户一些错误提示，如果等于200，就拿到data字段去更新UI，常规的操作是这样的

val response = RxHttp.get("/service/...")
    .toAwait<BaseResponse<Student>>()
    .await()
if (response.code == 200) {
    //拿到data字段(Student)刷新UI
} else {
    //拿到msg字段给出错误提示
} 
复制代码

试想一下，一个项目少说也有30+个这样的接口，如果每个接口读取这么判断，就显得不够优雅，也可以说是灾难，相信也没有人会这么干。而且对于UI来说，只需要data字段即可，错误提示啥的我管不着。

那有没有什么办法，能直接拿到data字段，并且对code做出统一判断呢？有的，直接上代码

val student = RxHttp.get("/service/...")
    .toAwaitResponse<Student>() //调用此方法，直接拿到data字段，也就是Student对象   
    .awaitResult {  
        val student = it
        //更新UI
    }.onFailure {
        val msg = it.msg  
        val code = it.code                            
    }
复制代码

可以看到，这里调用了toAwaitResponse()方法，就直接拿到了data字段，也就是Student对象。

此时，相信很多人会有疑问，

• 业务code哪里判断的？

• 异常回调里的it是什么对象，为啥可以拿到msg、code字段？

先来回答第一个问题，业务code哪里判断的？

其实toAwaitResponse()方法并不是RxHttp内部提供的，而是用户通过自定义解析器，并用@Parser注解标注，最后由注解处理器rxhttp-compiler自动生成的，听不懂？没关系，直接看代码

@Parser(name = "Response")
open class ResponseParser<T> : TypeParser<T> {
    
    //以下两个构造方法是必须的
    protected constructor() : super()
    constructor(type: Type) : super(type)

    @Throws(IOException::class)
    override fun onParse(response: okhttp3.Response): T {
        val data: BaseResponse<T> = response.convertTo(BaseResponse::class, *types)
        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，此时rxhttp-compiler就会生成toAwaitResponse<T>()方法，命名规则为toAwait{name}

第二点，我们在if语句里，code != 200或data == null时，就抛出ParseException异常，并带上了msg、code字段，所以我们在异常回调通过强转，就可以拿到这两个字段

接着回答第二个问题，异常回调里的it是什么对象，为啥可以拿到msg、code字段？

其实it就是Throwable对象，而msg、code是Throwable的扩展字段，这需要我们自己为其扩展，代码如下：

val Throwable.code: Int
    get() =
        when (this) {
            is HttpStatusCodeException -> this.statusCode //Http状态码异常
            is ParseException -> this.errorCode.toIntOrNull() ?: -1     //业务code异常
            else -> -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、操作符介绍

awaitResult 返回kotlin.Result

awaitResult是最常用的字符，它可以处理请求成功/失败回调，如下：

val result: Result<Student> = RxHttp
    .postForm("/service/...")
    .toAwait<Student>()
    .awaitResult {  
        //请求成功，通过it拿到Student对象          
    }.onFailure { 
        //请求异常，通过it拿到Throwable对象      
    }                                                            
复制代码

拿到kotlin.Result对象后，随后成功/失败处理相关逻辑

tryAwait 异常返回null

tryAwait会在异常出现时，返回null，如下：

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .timeout(100)      //超时时长为100毫秒                        
    .tryAwait()     //这里返回 Student? 对象，如果出现异常，那它就是null 
复制代码

当然，tryAwait也支持异常回调，如下

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .timeout(100)      //超时时长为100毫秒                        
    .tryAwait { //同样的，出现异常，返回null
        //这里通过it拿到Throwable对象
    }     
复制代码

onErrorReturn、onErrorReturnItem异常默认值

有些情况，我们不希望请求出现异常时，直接走异常回调，此时我们就可以通过两个操作符，给出默认的值，如下：

//根据异常给出默认值
val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .timeout(100)      //超时时长为100毫秒  
    .onErrorReturn {
        //如果时超时异常，就给出默认值，否则，抛出原异常
        return@onErrorReturn if (it is TimeoutCancellationException)
            Student()                                              
        else                                                        
            throw it                                                
    }
    .await()
    
//只要出现异常，就返回默认值
val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .timeout(100)      //超时时长为100毫秒  
    .onErrorReturnItem(Student())
    .await()
复制代码

repeat 轮训请求

repeat操作符共有3个参数，如下：

/**
 * @param times  轮训次数，默认Long.MAX_VALUE，即一直轮训
 * @param period 轮训周期，默认0
 * @param stop   轮训终止条件，默认false，即无条件轮训times次
 */
fun <T> IAwait<T>.repeat(
    times: Long = Long.MAX_VALUE,
    period: Long = 0,
    stop: suspend (T) -> Boolean = { false }
)
复制代码

以上3个参数可随意搭配使用，用法如下：

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .repeat(10, 1000) {            //轮训 10次，每次间隔 1s
        return it.id == 8888       //如果学生 id 是 8888，则停止轮训  
    }                                             
    .await()                     
复制代码

retry 失败重试

retry操作符共有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 }
)
复制代码

3个参数可随意搭配使用，我们需要在网络出现异常时，重试2次，每次间隔1秒，代码如下：

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .retry(2, 1000) {            //重试2次，每次间隔1s                 
        it is ConnectException   //如果是网络异常就重试     
    }                                             
    .await()                     
复制代码

timeout 超时

OkHttp提供了全局的读、写及连接超时，有时我们也需要为某个请求设置不同的超时时长，此时就可以用到RxHttp的timeout(Long)方法，如下：

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .timeout(3000)      //超时时长为3s                           
    .await()                       
复制代码

map 转换符号

map操作符很好理解，RxJava及协程的Flow都有该操作符，功能都是一样，用于转换对象，如下：

val student = RxHttp.postForm("/service/...")
    .toAwaitString()
    .map { it.length }  //String转Int                        
    .tryAwait()     //这里返回 Student? 对象，即有可能为空  
复制代码

flowOn 指定上游所在线程

该操作符跟Flow里面的flowOn操作符一样，用于指定上游所在线程，如下：

val students = RxHttp.postForm("/service/...")
    .toAwaitList<Student>()
    .map { //IO线程执行 }        
    .flowOn(Dispatchers.IO)
    .map { //Default线程执行 }    
    .flowOn(Dispatchers.Default)
    .map { //IO线程执行 }   
    .flowOn(Dispatchers.IO)
    .flowOn(Dispatchers.Default)
    .await() 
复制代码

asFlow 转Flow对象

如果你喜欢kotlin的flow流，那么asFlow 就派上用场了，如下：

RxHttp.postForm("/service/...")
    .toAwaitList<Student>()
    .asFlow()
    .collect {       
        //这里拿到List<Student>对象         
    }                
复制代码

注意：使用asFlow操作符后，需要使用collect替代await操作符

async 异步操作

如果我们由两个请求需要并行时，就可以使用该操作符，如下：

//同时获取两个学生信息
suspend void initData() {
  val asyncStudent1 = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .async(this)   //this为CoroutineScope对象，这里会返回Deferred<Student>  
    
  val asyncStudent2 = RxHttp.postForm("/service/...")
    .toAwait<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/...")
    .toAwait<Student>()
    .delay(1000)      //请求回来后，延迟1s返回                         
    .await()       
    
val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .startDelay(1000)     //延迟1s后再发送请求       
    .await()     
复制代码

以上操作符随意搭配

以上操作符，可随意搭配使用，但调用顺序的不同，产生的效果也不一样，这里先告诉大家，以上操作符仅会对上游代码产生影响。

如timeout及retry：

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .timeout(50)
    .retry(2, 1000) { it is TimeoutCancellationException }                                  
    .await()                       
复制代码

以上代码，只要出现超时，就会重试，并且最多重试两次。

但如果timeout、retry互换下位置，就不一样了，如下：

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .retry(2, 1000) { it is TimeoutCancellationException }       
    .timeout(50)                                  
    .await()                       
复制代码

此时，如果50毫秒内请求没有完成，就会触发超时异常，并且直接走异常回调，不会重试。为什么会这样？原因很简单，timeout及retry操作符，仅对上游代码生效。如retry操作符，下游的异常是捕获不到的，这就是为什么timeout在retry下，超时时，重试机制没有触发的原因。

在看timeout和startDelay操作符

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .startDelay(2000)       
    .timeout(1000)                                  
    .await()                       
复制代码

以上代码，必定会触发超时异常，因为startDelay，延迟了2000毫秒，而超时时长只有1000毫秒，所以必定触发超时。 但互换下位置，又不一样了，如下：

val student = RxHttp.postForm("/service/...")
    .toAwait<Student>()
    .timeout(1000)    
    .startDelay(2000)       
    .await()                       
复制代码

以上代码正常情况下，都能正确拿到返回值，为什么？原因很简单，上面说过，操作符只会对上游产生影响，下游的startDelay延迟，它是不管的，也管不到。

3、上传/下载

RxHttp对文件的优雅操作是与生俱来的，在协程的环境下，依然如此，没有什么比代码更具有说服力，直接上代码

3.1、文件上传

 val result = RxHttp.postForm("/service/...")  
     .addFile("file", File("xxx/1.png"))        //添加单个文件   
     .addFiles("fileList", ArrayList<File>())    //添加多个文件
     .toAwait<String>()
     .await()                   
复制代码

只需要通过addFile系列方法添加File对象即可，就是这么简单粗暴，想监听上传进度，需要调用toFlow方法，并传入进度回调即可，如下：

RxHttp.postForm("/service/...")      
    .addFile("file", File("xxx/1.png"))    
    .addFiles("fileList", ArrayList<File>())      
    .toFlow<String> {  //这里还可以选择自定义解析器对应的toFlowXxx方法   
        val process = it.progress         //已上传进度  0-100 
        val currentSize = it.currentSize  //已上传size，单位：byte
        val totalSize = it.totalSize      //要上传的总size  单位：byte
    }.catch {
        //异常回调
    }.collect {
        //成功回调
    }
复制代码

3.2、文件下载

接着再来看看下载，直接贴代码

val localPath = "sdcard//android/data/..../1.apk" 
val path = RxHttp.get("/service/...")     
    .toDownloadAwait(localPath)  //下载需要传入本地文件路径   
    .await()  //返回本地存储路径，这里也就是localPath
复制代码

下载调用toDownloadAwait(String)方法，传入本地文件路径即可，要监听下载进度？也简单，如下：

val localPath = "sdcard//android/data/..../1.apk"  
val path = RxHttp.get("/service/...")      
    .toDownloadAwait(localPath) {       
        //it为Progress对象
        val process = it.progress        //已下载进度 0-100
        val currentSize = it.currentSize //已下载size，单位：byte
        val totalSize = it.totalSize     //要下载的总size 单位：byte      
    }     
    .await()
复制代码

看下toDownloadAwait方法完整签名

/**
 * @param destPath 本地存储路径
 * @param append 是否追加下载，即是否断点下载
 * @param capacity 队列size，仅监听进度回调时生效
 * @param progress 进度回调
 */
fun CallFactory.toDownloadAwait(
    destPath: String,
    append: Boolean = false,
    capacity: Int = 1,
    progress: (suspend (Progress) -> Unit)? = null
): Await<String>
复制代码

如果你需要断点下载，第二个参数传true就可，如下：

val localPath = "sdcard//android/data/..../1.apk"   
val path = RxHttp.get("/service/...")             
    .toDownloadAwait(localPath, true) { 
        //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，那下面如何安全的开启一个协程，做到自动异常捕获，且页面销毁时，自动关闭协程及请求

对于Android 10文件上传/下载，请点击RxHttp 完美适配Android 10/11 上传/下载/进度监听

4、协程开启及关闭

对于协程的开启，Jetpack库里提供了lifecycle-runtime-ktx、lifecycle-viewmodel-ktx这两个框架，可以非常方便的开启协程，并在页面销毁时自动关闭协程，如下：

// FragmentActivity、Fragment环境
lifecycleScope.launch { 
    RxHttp.get("/server/...")      
        .toAwait<Student>()  
        .awaitResult {
            //请求成功，通过it拿到Student对象
        }.onFailure {
            //请求异常，通过it拿到Throwable对象      
        }        
}       
// ViewModel环境
viewModelScope.launch { 
    RxHttp.get("/server/...")      
        .toAwait<Student>()  
        .awaitResult {
            //请求成功，通过it拿到Student对象
        }.onFailure {
            //请求异常，通过it拿到Throwable对象      
        }       
}       
复制代码

如果想手动关闭，拿到launch方法返回的Job对象，通过该对象可以关闭协程，协程关闭，请求就会自定关闭，如下：

//ViewModel环境
val job = lifecycleScope.launch { 
    RxHttp.get("/server/...")      
        .toAwait<Student>()  
        .awaitResult {
            //请求成功，通过it拿到Student对象
        }.onFailure {
            //请求异常，通过it拿到Throwable对象      
        }     
} 
//在合适的时机关闭协程
job.cancel()
复制代码

5、协程多任务处理

我们知道，协程最大的优势就是：能以看起来同步的代码，写出异步的逻辑，这使得我们可以非常优雅的实现多任务场景，比如多请求的并行/串行

5.1、协程串行多个请求

假设，我们有这么一种场景，首先获取Student对象，随后通过studentId获取学生的家庭成员列表，后者依赖于前者，这是典型的串行场景

看看通过协程如何解决这个问题，如下：

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState);
        //启动协程，发送请求
        lifecycleScope.launch { sendRequest() }
    }
    
    suspend fun sendRequest() {
        //获取student对象，null的话，直接返回
        val student = getStudent() ?: return       
        //通过学生Id，查询家庭成员信息
        val personList = getFamilyPersons(student.id) 
        //拿到相关信息后，便可直接更新UI，如：
        tvName.text = student.name
    }

    //挂断方法，获取学生信息
    suspend fun getStudent(): Student? {
        return RxHttp.get("/service/...")
            .add("key", "value")
            .addHeader("headKey", "headValue")
            .toAwait<Student>()
            .tryAwait() //tryAwait，出现异常时，返回null
    }

    //挂断方法，获取家庭成员信息
    suspend fun getFamilyPersons(studentId: Int): List<Person> {
        return RxHttp.get("/service/...")
            .add("studentId", "10000")
            .toAwait<List<Person>>()
            .onErrorReturnItem(ArrayList())  //出现异常时，返回空的List
            .await() 
    }
}
复制代码

我们重点看下协程代码块，首先通过第一个请求拿到Student对象，随后拿到studentId，发送第二个请求获取学习家庭成员列表，拿到后，便可以直接更新UI，怎么样，是不是看起来同步的代码，写出了异步的逻辑。

串行请求中，只要其中一个请求出现异常，协程便会关闭（同时也会关闭请求），停止执行剩下的代码，接着走异常回调

5.2、协程并行多个请求

请求并行，在现实开发中，也是家常便饭，在一个Activity中，我们往往需要拿到多种数据来展示给用户，而这些数据，都是不同接口下发的。

如我们有这样一个页面，顶部是横向滚动的Banner条，Banner条下面展示学习列表，此时就有两个接口，一个获取Banner条列表，一个获取学习列表，它们两个互不依赖，便可以并行执行，如下：

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState);
        //启动协程，发送请求
        lifecycleScope.launch { sendRequest(this) }
    }
    
    //当前在UI线程运行
    suspend fun sendRequest(scope: CoroutineScope) {
        val asyncBanner = getBanners(scope) //这里返回Deferred<List<Banner>>对象
        val asyncPersons = getStudents(scope) //这里返回Deferred<List<Student>>对象
        val banners = asyncBanner.tryAwait()    //这里返回List<Banner>?对象
        val students = asyncPersons.tryAwait()  //这里返回List<Student>?对象
        //开始更新UI
    }

    //挂断方法，获取学生信息
    suspend fun getBanners(scope: CoroutineScope): Deferred<List<Banner>> {
        return RxHttp.get("/service/...")
            .add("key", "value")
            .addHeader("headKey", "headValue")
            .toAwait<List<Banner>>()
            .async(scope)  //注意这里使用async异步操作符
    }

    //挂断方法，获取家庭成员信息
    suspend fun getStudents(scope: CoroutineScope): Deferred<List<Student>> {
        return RxHttp.get("/service/...")
            .add("key", "value")
            .toAwait<List<Student>>()
            .async(scope) //注意这里使用async异步操作符
    }
}
复制代码

在上述代码的两个挂断方法中，均使用了async异步操作符，此时这两个请求就并行发送请求，随后拿到Deferred<T>对象，调用其await()方法，最终拿到Banner列表及Student列表，最后便可以直接更新UI。

划重点

并行跟串行一样，如果其中一个请求出现了异常，协程便会自动关闭（同时关闭请求），停止执行剩下的代码，接着走异常回调。如果想多个请求互不影响，就可以使用上面介绍的onErrorReturn、onErrorReturnItem操作符，出现异常时，给出一个默认对象，又或者使用tryAwait操作符获取返回值，出现异常时，返回null，这样就不会影响其它请求的执行。

6、原理剖析

RxHttp使用到当下流行的注解处理器工具(Annotation Processing Tool，以下简称APT)，像知名的Eventbus、ButterKnife、Dagger2、Glide以及Jetpack库里非常好用Room数据库框架，都使用到了APT，它能够在编译时检索注解信息，通过Javapoet框架生成Java类、方法等相关代码(想生成Kotlin相关代码，使用kotlinpoet)，并因此在运行时做到零性能损耗。

那么，APT给RxHttp带来了哪些优势？RxHttp又是如何使用APT的？继续往下看

说起APT，大家脑海里第一个想到的可能是解耦，没错，解耦是它的一大优势，其实它还有一个更大有优势，那就是根据配置，生成不同的代码逻辑；比如在RxHttp中，默认是不依赖RxJava的，但是如果你需要使用RxHttp + RxJava方式发送请求，就可以在annotationProcessorOptions标签中的rxhttp_rxjava参数来配置RxJava大版本，可传入RxJava2或RxJava3，内部根据传入的RxJava版本，生成不同的代码，这样就可做到一套代码同时兼通RxJava2和RxJava3，如果后续出了RxJava4、RxJava5等新版本，一样可以兼容，而且非常简单。

同时兼容RxJava不同版本，这就是APT带给RxHttp的第一大优势。

RxHttp是如何使用APT？在RxHttp中，一共定义了6个注解，如下：

• @DefaultDomain：用它来指定默认的baseUrl，只能使用一次

• @Domain：指定非默认的baseUrl，可使用多次

• @Parser： 指定自定义的解析器，可使用多次，这个非常强大，可在解析器里写自己数据解析逻辑，并返回任意类型的数据，完美解决服务端返回的数据不规范问题

• @Param：指定自定义的Param，可使用多次，发送统一加密请求时用到

• @OkClient：为不同请求配置不同的OkHttpClient对象，可多次使用

• @Converter：为不同请求配置不同的Converter对象，可多次使用

注：以上6个注解的具体使用方式，请查看RxHttp 注解使用

RxHttp的注解处理器是rxhttp-compiler，它首要任务就是生成RxHttp类，其次就是检索以上6个注解，生成对应的类及方法，这就使得，无论我们如何去自定义，写请求代码时，始终遵循请求三部曲，如我们要发送统一加密的请求，就可以直接使用@Param注解生成的方法，如下：

//发送加密的post表单请求，方法名可通过@Param注解随意指定
val student = RxHttp.postEncryptForm("/service/...")
    .add("key", "value")
    .toAwait<Student>()
    .await()
复制代码

其它5个注解带来的优势就不一一介绍了，总之就是另一大优势，解耦，使得任意请求，皆遵循请求三部曲

RxHttp工作流程

接下来，讲讲RxHttp的工作流程，有5个重要的角色，分别是：

• RxHttp：这是最重要的一个角色，所以请求的唯一入口，内部持有一个Param对象，它的职责是，请求参数/请求头/BaseUrl的处理，请求线程的调度，提供注解生成的方法等等，最终的使命就是通过Param构建一个okhttp3.Request对象，随后在构建一个okhttp3.Call对象，并把Call对象丢给Observable或Await，然后由Observable或Await真正的去执行请求

• Param：它的职责是处理请求参数/请求头/url等一切用来构建okhttp3.Request需要的东西，最终使命就是构建okhttp3.Request对象，它被RxHttp类所持有，RxHttp把构建okhttp3.Request对象所需要的东西，都交给Param去实现的

• Awiat：结合协程发请求时，真正执行网络请求的对象，具体实现类为AwaitImpl,它内部持有Parser对象，请求返回后，将okhttp3.Response丢给Parser去解析，并返回解析后的对象

• Observable：结合RxJava发送请求时，真正执行网络请求的对象，具体实现类ObservableCall内部持有Parser对象，具体的解析工作都交给Parser

• Parser：负责数据解析工作，将数据解析成我们想要的数据类型，这是一个接口对象，内部只有onParse(response: Response): T这一个方法，具体实现类有3个： SmartParser、StreamParser、OkResponseParser，第一个为万能的解析器，内部的toObservable/toAwait方法，就是通过它去实现的；第二是下载文件时用的的解析器；最后一个可同时返回请求头及对应的实体类。

工作流程图如下：

7、总结

看完本文，相信你已经领悟到了RxHttp优雅及简便，业务code的统一处理，失败重试、超时、文件上传/下载及进度监听。

其实，RxHttp远不止这些，本文只是讲解了RxHttp与协程相关的东西，更多优雅的功能，如：多/动态baseUrl的处理、公共参数/请求头的添加、请求加解密、缓存等等，请查看

RxHttp 让你眼前一亮的Http请求框架

RxHttp 全网Http缓存最优解

最后，开源不易，写文章更不易，还需要劳烦大家给本文点个赞，可以的话，再给个star，我将感激不尽，🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏🙏