Update doc

docs/error-default.md

@@ -0,0 +1,27 @@
+Net具备完善的错误处理机制, 能捕获大部分网络请求或者异步任务导致的崩溃, 减少App崩溃和收集详细的错误信息
+
+以下场景的崩溃会被捕获到
+
+- 作用域内部 (scope**等函数大括号`{}`内部)
+- 拦截器中 (Interceptor/RequestInterceptor)
+- 转换器中 (NetConverter)
+
+
+<br>
+
+如果捕获到错误默认会执行以下操作
+
+-  `Logcat`中显示详细的异常堆栈信息, 如果想要输出更详细内容请继续阅读
+-  `Toast`吐司显示错误文本信息, 如果想要自定义或者国际化错误文本请阅读[自定义错误提示](error_tip)
+
+<br>
+要改变以上异常处理流程就需要自定义异常处理器
+
+
+
+
+
+
+
+
+

docs/error-global.md

@@ -0,0 +1,24 @@
+Net可以通过实现`NetErrorHandler`接口来监听全局错误处理, 当你通过`setErrorHandler`后Net就不会再执行默认的错误处理了
+
+```kotlin
+NetConfig.init("http://localhost:80/") {
+
+    setErrorHandler(object : NetErrorHandler() {
+        override fun onError(e: Throwable) {
+            super.onError(e)
+        }
+
+        override fun onStateError(e: Throwable, view: View) {
+            super.onStateError(e, view)
+        }
+    })
+}
+```
+
+|场景|处理函数|处理方式|
+|-|-|-|
+|普通网络请求/自动加载框|`onError`| 默认吐司错误信息 |
+|使用自动处理缺省页的作用域|`onStateError`| 仅部分错误信息会吐司, 因为缺省页不需要所有的错误信息都吐司(toast)提示, 因为错误页可能已经展示错误信息, 所以这里两者处理的函数区分. |
+
+> 默认全局处理实现源码: [NetErrorHandler](https://github.com/liangjingkanji/Net/blob/97c31dddde7ced5aa75411d2581c858ca494669e/net/src/main/java/com/drake/net/interfaces/NetErrorHandler.kt#L18)
+> `scope/scopeLife`不会触发任何全局错误NetErrorHandler, 请使用单例错误处理方式`catch`, 因为`scope`用于处理异步任务,不应当用于网络请求

docs/error-handle.md

@@ -1,162 +0,0 @@
-## 默认异常处理
-Net具备完善的异常处理机制, 默认情况发生错误会执行以下操作
-
-1. `Logcat`中显示详细的异常堆栈信息
-2. `Toast`吐司显示异常信息(默认使用内置的异常文本信息)
-
-要改变以上异常处理流程就需要自定义异常处理器
-
-捕获异常分为两种
-
-1. 作用域内部异常捕获
-2. 捕获整个作用域内部所有异常
-
-## 作用域内部异常捕获
-一个作用域内常常有多个请求发生. 默认情况下一个请求发生错误就会取消当前作用域内部所有协程
-
-例如
-```kotlin
-scopeNetLife {
-    Get<String>("api").await() // 失败
-    Get<String>("api2").await() // 上面失败, 此处也不会执行
-}
-```
-
-捕获第一个协程避免终止后续执行
-```kotlin
-scopeNetLife {
-    try {
-        Get<String>("api").await() // 失败
-    } catch(e:Exception) {
-    }
-    Get<String>("api2").await() // 上面失败, 此处继续执行
-}
-```
-当然如果你创建不同的作用域分别请求那是互不影响的
-```kotlin
-scopeNetLife {
-    Get<String>("api").await() // 失败
-}
-scopeNetLife {
-    Get<String>("api2").await() // 上面失败, 此处完全不受影响
-}
-```
-
-## 捕获整个作用域
-
-捕获整个作用域分为两类
-
-1. 单例处理异常(针对每个作用域)
-2. 全局处理异常(针对所有作用域, [个别除外](#scope))
-
-### 单例处理异常
-```kotlin
-scope {
-    val data = Get<String>("http://www.thisiserror.com/").await()
-}.catch {
-    // 协程内部发生错误回调, it为异常
-}.finally {
-    // 协程内协程全部执行完成, it为异常(如果是正常结束则it为null)
-}
-```
-
-以下函数幕后字段`it`为异常对象, 如果正常完成it则为null. 如果属于请求被手动取消则it为`CancellationException`
-
-| 函数 | 描述 |
-|-|-|
-| catch | 作用域被`catch`则不会被传递到全局异常处理回调中: [全局处理异常](exception-handle.md), 除非使用`handleError`再次传递给全局 |
-| finally | 同样可以获取到异常对象, 且不影响全局异常回调处理 |
-
-### 全局处理异常
-
-Net默认就会处理异常错误避免崩溃. 但是如果你想要自定义或者监听全局错误, 你可以覆盖默认的错误处理.  在`initNet`或者`NetConfig.errorHandler`函数里面自定义全局错误处理
-
-默认情况下不需要去定义异常处理, 因为`NetErrorHandler`默认实现适用于大部分情况的异常处理.
-
-|场景|处理函数|处理方式|
-|-|-|-|
-|普通网络请求/自动加载框|`onError`|`toast`提示后端定义的错误消息|
-|使用自动处理缺省页的作用域|`onStateError`|部分错误信息`toast`, 因某些常见错误已经显示为错误缺省页(比如无网络), 无需再吐司 |
-
-示例
-
-```kotlin
-NetConfig.init("http://localhost:80/") {
-
-    setErrorHandler(object : NetErrorHandler() {
-        override fun onError(e: Throwable) {
-            super.onError(e)
-        }
-
-        override fun onStateError(e: Throwable, view: View) {
-            super.onStateError(e, view)
-        }
-    })
-}
-```
-
-缺省页不需要所有的错误信息都吐司(toast)提示, 因为错误页可能已经展示错误信息, 所以这里两者处理的函数区分.
-
-但是所有的错误信息和错误码都会在LogCat控制台看到, 具体查看[异常追踪](exception-track.md).
-
-> 本章末尾有默认实现的源码, 可供参考或者理解: [默认处理](#_2)
-
-
-## 异常对象
-
-以下为Net内部常见发生的异常对象. 不代表全部异常, 例如不包含开发者自己定义的异常
-
-> `scope/scopeLife`不会触发任何全局错误NetErrorHandler, 请使用单例错误处理方式`catch`, 因为`scope`用于处理异步任务,不应当用于网络请求
-
-
-| 异常 | 描述 |
-|-|-|
-| NetException | 未知的网络异常, 一般情况应当继承他来创建自定义的网络异常  |
-| HttpFailureException | Http请求错误, Http请求失败(onFailure) |
-| HttpResponseException | Http请求成功后发生的错误, Http请求成功但发生异常(onResponse) |
-| URLParseException | 地址错误 |
-| NetUnknownHostException | 域名错误 |
-| NetSocketTimeoutException | 连接超时 |
-| NetConnectException | 连接服务器失败 |
-| DownloadFileException | 下载文件异常 |
-| ConvertException | 解析错误, `NetConvert`中发生的未捕获异常都算解析错误 |
-| RequestParamsException | 请求参数错误 `400 - 499` 范围内错误码 |
-| ServerResponseException | 服务器错误 `500 - 599` 范围内错误码 |
-| ResponseException | 错误码异常, 一般应用于后端返回的错误码和其定义的成功码不匹配 |
-| NullPointerException | 空指针, 一般是在作用域内操作一个空的对象 |
-
-假设你重写`NetConverter`可以改变异常发生的条件, 当然你在转换器或者拦截器中抛出任何异常都会被捕获或者全局处理 <br>
-转换器中发生的所有异常除非是NetException的子类否则都将被ConvertException包裹(即捕获的是ConvertException).
-
-
-## 覆盖默认异常处理
-
-覆盖默认错误处理有两种方式
-
-### 1) 实现NetErrorHandler
-
-源码位于: `NetConfig`
-
-<img src="https://i.loli.net/2021/08/14/cTr57oulbhwxEaQ.png" width="400"/>
-
-缺省页的错误处理是单独的: `onStateError`
-
-### 2)  仅覆盖错误信息文本
-
-默认错误处理的文本被定义在`strings.xml`中, 我们可以在项目中使用同名覆盖或者多语言
-```xml
-<!--网络请求异常-->
-<string name="net_network_error">当前网络不可用</string>
-<string name="net_url_error">请求资源地址错误</string>
-<string name="net_host_error">无法找到指定服务器主机</string>
-<string name="net_connect_timeout_error">连接服务器超时，%s</string>
-<string name="net_download_error">下载过程发生错误</string>
-<string name="net_no_cache_error">读取缓存错误</string>
-<string name="net_parse_error">解析数据时发生异常</string>
-<string name="net_request_error">请求参数错误</string>
-<string name="net_server_error">服务响应错误</string>
-<string name="net_null_error">数据为空</string>
-<string name="net_error">未知网络错误</string>
-<string name="net_other_error">未知错误</string>
-<string name="no_error_message">无错误信息</string>
-```

docs/error-implemention.md

@@ -0,0 +1,81 @@
+以下为Net内部常见发生的异常对象. 不代表全部异常, 例如不包含开发者自己定义的异常
+
+
+| 异常 | 描述 |
+|-|-|
+| NetException | 未知的网络异常, 一般情况应当继承他来创建自定义的网络异常  |
+| HttpFailureException | Http请求错误, Http请求失败(onFailure) |
+| HttpResponseException | Http请求成功后发生的错误, Http请求成功但发生异常(onResponse) |
+| URLParseException | 地址错误 |
+| NetUnknownHostException | 域名错误 |
+| NetSocketTimeoutException | 连接超时 |
+| NetConnectException | 连接服务器失败 |
+| DownloadFileException | 下载文件异常 |
+| ConvertException | 解析错误, `NetConvert`中发生的未捕获异常都算解析错误 |
+| RequestParamsException | 请求参数错误 `400 - 499` 范围内错误码 |
+| ServerResponseException | 服务器错误 `500 - 599` 范围内错误码 |
+| ResponseException | 错误码异常, 一般应用于后端返回的错误码和其定义的成功码不匹配 |
+| NullPointerException | 空指针, 一般是在作用域内操作一个空的对象 |
+
+## 自定义异常
+
+我们可以在转换器(NetConverter)或者拦截器(Interceptor)中抛出任何异常对象, 比如token失效我们抛出一个自定义的`TokenException`异常对象. <br>
+该异常对象在单例或全局错误处理都可以被收到. 可以用于判断是否为token失效(失效则跳转到登录页面)
+
+
+> 转换器中发生的所有异常除非是NetException的子类否则都将被ConvertException包裹(即捕获的是ConvertException, cause才为实际抛出异常).
+
+## 使用异常属性
+
+Net自带的一些异常都会有一个类型为Any的属性`tag`. 可以用来传递任何对象来用于判断错误类型. 比如`ResponseException`我常用于作为请求服务器成功但是服务器业务错误. 然后tag为业务错误码
+
+示例代码
+
+在转换器中获取401
+
+```kotlin
+class SerializationConverter(
+    val success: String = "0",
+    val code: String = "code",
+    val message: String = "msg"
+) : NetConverter {
+
+    override fun <R> onConvert(succeed: Type, response: Response): R? {
+        try {
+            return NetConverter.onConvert<R>(succeed, response)
+        } catch (e: ConvertException) {
+            val code = response.code
+            when {
+                code in 200..299 -> { // 请求成功
+                // ... 假设Token失效. 后端返回业务错误码 srvCode = 401
+                    throw ResponseException(response, errorMessage, tag = srvCode) // 将业务错误码作为tag传递
+                }
+                code in 400..499 -> throw RequestParamsException(response, code.toString()) // 请求参数错误
+                code >= 500 -> throw ServerResponseException(response, code.toString()) // 服务器异常错误
+                else -> throw ConvertException(response)
+            }
+        }
+    }
+}
+```
+
+全局错误处理器
+
+```kotlin
+// 创建错误处理器
+MyErrorHandler : NetErrorHandler {
+    override fun onError(e: Throwable) {
+    // .... 其他错误
+        if (e is ResponseException && e.tag == 401) { // 判断异常为token失效
+            Engine.currentActivity?.let {
+                it.startActivity(Intent(it, LoginActivity::class.java))
+            }
+        }
+    }
+}
+
+// 初始化Net的时候设置错误处理器
+NetConfig.init("host") {
+    setErrorHandler(MyErrorHandler()
+}
+```

docs/error-single.md

@@ -0,0 +1,59 @@
+单例捕获即只捕获某个作用域或者接口, 不会影响到全局
+
+- 捕获请求
+- 捕获作用域
+
+<br>
+
+## 捕获请求
+
+一个作用域内常常有多个请求发生. 默认情况下一个请求发生错误就会取消当前作用域内部所有协程, 这个时候我们可以捕获错误请求来进行其他处理
+
+例如
+```kotlin
+scopeNetLife {
+    Get<String>("api").await() // 失败
+    Get<String>("api2").await() // 上面失败, 此处也不会执行
+}
+```
+
+捕获第一个协程避免终止后续执行
+```kotlin
+scopeNetLife {
+    try {
+        Get<String>("api").await() // 失败
+    } catch(e:Exception) {
+    }
+    Get<String>("api2").await() // 上面失败, 此处继续执行
+}
+```
+当然如果你创建不同的作用域分别请求那是互不影响的
+```kotlin
+scopeNetLife {
+    Get<String>("api").await() // 失败
+}
+scopeNetLife {
+    Get<String>("api2").await() // 上面失败, 此处完全不受影响
+}
+```
+
+<br>
+
+## 捕获作用域
+
+```kotlin
+scope {
+    val data = Get<String>("http://www.thisiserror.com/").await()
+}.catch {
+    // 协程内部发生错误回调, it为异常
+}.finally {
+    // 协程内协程全部执行完成, it为异常(如果是正常结束则it为null)
+}
+```
+
+以下函数幕后字段`it`为异常对象, 如果正常完成it则为null. 如果属于请求被手动取消则it为`CancellationException`
+
+| 函数 | 描述 |
+|-|-|
+| catch | 作用域被`catch`则不会被传递到全局异常处理回调中: [全局处理异常](exception-handle.md), 除非使用`handleError`再次传递给全局 |
+| finally | 同样可以获取到异常对象, 且不影响全局异常回调处理 |

docs/error-tip.md

@@ -0,0 +1,28 @@
+如果你仅仅是想修改默认吐司的错误文本信息或者做国际化语言
+
+## 复写NetErrorHandler
+这实际上就是自定义全局错误处理. 不过你可以复制默认的实现仅修改下文本信息即可
+
+<img src="https://s2.loli.net/2022/03/01/mQNuoUwtxfK8P6E.png" width="500"/>
+
+
+## 复写XML
+
+默认错误处理的文本被定义在`strings.xml`中, 我们可以在项目中使用同名覆盖或者多语言
+
+```xml
+<!--网络请求异常-->
+<string name="net_network_error">当前网络不可用</string>
+<string name="net_url_error">请求资源地址错误</string>
+<string name="net_host_error">无法找到指定服务器主机</string>
+<string name="net_connect_timeout_error">连接服务器超时，%s</string>
+<string name="net_download_error">下载过程发生错误</string>
+<string name="net_no_cache_error">读取缓存错误</string>
+<string name="net_parse_error">解析数据时发生异常</string>
+<string name="net_request_error">请求参数错误</string>
+<string name="net_server_error">服务响应错误</string>
+<string name="net_null_error">数据为空</string>
+<string name="net_error">未知网络错误</string>
+<string name="net_other_error">未知错误</string>
+<string name="no_error_message">无错误信息</string>
+```

mkdocs.yml

@@ -53,7 +53,12 @@ nav:
   - ViewModel: view-model.md
   - 切换线程: switch-thread.md
   - OkHttpClient: okhttp-client.md
-  - 错误处理: error-handle.md
+  - 错误处理:
+      - 默认错误: error-default.md
+      - 单例错误: error-single.md
+      - 全局错误: error-global.md
+      - 自定义错误提示: error-tip.md
+      - 自定义错误对象: error-implemention.md
   - 定位异常: exception-track.md
   - 拦截器: interceptor.md
   - 标签: tag.md