docs: 使用文档

liangjingkanji · Aug 5, 2023 · c37f278 · c37f278
1 parent a50981f
commit c37f278
Show file tree

Hide file tree

Showing 8 changed files with 139 additions and 108 deletions.
diff --git a/docs/config.md b/docs/config.md
@@ -2,7 +2,7 @@
 
 ## 初始配置
 
-两种方式初始配置, 大部分情况下不初始化也能直接使用
+两种方式初始配置, 不初始化也能直接使用
 
 === "Net初始化"
     ```kotlin

diff --git a/docs/css/extra.css b/docs/css/extra.css
@@ -44,4 +44,8 @@ code,
 .md-typeset code,
 .md-typeset {
     font-size: 14px !important;
+}
+
+.md-typeset .admonition-title, .md-typeset summary {
+    font-weight: normal;
 }
diff --git a/docs/error-global.md b/docs/error-global.md
@@ -1,23 +1,30 @@
-Net可以通过实现`NetErrorHandler`接口来监听全局错误处理, 当你通过`setErrorHandler`后Net就不会再执行默认的错误处理了
+可实现`NetErrorHandler`接口来监听全局错误处理
 
-```kotlin
-NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
-
-    setErrorHandler(object : NetErrorHandler() {
+=== "创建"
+    ```kotlin
+    class NetworkingErrorHandler : NetErrorHandler {
         override fun onError(e: Throwable) {
-            super.onError(e)
-        }
-
-        override fun onStateError(e: Throwable, view: View) {
-            super.onStateError(e, view)
+        // .... 其他错误
+            if (e is ResponseException && e.tag == 401) { // 判断异常为token失效
+               // 打开登录界面或者弹登录失效对话框
+            }
         }
-    })
-}
-```
+    }
+    ```
+=== "配置"
+    ```kotlin
+    NetConfig.initialize(Api.HOST, this) {
+        setErrorHandler(NetworkingErrorHandler))
+    }
+    ```
 
-|场景|处理函数|处理方式|
+|NetErrorHandler|使用场景|触发位置|
 |-|-|-|
-|普通网络请求/自动加载框|`onError`| 默认吐司错误信息 |
-|使用自动处理缺省页的作用域|`onStateError`| 仅部分错误信息会吐司, 因为缺省页不需要所有的错误信息都吐司(toast)提示, 因为错误页可能已经展示错误信息, 所以这里两者处理的函数区分. |
+|`onError`| 吐司错误信息 | `scopeNetLife/scopeDialog` |
+|`onStateError` | 部分错误直接显示在缺省页 |`PageRefreshLayout.scope/StateLayout.scope`|
+
+
+!!! warning "以下情况全局错误处理无效"
 
-> `scope/scopeLife`不会触发任何全局错误NetErrorHandler, 请使用单例错误处理方式`catch`, 因为其用于处理异步任务,不应当用于网络请求
+    1. 异步任务作用域(`scope/scopeLife`)发生的错误
+    2. 使用[单例错误处理](error-single.md)处理的错误
diff --git a/docs/error-throws.md b/docs/error-throws.md
@@ -29,55 +29,51 @@
 
 > 转换器中发生的所有异常除非是NetException的子类否则都将被ConvertException包裹(即捕获的是ConvertException, cause才为实际抛出异常).
 
-## 使用异常属性
+## 异常传递字段
 
-Net自带的一些异常都会有一个类型为Any的属性`tag`. 可以用来传递任何对象来用于判断错误类型. 比如`ResponseException`我常用于作为请求服务器成功但是服务器业务错误. 然后tag为业务错误码
+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传递
+=== "转换器抛出异常"
+
+    ```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)
                 }
-                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失效
-           // 打开登录界面或者弹登录失效对话框
+    ```
+
+=== "全局错误处理异常"
+
+    ```kotlin
+    class NetworkingErrorHandler : NetErrorHandler {
+        override fun onError(e: Throwable) {
+        // .... 其他错误
+            if (e is ResponseException && e.tag == 401) { // 判断异常为token失效
+               // 打开登录界面或者弹登录失效对话框
+            }
         }
     }
