docs: 使用文档

liangjingkanji · Aug 5, 2023 · b749795 · b749795
1 parent 99bf780
commit b749795
Show file tree

Hide file tree

Showing 4 changed files with 97 additions and 109 deletions.
diff --git a/docs/cancel.md b/docs/cancel.md
@@ -1,7 +1,4 @@
-Net虽然支持自动跟随生命周期取消网络请求, 绝大部分场景也足够. 但是有时还是需要手动取消, 例如取消下载文件.
-<br>
-
-Net取消协程作用域自动取消内部网络请求, 也支持任意位置取消指定网络请求.
+Net跟随作用域生命周期自动取消网络请求, 绝大部分场景无需手动处理, 但是例如取消下载文件等可能需要手动取消
 
 ```kotlin
 downloadScope = scopeNetLife {
@@ -15,9 +12,8 @@ downloadScope.cancel() // 取消下载
 
 
 ## 任意位置取消
-发起请求的时候要求定义一个`Id`用于指定网络请求, 然后在需要的地方使用单例对象`Net.cancelId`取消请求.
+发起请求时指定`Id`
 
-创建请求
 ```kotlin
 scopeNetLife {
     tvFragment.text = Get<String>("api"){
@@ -26,15 +22,25 @@ scopeNetLife {
 }
 ```
 
-然后根据Id取消网络请求
-```kotlin
-Net.cancelId("请求用户信息")
-
-Net.cancelGroup("请求分组名称") // 设置分组
-```
-
-Group和Id在使用场景上有所区别, 预期上Group允许重复赋值给多个请求, Id仅允许赋值给一个请求, 但实际上都允许重复赋值 <br>
-在作用域中发起请求时会默认使用协程错误处理器作为Group: `setGroup(coroutineContext[CoroutineExceptionHandler])` <br>
-如果你覆盖Group会导致协程结束不会自动取消请求
-
-<br>
+=== "根据ID取消"
+    ``` kotlin
+    Net.cancelId("请求用户信息")
+    ```
+=== "根据Group取消"
+    ``` kotlin
+    Net.cancelGroup("请求分组名称")
+    ```
+
+## Group和Id区别
+
+| 函数 | 描述 |
+|-|-|
+| id | 请求唯一Id, 实际上重复也行, 但是取消请求时遍历到指定Id就会结束遍历 |
+| group | 允许多个请求使用相同group, 在取消请求时会遍历所有分组的请求 <br>  |
+
+!!! warning "作用域结束请求自动取消"
+    在`scopeXX()`作用域中发起请求时会默认使用当前协程错误处理器作为Group
+    ```kotlin
+    setGroup(coroutineContext[CoroutineExceptionHandler])
+    ```
+    在作用域结束时 会`cancelGroup`, 所以如果你手动指定分组会导致无法自动取消
diff --git a/docs/config.md b/docs/config.md
@@ -2,48 +2,33 @@
 
 ## 初始配置
 
-=== "普通初始化"
+两种方式初始配置, 大部分情况下不初始化也能直接使用
 
+=== "Net初始化"
     ```kotlin
-    class App : Application() {
-        override fun onCreate() {
-            super.onCreate()
-
-            // https://github.com/liangjingkanji/Net/  这是接口全局域名, 可以使用NetConfig.host进行单独的修改
-            NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
-                // 超时配置, 默认是10秒, 设置太长时间会导致用户等待过久
-                connectTimeout(30, TimeUnit.SECONDS)
-                readTimeout(30, TimeUnit.SECONDS)
-                writeTimeout(30, TimeUnit.SECONDS)
-                setDebug(BuildConfig.DEBUG)
-                setConverter(SerializationConverter())
-            }
-        }
+    NetConfig.initialize(Api.HOST, this) {
+        // 超时配置, 默认是10秒, 设置太长时间会导致用户等待过久
+        connectTimeout(30, TimeUnit.SECONDS)
+        readTimeout(30, TimeUnit.SECONDS)
+        writeTimeout(30, TimeUnit.SECONDS)
+        setDebug(BuildConfig.DEBUG)
+        setConverter(SerializationConverter())
     }
     ```
 
-=== "OkHttpClient.Builder"
-
+=== "OkHttp构造器初始化"
     ```kotlin
-    class App : Application() {
-        override fun onCreate() {
-            super.onCreate()
-            // https://github.com/liangjingkanji/Net/  这是接口全局域名, 可以使用NetConfig.host进行单独的修改
-            val okHttpClientBuilder = OkHttpClient.Builder()
-                .setDebug(BuildConfig.DEBUG)
-                .setConverter(SerializationConverter())
-                .addInterceptor(LogRecordInterceptor(BuildConfig.DEBUG))
-
-            NetConfig.initialize("https://github.com/liangjingkanji/Net/", this, okHttpClientBuilder)
-        }
-    }
+    val okHttpClientBuilder = OkHttpClient.Builder()
+        .setDebug(BuildConfig.DEBUG)
+        .setConverter(SerializationConverter())
+        .addInterceptor(LogRecordInterceptor(BuildConfig.DEBUG))
+    NetConfig.initialize(Api.HOST, this, okHttpClientBuilder)
     ```
 
-> 配置都是可选项, 不是不初始化就不能使用. 如果你是Xposed或者多进程项目中必须初始化传入上下文或者赋值 `NetConfig.app = this`
+!!! failure "指定上下文"
+    如果是多进程项目(例如Xposed)必须初始化, 因为多进程无法自动指定Context
 
-在initNet函数作用域中的this属于`OkHttpClient.Builder()`, 可以配置任何OkHttpClient.Builder的属性以外还支持以下Net独有配置
-
-| 函数 | 描述 |
+| 可配置选项 | 描述 |
 |-|-|
 | setDebug | 是否输出网络日志, 和`LogRecordInterceptor`互不影响 |
 | setSSLCertificate | 配置Https证书 |
@@ -53,61 +38,53 @@
 | setErrorHandler | [配置全局错误处理](error-global.md) |
 | setDialogFactory | [配置全局对话框](auto-dialog.md) |
 
+!!! success "修改配置"
+    NetConfig存储所有全局配置变量, 可以后续修改, 且大部分支持单例指定配置
+
 ## 重试次数
 
-默认情况下你设置超时时间即可, OkHttp内部也有重试机制.
+可以添加`RetryInterceptor`拦截器即可实现失败以后会重试指定次数
 
-但是个别开发者需求指定重试次数则可以添加`RetryInterceptor`拦截器即可实现失败以后会重试指定次数
+默认情况下你设置超时时间即可, OkHttp内部也有重试机制
 
 ```kotlin
 NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
     // ... 其他配置
     addInterceptor(RetryInterceptor(3)) // 如果全部失败会重试三次
 }
 ```
+!!! warning "长时间阻碍用户交互"
+     OkHttp内部也有重试机制, 如果你还添加重试拦截器可能导致请求时间过长, 长时间阻碍用户交互
 
 
-## 修改配置
-
-[NetConfig](api/-net/com.drake.net/-net-config/index.html)的字段即为全局配置, 可随时修改
-
-```kotlin
-NetConfig.converter = MyNewConverter() // 修改全局数据转换器
-NetConfig.okHttpClient // 修改全局默认客户端
-```
-
-更多请访问源码查看
-
-## BaseUrl
-
-这个概念来源于Retrofit, 因为Retrofit无法动态修改Host, 但是这个Net支持随时修改. 以下介绍三种修改方式
-
-1) 直接修改
-
-```kotlin
-NetConfig.host = "新的BaseUrl"
-```
+## 多域名
 
+概念源于`Retrofit`(称为BaseUrl), 因为Retrofit无法二次修改请求Host, 但Net支持随时修改
 
-2) 传入路径
-如传入参数为路径(例如`/api/index`)会自动和`host`拼接组成完成URL, 但如果传入的以`http/https`开头的全路径则会直接作为请求URL
+以下介绍三种修改方式
 
-```kotlin
-scopeNetLife {
-    val data = Get<String>("https://github.com/liangjingkanji/Net/").await()
-}
-```
+=== "修改Host"
+    ```kotlin
+    NetConfig.host = Api.HOST_2
+    ```
 
-3) 使用拦截器
+=== "指定全路径"
+    指定Path(例如`/api/index`)会自动和`NetConfig.host`拼接组成Url, 但指定以`http/https`开头的全路径则直接作为请求Url
+    ```kotlin
+    scopeNetLife {
+        val data = Get<String>("https://github.com/path").await()
+    }
+    ```
 
-或者通过指定`tag`, 然后拦截器(interceptor)中根据tag动态修改host, 因为拦截器能修改一切请求参数
+=== "使用拦截器"
+    请求时指定`tag`, 然后拦截器中根据tag判断修改host, 拦截器能修改所有请求/响应信息
 
-```kotlin
-scopeNetLife {
-    val data = Get<String>("/api/index", "User").await() // User即为tag
-}
-// 拦截器修改请求URL不做介绍
-```
+    ```kotlin
+    scopeNetLife {
+        val data = Get<String>("/api/index", "User").await() // User即为tag
+    }
+    // 拦截器修改请求URL不做介绍
+    ```
 
 ## 多域名
 

diff --git a/docs/index.md b/docs/index.md
@@ -23,29 +23,29 @@
 === "简单请求"
     ```kotlin
     scopeNetLife { 创建作用域
-    // 这个大括号内就属于作用域内部
-    val data = Get<String>("https://github.com/liangjingkanji/Net/").await() // 发起GET请求并返回`String`类型数据
+        // 这个大括号内就属于作用域内部
+        val data = Get<String>("https://github.com/liangjingkanji/Net/").await() // 发起GET请求并返回`String`类型数据
     }
     ```
 === "同步请求"
     ```kotlin
     scopeNetLife {
-    val userInfo = Get<String>("https://github.com/liangjingkanji/BRV/").await() // 立即请求
-    val config = Get<String>("https://github.com/liangjingkanji/Net/"){
-    param("userId", userInfo.id) // 使用上个请求的数据作为参数
-    }.await() // 请求B 将等待A请求完毕后发起GET请求并返回数据
+        val userInfo = Get<String>("https://github.com/liangjingkanji/BRV/").await() // 立即请求
+            val config = Get<String>("https://github.com/liangjingkanji/Net/"){
+            param("userId", userInfo.id) // 使用上个请求的数据作为参数
+        }.await() // 请求B 将等待A请求完毕后发起GET请求并返回数据
     }
-```
+    ```
 === "并发请求"
     ```kotlin
     scopeNetLife {
-    // 以下两个网络请求属于同时进行中
-    val getUserInfoAsync = Get<String>("https://github.com/liangjingkanji/Net/") // 立即请求
-    val getConfigAsync = Get<String>("https://github.com/liangjingkanji/BRV/") // 立即请求
-    
-            val userInfo = getUserInfoAsync.await() // 等待数据返回
-            val config = getConfigAsync.await()
-        }
+        // 以下两个网络请求属于同时进行中
+        val getUserInfoAsync = Get<String>("https://github.com/liangjingkanji/Net/") // 立即请求
+        val getConfigAsync = Get<String>("https://github.com/liangjingkanji/BRV/") // 立即请求
+
+        val userInfo = getUserInfoAsync.await() // 等待数据返回
+        val config = getConfigAsync.await()
+    }
     ```
 
 多个网络请求在同一个作用域内可以统一控制, 如果多个网络请求之间毫无关联, 可以创建多个作用域来请求

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -45,20 +45,25 @@ plugins:
         - en
         - zh
 markdown_extensions:
-  - attr_list
-  - def_list
-  - md_in_html
   - toc:
       permalink: true
   - pymdownx.tasklist:
       custom_checkbox: true
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - attr_list
+  - def_list
+  - md_in_html
   - admonition
   - pymdownx.highlight
   - pymdownx.details
-  - pymdownx.superfences
-  - pymdownx.inlinehilite
-  - pymdownx.tabbed:
-      alternate_style: true
   - pymdownx.caret
   - pymdownx.keys
   - pymdownx.mark