更新BRV, 更新文档

README.md

@@ -107,7 +107,7 @@ implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.0'
 // 支持自动下拉刷新和缺省页的(可选)
 implementation 'com.github.liangjingkanji:BRV:1.3.9'
 
-implementation 'com.github.liangjingkanji:Net:2.2.16'
+implementation 'com.github.liangjingkanji:Net:2.2.17'
 ```
 
 <br>

build.gradle

@@ -18,8 +18,8 @@
 
 buildscript {
     ext {
-        kotlin_version = '1.4.0'
-        brv_version = '1.3.10'
+        kotlin_version = '1.4.10'
+        brv_version = '1.3.11'
         coroutine_version = '1.3.7'
         glide_version = '4.9.0'
         room_version = "2.2.5"

docs/api/net/com.drake.net.scope/-android-scope/index.md

@@ -26,7 +26,6 @@
 
 | Name | Summary |
 |---|---|
-| [adjustDispatcher](adjust-dispatcher.md) | `fun adjustDispatcher(): CoroutineDispatcher` |
 | [cancel](cancel.md) | `open fun cancel(cause: CancellationException? = null): `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)<br>`open fun cancel(message: `[`String`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)`, cause: `[`Throwable`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-throwable/index.html)`? = null): `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html) |
 | [catch](catch.md) | `open fun catch(e: `[`Throwable`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-throwable/index.html)`): `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)<br>当作用域内发生异常时回调`open fun catch(block: `[`AndroidScope`](./index.md)`.(`[`Throwable`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-throwable/index.html)`) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)` = {}): `[`AndroidScope`](./index.md) |
 | [finally](finally.md) | `open fun finally(e: `[`Throwable`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-throwable/index.html)`?): `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)<br>无论正常或者异常结束都将最终执行`open fun finally(block: `[`AndroidScope`](./index.md)`.(`[`Throwable`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-throwable/index.html)`?) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)` = {}): `[`AndroidScope`](./index.md) |

docs/api/net/com.drake.net.utils/kotlinx.coroutines.-coroutine-scope/fastest.md

@@ -22,3 +22,16 @@
 
 [DeferredTransform](../../com.drake.net.transform/-deferred-transform/index.md)
 
+`suspend fun <T, R> CoroutineScope.fastest(deferredList: `[`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/index.html)`<`[`DeferredTransform`](../../com.drake.net.transform/-deferred-transform/index.md)`<T, R>>): R`
+
+该函数将选择[deferredList](fastest.md#com.drake.net.utils$fastest(kotlinx.coroutines.CoroutineScope, kotlin.collections.List((com.drake.net.transform.DeferredTransform((com.drake.net.utils.fastest.T, com.drake.net.utils.fastest.R)))))/deferredList)中的Deferred执行[Deferred.await](#), 然后将返回最快的结果
+执行过程中的异常将被忽略, 如果全部抛出异常则将抛出最后一个Deferred的异常
+
+### Parameters
+
+`deferredList` - 一系列并发任务
+
+**See Also**
+
+[DeferredTransform](../../com.drake.net.transform/-deferred-transform/index.md)
+

docs/api/net/com.drake.net.utils/kotlinx.coroutines.-coroutine-scope/index.md

@@ -4,4 +4,4 @@
 
 | Name | Summary |
 |---|---|
-| [fastest](fastest.md) | 该函数将选择[deferredArray](fastest.md#com.drake.net.utils$fastest(kotlinx.coroutines.CoroutineScope, kotlin.Array((kotlinx.coroutines.Deferred((com.drake.net.utils.fastest.T)))))/deferredArray)中的Deferred执行[Deferred.await](#), 然后将返回最快的结果 执行过程中的异常将被忽略, 如果全部抛出异常则将抛出最后一个Deferred的异常`suspend fun <T> CoroutineScope.fastest(vararg deferredArray: Deferred<T>): T`<br>`suspend fun <T, R> CoroutineScope.fastest(vararg deferredArray: `[`DeferredTransform`](../../com.drake.net.transform/-deferred-transform/index.md)`<T, R>): R` |
+| [fastest](fastest.md) | 该函数将选择[deferredArray](fastest.md#com.drake.net.utils$fastest(kotlinx.coroutines.CoroutineScope, kotlin.Array((kotlinx.coroutines.Deferred((com.drake.net.utils.fastest.T)))))/deferredArray)中的Deferred执行[Deferred.await](#), 然后将返回最快的结果 执行过程中的异常将被忽略, 如果全部抛出异常则将抛出最后一个Deferred的异常`suspend fun <T> CoroutineScope.fastest(vararg deferredArray: Deferred<T>): T`<br>`suspend fun <T, R> CoroutineScope.fastest(vararg deferredArray: `[`DeferredTransform`](../../com.drake.net.transform/-deferred-transform/index.md)`<T, R>): R`<br>该函数将选择[deferredList](fastest.md#com.drake.net.utils$fastest(kotlinx.coroutines.CoroutineScope, kotlin.collections.List((com.drake.net.transform.DeferredTransform((com.drake.net.utils.fastest.T, com.drake.net.utils.fastest.R)))))/deferredList)中的Deferred执行[Deferred.await](#), 然后将返回最快的结果 执行过程中的异常将被忽略, 如果全部抛出异常则将抛出最后一个Deferred的异常`suspend fun <T, R> CoroutineScope.fastest(deferredList: `[`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/index.html)`<`[`DeferredTransform`](../../com.drake.net.transform/-deferred-transform/index.md)`<T, R>>): R` |

docs/api/net/com.drake.net.utils/kotlinx.coroutines.flow.-flow/index.md

@@ -5,4 +5,4 @@
 | Name | Summary |
 |---|---|
 | [listen](listen.md) | 收集Flow结果并过滤重复结果`fun <T> Flow<`[`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/index.html)`<T>>.listen(lifecycleOwner: LifecycleOwner? = null, lifeEvent: Event = Lifecycle.Event.ON_DESTROY, dispatcher: CoroutineDispatcher = Dispatchers.Main, block: (`[`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/index.html)`<T>) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`): `[`AndroidScope`](../../com.drake.net.scope/-android-scope/index.md) |
-| [scope](scope.md) | `fun <T> Flow<T>.scope(owner: LifecycleOwner? = null, event: Event = Lifecycle.Event.ON_DESTROY, dispatcher: CoroutineDispatcher = Dispatchers.Main, action: suspend (value: T) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`): `[`AndroidScope`](../../com.drake.net.scope/-android-scope/index.md) |
+| [scope](scope.md) | Flow直接创建作用域`fun <T> Flow<T>.scope(owner: LifecycleOwner? = null, event: Event = Lifecycle.Event.ON_DESTROY, dispatcher: CoroutineDispatcher = Dispatchers.Main, action: suspend (value: T) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`): `[`AndroidScope`](../../com.drake.net.scope/-android-scope/index.md) |

docs/api/net/com.drake.net.utils/kotlinx.coroutines.flow.-flow/scope.md

@@ -2,4 +2,14 @@
 
 # scope
 
-`inline fun <T> Flow<T>.scope(owner: LifecycleOwner? = null, event: Event = Lifecycle.Event.ON_DESTROY, dispatcher: CoroutineDispatcher = Dispatchers.Main, crossinline action: suspend (value: T) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`): `[`AndroidScope`](../../com.drake.net.scope/-android-scope/index.md)
+`inline fun <T> Flow<T>.scope(owner: LifecycleOwner? = null, event: Event = Lifecycle.Event.ON_DESTROY, dispatcher: CoroutineDispatcher = Dispatchers.Main, crossinline action: suspend (value: T) -> `[`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`): `[`AndroidScope`](../../com.drake.net.scope/-android-scope/index.md)
+
+Flow直接创建作用域
+
+### Parameters
+
+`owner` - 跟随的生命周期组件
+
+`event` - 销毁时机
+
+`dispatcher` - 指定调度器

docs/api/net/package-list

@@ -21,6 +21,7 @@ $dokka.location:com.drake.net.error$NetCancellationException(kotlinx.coroutines.
 $dokka.location:com.drake.net.transform$transform(kotlinx.coroutines.Deferred((com.drake.net.transform.transform.T)), kotlin.Function1((com.drake.net.transform.transform.T, com.drake.net.transform.transform.R)))com.drake.net.transform/kotlinx.coroutines.-deferred/transform.md
 $dokka.location:com.drake.net.utils$fastest(kotlinx.coroutines.CoroutineScope, kotlin.Array((com.drake.net.transform.DeferredTransform((com.drake.net.utils.fastest.T, com.drake.net.utils.fastest.R)))))com.drake.net.utils/kotlinx.coroutines.-coroutine-scope/fastest.md
 $dokka.location:com.drake.net.utils$fastest(kotlinx.coroutines.CoroutineScope, kotlin.Array((kotlinx.coroutines.Deferred((com.drake.net.utils.fastest.T)))))com.drake.net.utils/kotlinx.coroutines.-coroutine-scope/fastest.md
+$dokka.location:com.drake.net.utils$fastest(kotlinx.coroutines.CoroutineScope, kotlin.collections.List((com.drake.net.transform.DeferredTransform((com.drake.net.utils.fastest.T, com.drake.net.utils.fastest.R)))))com.drake.net.utils/kotlinx.coroutines.-coroutine-scope/fastest.md
 $dokka.location:com.drake.net.utils$foreach(android.database.Cursor, kotlin.Function1((android.database.Cursor, kotlin.Unit)))com.drake.net.utils/android.database.-cursor/foreach.md
 $dokka.location:com.drake.net.utils$getSavedModel(androidx.fragment.app.Fragment)com.drake.net.utils/androidx.fragment.app.-fragment/get-saved-model.md
 $dokka.location:com.drake.net.utils$getSavedModel(androidx.fragment.app.FragmentActivity)com.drake.net.utils/androidx.fragment.app.-fragment-activity/get-saved-model.md

docs/auto-error-handle.md

@@ -9,9 +9,49 @@ Net具备完善的全局错误处理机制
 
 但是所有的错误信息和错误码都会在LogCat控制台看到, 具体查看[异常追踪](exception-track.md)
 
+
+## 手动错误处理
+<br>
+
+!!! note
+    假设不需要全局错误处理, 我们可以`catch`作用域来自己处理异常
+
+
+```kotlin
+scopeNetLife {
+    val data = Get<String>("http://www.thisiserror.com/").await()
+}.catch {
+    // 这里进行错误处理, it即为错误的异常对象
+}
+```
+
+catch里面的`it`属于异常对象, 这里列举可能存在的异常
+
+| 异常 | 描述 |
+|-|-|
+| NetworkError | 无网络 |
+| URLError | 地址错误 |
+| HostError | 域名错误 |
+| ConnectTimeoutError | 连接超时 |
+| ReadTimeoutError | 读取超时 |
+| DownloadError | 下载异常 |
+| NoCacheError | 没有缓存 |
+| ParseError | 解析错误, `Convert`中发生的未捕获异常都算解析错误 |
+| RequestParamsException | 请求参数错误 `400 - 499` 范围内错误码 |
+| ServerResponseException | 服务器错误 `500 - 599` 范围内错误码 |
+| ExecutionException | 加载图片异常等 |
+| NullPointerException | 空指针, 一般是在作用域内操作一个空的对象 |
+| ConnectException | 连接异常 |
+| WriteException | 写入异常 |
+| ReadException | 读取异常 |
+| ResponseException | 响应异常, 这里属于后端返回的错误码和其定义的成功码不匹配 |
+
+假设你重写`DefaultConvert`可以改变异常发生的条件, 当然你在转换器或者拦截器中抛出任何异常都会被捕获或者全局处理, 这里你可以自定义你的异常
+
+
 ## 默认错误处理
 
-Net默认的错误处理方式
+Net默认的错误处理源码
 
 <img src="https://i.imgur.com/t1Ep8tj.png" width="70%"/>
 

docs/config.md

@@ -4,6 +4,7 @@ class App : Application() {
     override fun onCreate() {
         super.onCreate()
 
+        // http://182.92.97.186/  这是接口全局域名, 可以使用NetConfig.host读写
         initNet("http://182.92.97.186/") {
             converter(JsonConvert()) // 转换器
             cacheEnabled() // 开启缓存
@@ -12,20 +13,6 @@ class App : Application() {
 }
 ```
 
-```kotlin
-class App : Application() {
-    override fun onCreate() {
-        super.onCreate()
-
-        initNet("http://182.92.97.186/") {
-            converter(JsonConvert()) // 转换器
-            cacheEnabled() // 开启缓存
-        }
-    }
-}
-```
-
-
 initNet 作用域内可选函数
 
 <img src="https://i.imgur.com/G8W4oDX.png" width="60%"/>

docs/index.md

@@ -30,12 +30,30 @@ Net使用协程发起网络, 但是即使不会协程也可以使用该框架
 
         // 随任务同时进行, 但是数据依然可以按序返回
         val aData = Deferred.await() // 等待任务A返回数据
-        val bData = bDeferred.await() // 等待任务A返回数据
+        val bData = bDeferred.await() // 等待任务B返回数据
     }
     ```
 
 多个网络请求放在同一个作用域内就可以统一控制, 如果你的多个网络请求毫无关联, 你可以创建多个作用域.
 
+<br>
+
+!!! note
+    当`Get`或`Post`等函数调用就会开始发起网络请求, `await`只是等待其请求成功返回结果, 所以如果你在`await`后执行的网络请求,这不属于并发(属于串行)
+
+并发的错误示例
+```kotlin hl_lines="3"
+scopeNetLife {
+    // 请求A
+    val aDeferred = Get<String>("http://www.baidu.com/").await()
+    // 请求B, 由于上面使用`await()`函数, 所以必须等待A请求返回结果后才会执行B
+    val bDeferred = Get<String>("http://www.baidu.com/")
+
+    val bData = bDeferred.await() // 等待任务B返回数据
+}
+```
+
+
 <br>
 关于JSON解析以及全局URL等初始化配置后面讲解
 

net/src/main/java/com/drake/net/utils/ScopeUtils.kt

@@ -52,19 +52,20 @@ fun FragmentActivity.scopeDialog(
         dialog: Dialog? = null,
         cancelable: Boolean = true,
         dispatcher: CoroutineDispatcher = Dispatchers.Main,
-        block: suspend CoroutineScope.() -> Unit
-                                ) = DialogCoroutineScope(this, dialog, cancelable, dispatcher).launch(block)
+        block: suspend CoroutineScope.() -> Unit) =
+        DialogCoroutineScope(this, dialog, cancelable, dispatcher).launch(block)
 
 fun Fragment.scopeDialog(
         dialog: Dialog? = null,
         cancelable: Boolean = true,
         dispatcher: CoroutineDispatcher = Dispatchers.Main,
-        block: suspend CoroutineScope.() -> Unit
-                        ) = DialogCoroutineScope(requireActivity(), dialog, cancelable, dispatcher).launch(block)
+        block: suspend CoroutineScope.() -> Unit) =
+        DialogCoroutineScope(requireActivity(), dialog, cancelable, dispatcher).launch(block)
 
 // </editor-fold>
 
 
+//<editor-fold desc="缺省页/分页">
 /**
  * 自动处理缺省页的异步作用域
  * 作用域开始执行时显示加载中缺省页
@@ -76,8 +77,9 @@ fun Fragment.scopeDialog(
  *
  * 布局被销毁或者界面关闭作用域被取消
  */
-fun StateLayout.scope(dispatcher: CoroutineDispatcher = Dispatchers.Main,
-                      block: suspend CoroutineScope.() -> Unit): NetCoroutineScope {
+fun StateLayout.scope(
+        dispatcher: CoroutineDispatcher = Dispatchers.Main,
+        block: suspend CoroutineScope.() -> Unit): NetCoroutineScope {
     val scope = StateCoroutineScope(this, dispatcher)
     scope.launch(block)
     return scope
@@ -96,13 +98,16 @@ fun StateLayout.scope(dispatcher: CoroutineDispatcher = Dispatchers.Main,
  *
  * 布局被销毁或者界面关闭作用域被取消
  */
-fun PageRefreshLayout.scope(dispatcher: CoroutineDispatcher = Dispatchers.Main,
-                            block: suspend CoroutineScope.() -> Unit): PageCoroutineScope {
+fun PageRefreshLayout.scope(
+        dispatcher: CoroutineDispatcher = Dispatchers.Main,
+        block: suspend CoroutineScope.() -> Unit): PageCoroutineScope {
     val scope = PageCoroutineScope(this, dispatcher)
     scope.launch(block)
     return scope
 }
+//</editor-fold>
 
+//<editor-fold desc="异步任务">
 /**
  * 异步作用域
  *
@@ -113,18 +118,16 @@ fun scope(dispatcher: CoroutineDispatcher = Dispatchers.Main,
     return AndroidScope(dispatcher = dispatcher).launch(block)
 }
 
-fun LifecycleOwner.scopeLife(
-        lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_DESTROY,
-        dispatcher: CoroutineDispatcher = Dispatchers.Main,
-        block: suspend CoroutineScope.() -> Unit
-                            ) = AndroidScope(this, lifeEvent, dispatcher).launch(block)
+fun LifecycleOwner.scopeLife(lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_DESTROY,
+                             dispatcher: CoroutineDispatcher = Dispatchers.Main,
+                             block: suspend CoroutineScope.() -> Unit) = AndroidScope(this, lifeEvent, dispatcher).launch(block)
 
-fun Fragment.scopeLife(
-        lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_STOP,
-        dispatcher: CoroutineDispatcher = Dispatchers.Main,
-        block: suspend CoroutineScope.() -> Unit
-                      ) = AndroidScope(this, lifeEvent, dispatcher).launch(block)
+fun Fragment.scopeLife(lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_STOP,
+                       dispatcher: CoroutineDispatcher = Dispatchers.Main,
+                       block: suspend CoroutineScope.() -> Unit) = AndroidScope(this, lifeEvent, dispatcher).launch(block)
+//</editor-fold>
 
+//<editor-fold desc="网络">
 /**
  * 网络请求的异步作用域
  * 自动显示错误信息吐司
@@ -135,35 +138,37 @@ fun scopeNet(dispatcher: CoroutineDispatcher = Dispatchers.Main,
              block: suspend CoroutineScope.() -> Unit) = NetCoroutineScope(dispatcher = dispatcher).launch(block)
 
 
-fun LifecycleOwner.scopeNetLife(
-        lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_DESTROY,
-        dispatcher: CoroutineDispatcher = Dispatchers.Main,
-        block: suspend CoroutineScope.() -> Unit
-                               ) = NetCoroutineScope(this, lifeEvent, dispatcher).launch(block)
+fun LifecycleOwner.scopeNetLife(lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_DESTROY,
+                                dispatcher: CoroutineDispatcher = Dispatchers.Main,
+                                block: suspend CoroutineScope.() -> Unit) = NetCoroutineScope(this, lifeEvent, dispatcher).launch(block)
 
 /**
  * Fragment应当在[Lifecycle.Event.ON_STOP]时就取消作用域, 避免[Fragment.onDestroyView]导致引用空视图
  */
-fun Fragment.scopeNetLife(
-        lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_STOP,
-        dispatcher: CoroutineDispatcher = Dispatchers.Main,
-        block: suspend CoroutineScope.() -> Unit
-                         ) = NetCoroutineScope(this, lifeEvent, dispatcher).launch(block)
+fun Fragment.scopeNetLife(lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_STOP,
+                          dispatcher: CoroutineDispatcher = Dispatchers.Main,
+                          block: suspend CoroutineScope.() -> Unit) = NetCoroutineScope(this, lifeEvent, dispatcher).launch(block)
+//</editor-fold>
 
 
+/**
+ * Flow直接创建作用域
+ * @param owner 跟随的生命周期组件
+ * @param event 销毁时机
+ * @param dispatcher 指定调度器
+ */
 @OptIn(InternalCoroutinesApi::class)
-inline fun <T> Flow<T>.scope(
-        owner: LifecycleOwner? = null,
-        event: Lifecycle.Event = Lifecycle.Event.ON_DESTROY,
-        dispatcher: CoroutineDispatcher = Dispatchers.Main,
-        crossinline action: suspend (value: T) -> Unit
-                            ): AndroidScope = AndroidScope(owner, event, dispatcher).launch {
+inline fun <T> Flow<T>.scope(owner: LifecycleOwner? = null,
+                             event: Lifecycle.Event = Lifecycle.Event.ON_DESTROY,
+                             dispatcher: CoroutineDispatcher = Dispatchers.Main,
+                             crossinline action: suspend (value: T) -> Unit): AndroidScope = AndroidScope(owner, event, dispatcher).launch {
     this@scope.collect(object : FlowCollector<T> {
         override suspend fun emit(value: T) = action(value)
     })
 }
 
 
+//<editor-fold desc="并发返回最快">
 /**
  * 该函数将选择[deferredArray]中的Deferred执行[Deferred.await], 然后将返回最快的结果
  * 执行过程中的异常将被忽略, 如果全部抛出异常则将抛出最后一个Deferred的异常
@@ -264,6 +269,7 @@ suspend fun <T, R> CoroutineScope.fastest(deferredList: List<DeferredTransform<T
     }
     return chan.receive()
 }
+//</editor-fold>