-}
-
-// 初始化Net的时候设置错误处理器
-NetConfig.initialize("host", this) {
-    setErrorHandler(MyErrorHandler()
-}
-```
+    ```
diff --git a/docs/error-tip.md b/docs/error-tip.md
@@ -1,31 +1,63 @@
-网络请求发生错误一定要提示给用户, 提示语一般情况下是可读的语义句
+!!! question "网络错误提示"
+    网络请求发生错误一定要提示给用户, 并且是可读语义句
 
-如果你是想修改默认吐司的错误文本信息或者做国际化语言可以参考以下方法
+如需修改默认吐司错误文本或者国际化语言可以参考以下方法
 
 ## 创建多语言
 
-默认错误处理的文本被定义在`strings.xml`中, 我们可以在项目中创建多语言values来创建同名string实现国际化. 比如英语是`values-en`下创建文件`strings.xml`
-
-```xml
-<!--网络请求异常-->
-<string name="net_connect_error">连接网络失败</string>
-<string name="net_networking_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="request_failure">请求失败</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>
-```
+错误提示文本被定义在框架中`strings.xml`, 在自己应用项目中创建同名`name`可复写Net定义的文本
+
+或者中创建多语言values实现国际化, 例如英语是`values-en`下创建文件`strings.xml`
+
+??? example "默认文本"
+    ```xml
+        <!--网络请求异常-->
+        <string name="net_connect_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="request_failure">请求失败</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>
+
+        <!--对话框-->
+        <string name="net_dialog_msg">加载中</string>
+    ```
 
 ## 创建NetErrorHandler
-这实际上就是[自定义全局错误处理](error-global.md), 不过你可以复制默认的实现仅修改下文本信息即可
+使用[自定义全局错误处理](error-global.md)完全复写, 可以不提示错误或者上传错误日志
+
+??? example "默认全局错误处理"
+    ```kotlin
+    fun onError(e: Throwable) {
+        val message = when (e) {
+            is UnknownHostException -> NetConfig.app.getString(R.string.net_host_error)
+            is URLParseException -> NetConfig.app.getString(R.string.net_url_error)
+            is NetConnectException -> NetConfig.app.getString(R.string.net_connect_error)
+            is NetSocketTimeoutException -> NetConfig.app.getString(
+                R.string.net_connect_timeout_error,
+                e.message
+            )
+            is DownloadFileException -> NetConfig.app.getString(R.string.net_download_error)
+            is ConvertException -> NetConfig.app.getString(R.string.net_parse_error)
+            is RequestParamsException -> NetConfig.app.getString(R.string.net_request_error)
+            is ServerResponseException -> NetConfig.app.getString(R.string.net_server_error)
+            is NullPointerException -> NetConfig.app.getString(R.string.net_null_error)
+            is NoCacheException -> NetConfig.app.getString(R.string.net_no_cache_error)
+            is ResponseException -> e.message
+            is HttpFailureException -> NetConfig.app.getString(R.string.request_failure)
+            is NetException -> NetConfig.app.getString(R.string.net_error)
+            else -> NetConfig.app.getString(R.string.net_other_error)
+        }
 
-<img src="https://s2.loli.net/2022/03/01/mQNuoUwtxfK8P6E.png" width="500"/>
+        Net.debug(e)
+        TipUtils.toast(message)
+    }
+    ```
diff --git a/docs/error.md b/docs/error.md
@@ -1,29 +1,21 @@
-Net具备完善的错误处理机制, 能捕获大部分网络请求或者异步任务导致的崩溃, 减少App崩溃和收集详细的错误信息
-
-<br>
-以下场景的抛出的异常会被Net捕获到(不会导致崩溃)
-
-1. 作用域内部 (scope**等函数大括号`{}`内部)
-1. 拦截器中 (Interceptor/RequestInterceptor)
-1. 转换器中 (NetConverter)
+Net有完善的错误处理机制, 具备捕获异常/取消请求/错误提示/追踪链路
 
+!!! success "收集网络日志"
+    在Net作用域内发生的异常都会被全局错误处理捕获, 可以将其筛选上传日志
 
 <br>
+以下位置抛出异常会被捕获
+
+| 函数 | 描述 |
+|-|-|
+| 作用域 | `scopeXX`代码块中 |
+| 拦截器 | `Interceptor/RequestInterceptor` |
+| 转换器 | `NetConverter`  |
 
 如果捕获到错误默认会执行以下操作
 
--  `Logcat`中会输出详细的异常堆栈信息, 如果想要输出更详细内容请阅读[自定义异常](error-throws.md)
--  `Toast`吐司错误异常信息, 如果想要自定义或者国际化错误文本请阅读[自定义错误提示](error-tip.md)
+-  `Logcat`输出异常堆栈信息, 可[自定义异常抛出](error-throws.md)
+-  `Toast`显示错误文本, 可[自定义错误提示](error-tip.md)
 
 <br>
-要改变以上的默认错误处理请阅读阅读[全局错误处理](error-global.md), 默认全局错误处理器实现源码: [NetErrorHandler](https://github.com/liangjingkanji/Net/blob/97c31dddde7ced5aa75411d2581c858ca494669e/net/src/main/java/com/drake/net/interfaces/NetErrorHandler.kt#L18) <br>
-
-
-> 建议在全局错误处理器中将捕获到的Exception(除无网络异常意外)上报到崩溃统计平台
-
-
-
-
-
-
-
+自定义请阅读[全局错误处理](error-global.md)
diff --git a/docs/index.md b/docs/index.md
@@ -5,9 +5,9 @@
 <br>
 
 
-!!! tip "前言"
+!!! note "前言"
 
-    - Net没有的功能可以搜索`"OkHttp如何XX"`来实现
+    - Net没有的功能可以搜索`"OkHttp如何XX"`来扩展实现
     - 推荐阅读示例/源码
     - 如果觉得文档看不懂那肯定是作者问题, 请反馈给作者或者自我修订
 

diff --git a/docs/log-notice.md b/docs/log-notice.md
@@ -2,7 +2,7 @@
 
 这里介绍一个第三方日志拦截器[chucker](https://github.com/ChuckerTeam/chucker), 他会在Net发起请求后自动在设备通知栏显示网络请求记录, 点击通知可以跳转详情
 
-<img src="https://github.com/ChuckerTeam/chucker/raw/develop/assets/chucker-http.gif" width="250"/>
+<img src="https://github.com/ChuckerTeam/chucker/raw/main/assets/chucker-http.gif" width="250"/>
 
 添加依赖