doc: 开发文档

liangjingkanji · Aug 8, 2023 · d071efc · d071efc
1 parent 83d44a1
commit d071efc
Show file tree

Hide file tree

Showing 9 changed files with 37 additions and 44 deletions.
diff --git a/docs/cache.md b/docs/cache.md
@@ -1,15 +1,15 @@
-**网络请求中缓存至关重要, 而Net是最好的**
+### 缓存优势
 
 1. 页面秒开
 2. 减少服务器压力
 3. 无网络可用
 
 ### Net缓存特点
 
-1. 缓存任何请求方式, POST/GET/PUT/HEAD...
-2. 缓存任何数据类型, File/图片/JSON/ProtoBuf/...
-3. 限制最大缓存体积, 缓存遵守磁盘LRU缓存算法, 当缓存达到限制时, 将会删除最近最少使用的缓存
-4. 高性能DiskLruCache来实现统一缓存
+1. 缓存任何请求方式
+2. 缓存任何数据, File/图片/JSON/ProtoBuf等
+3. 限制最大缓存空间
+4. 使用`DiskLruCache`实现, 删除最近最少使用
 
 ## 配置缓存
 
@@ -87,7 +87,7 @@ scopeNetLife {
 ## 缓存有效期
 
 1. 仅`强制缓存模式`有效, 标准Http缓存协议遵守协议本身的有效期
-1. 缓存有效期过期只是让缓存无效, 并不会被删除(即无法读取), 缓存删除遵守Lru(最近最少使用)原则在所有缓存体积达到配置值时删除(即使缓存有效期未到)
+1. 缓存有效期过期只是让缓存无效, 不会立即删除  <br>根据(最近最少使用)原则在缓存空间达到配置值时删除(即使缓存有效期未到)
 
 ```kotlin
 scopeNetLife {

diff --git a/docs/cancel.md b/docs/cancel.md
@@ -1,4 +1,4 @@
-Net跟随作用域生命周期自动取消网络请求, 绝大部分场景无需手动处理, 但是例如取消下载文件等可能需要手动取消
+部分场景需要手动取消请求, 例如取消下载
 
 ```kotlin
 downloadScope = scopeNetLife {
@@ -8,8 +8,6 @@ downloadScope = scopeNetLife {
 
 downloadScope.cancel() // 取消下载
 ```
-完整示例: [源码](https://github.com/liangjingkanji/Net/blob/master/sample/src/main/java/com/drake/net/sample/ui/fragment/DownloadFileFragment.kt)
-
 
 ## 任意位置取消
 发起请求时指定`Id`

diff --git a/docs/coroutine-request.md b/docs/coroutine-request.md
@@ -1,9 +1,6 @@
-Net在2.0开始引入协程并发请求, 虽然很多网络框架支持协程, 但是唯有Net考虑到协程生命周期
+Net的协程作用域会自动处理协程生命周期
 
-并且不仅仅网络请求, 其也支持创建任何异步任务
-
-<br>
-在上章节已经介绍如何发起并发网络请求, 这里再演示同时(并发)网络请求`一万次`并且一次性全部取消
+在上章节已经介绍如何发起并发网络请求, 这里演示同时(并发)请求`一万次`, 然后取消全部
 
 ```kotlin
 val job = scopeNetLife {
@@ -27,7 +24,7 @@ thread {
 
 <br>
 
-Net主要使用的协程请求, 但也支持其他方式发起请求
+Net主要使用协程请求, 但也支持其他方式发起请求
 
 - [同步请求](sync-request.md)
 - [回调请求](callback.md)

diff --git a/docs/debounce.md b/docs/debounce.md
@@ -1,18 +1,16 @@
 !!! question "节流"
     在一定时间间隔内，只执行最后一次请求, 忽略其他多余的请求
 
-现代应用的搜索输入框一般情况下都是输入完关键词后自动开始搜索
+搜索输入框一般都是输入完关键词后自动开始搜索
 
-这个过程涉及到以下
+这个过程涉及到
 
 1. 每次变化都搜索会导致服务器压力, 应在停止输入满足一定时间后自动搜索
 2. 当产生新的搜索请求后应取消旧请求, 以防止旧数据覆盖新数据
 3. 当输入内容没有变化(例复制粘贴重复内容到搜索框)不会发起搜索请求
 
 <br>
 
-截图预览
-
 <img src="https://i.loli.net/2021/08/14/DAhfwxa1NK4gbpq.gif" width="250"/>
 
 <br>

diff --git a/docs/https.md b/docs/https.md
@@ -1,4 +1,4 @@
-Net可快速配置Https证书, 且允许使用OkHttp任何Api
+Net可快速配置Https证书, 或者使用OkHttp的方式
 
 ## 使用CA证书
 

diff --git a/docs/okhttp-client.md b/docs/okhttp-client.md
@@ -17,7 +17,7 @@ NetConfig.initialize(Api.HOST, this) {
 
 ## 单例
 
-每个请求可能存在独立的OkHttpClient配置, 我们可以单例配置客户端选项
+可以单独指定当前请求客户端
 
 === "修改全局客户端"
     ```kotlin
@@ -40,4 +40,4 @@ NetConfig.initialize(Api.HOST, this) {
         }.await()
     }
     ```
-    创建新的OkHttpClient, 一般不推荐, 因为新OkHttpClient会重新创建线程池/连接池等造成内存消耗
+    创建新的OkHttpClient, 一般不使用, 因为新OkHttpClient会重新创建线程池/连接池等造成内存消耗
diff --git a/docs/request.md b/docs/request.md
@@ -2,8 +2,8 @@
 !!! question "请求参数"
     根据请求方式不同请求参数分为两类
 
-    UrlRequest: GET, HEAD, OPTIONS, TRACE // Query(请求参数位于Url中) <br> 
-    BodyRequest: POST, DELETE, PUT, PATCH // Body(请求体为流)
+    `UrlRequest`: GET, HEAD, OPTIONS, TRACE // Query(请求参数位于Url中) <br>
+    `BodyRequest`: POST, DELETE, PUT, PATCH // Body(请求体为流)
 
 使用示例
 
@@ -23,22 +23,22 @@ scopeNetLife {
 |`setQuery/addQuery`|Url中的Query参数, 如果当为Url请求则该函数等效`param`|
 |`setHeader/addHeader`|设置/添加请求头|
 
-## JSON请求
+## JSON
 
-这里仅演示三种参数类型上传JSON, 详细请查看方法重载
+三种参数类型上传JSON示例, 更多请阅读方法注释
 
-=== "Pair(推荐)"
+=== "键值对"
     ```kotlin
     val name = "金城武"
     val age = 29
     val measurements = listOf(100, 100, 100)
 
-        scopeNetLife {
-            tvFragment.text = Post<String>("api") {
-                // 只支持基础类型的值, 如果值为对象或者包含对象的集合/数组会导致其值为null
-                json("name" to name, "age" to age, "measurements" to measurements)
-            }.await()
-        }
+    scopeNetLife {
+        tvFragment.text = Post<String>("api") {
+            // 只支持基础类型的值, 如果值为对象或者包含对象的集合/数组会导致其值为null
+            json("name" to name, "age" to age, "measurements" to measurements)
+        }.await()
+    }
     ```
 
 === "JSONObject"
@@ -71,21 +71,21 @@ scopeNetLife {
     }
     ```
 
-个别项目JSON中存在固定值, 开发者不想每次都写一遍:
+如果JSON需要全局参数
 
-1. 实现RequestBody默认添加参数
+1. 自定义`RequestBody`添加全局参数
 2. 使用请求拦截器来添加全局参数 [RequestInterceptor](/interceptor/#_1)
 
 ## 自定义扩展函数
 
-前面提到`json()`不能传对象, 因为内部使用`org.json.JSONObject`不支持映射对象字段
+由于`json()`不能传对象, 因为使用的`org.json.JSONObject`其不支持映射对象字段
 
-那可以自己创建扩展函数来使用支持解析对象的序列化框架, 如下
+但可创建扩展函数来使用射对象序列化框架来解析, 如下
 
 === "Gson"
     ```kotlin
     fun BodyRequest.gson(vararg body: Pair<String, Any?>) {
-    this.body = Gson().toJson(body.toMap()).toRequestBody(MediaConst.JSON)
+        this.body = Gson().toJson(body.toMap()).toRequestBody(MediaConst.JSON)
     }
     ```
 === "FastJson"
@@ -108,12 +108,12 @@ scopeNetLife {
 
 ## 全局请求参数
 
-使用`RequestInterceptor`请求拦截器添加全局参数/请求头, 如果不满足需求可以使用更复杂的`Interceptor`
+使用`RequestInterceptor`请求拦截器添加全局参数/请求头, 更复杂请实现`Interceptor`
 
 ```kotlin
 class GlobalHeaderInterceptor : RequestInterceptor {
 
-    /** 本方法每次请求发起都会调用, 这里添加的参数可以是动态参数 */
+    // 每次请求都会回调, 可以是动态参数
     override fun interceptor(request: BaseRequest) {
         request.setHeader("client", "Android")
         request.setHeader("token", UserConfig.token)

diff --git a/docs/tag.md b/docs/tag.md
@@ -1,9 +1,9 @@
-Net支持两种方式携带数据, 贯穿整个请求流程(请求 -> 拦截器 -> 转换器)
+Net支持两种方式携带数据, 贯穿整个请求流程(请求/拦截器/转换器)
 
 - tag: `HashMap<Class<*>, Any?>` 标签
 - extra: `HashMap<String, Any?>` 额外数据
 
-区别为key是`Class`还是`String`, 自由选择
+两者区别为存储时key是`Class`还是`String`, 自由选择
 
 ## 标签使用
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -104,7 +104,7 @@ nav:
   - Https证书: https.md
   - Cookie: cookie.md
   - 缓存: cache.md
-  - 标签/额外数据: tag.md
+  - 标签/额外: tag.md
   - 上传文件: upload-file.md
   - 下载文件: download-file.md
   - 进度监听: progress.md
@@ -113,7 +113,7 @@ nav:
   - 搜索节流: debounce.md
   - 最快请求结果: fastest.md
   - 日志插件: log-recorder.md
-  - 通知栏日志: log-notice.md
+  - 日志通知: log-notice.md
   - 限时/定时请求: timing.md
   - Callback: callback.md
   - 轮询器/倒计时: interval.md