docs: 更新文档

liangjingkanji · Aug 16, 2023 · 99f56e3 · 99f56e3
1 parent a78d461
commit 99f56e3
Show file tree

Hide file tree

Showing 52 changed files with 200 additions and 200 deletions.
diff --git a/docs/auto-dialog.md b/docs/auto-dialog.md
@@ -5,8 +5,8 @@ Net支持发起请求开始时显示加载框, 请求结束时隐藏加载框(
 
 ```kotlin hl_lines="1"
 scopeDialog {
-    tvFragment.text = Post<String>("dialog") {
-        param("u_name", "drake") // 请求参数
+    tv.text = Post<String>(Api.PATH) {
+        param("username", "用户名") // 请求参数
         param("pwd", "123456")
     }.await()
 }
@@ -27,8 +27,8 @@ scopeDialog {
 val dialog = BubbleDialog(requireActivity(), "加载中")
 
 scopeDialog(dialog) {
-    binding.tvFragment.text = Post<String>("dialog") {
-        param("u_name", "drake")
+    tv.text = Post<String>(Api.PATH) {
+        param("username", "用户名")
         param("pwd", "123456")
     }.await()
 }

diff --git a/docs/auto-pull.md b/docs/auto-pull.md
@@ -8,7 +8,7 @@
 ```kotlin
 page.onRefresh {
     scope {
-        val data = Get<ListModel>("list") {
+        val data = Get<Game>(Api.PATH) {
             param("page", index)
         }.await().data
         addData(data.list) {

diff --git a/docs/auto-refresh.md b/docs/auto-refresh.md
@@ -47,7 +47,7 @@ rv_push.linear().setup {
 page.onRefresh {
     scope {
         // 请求到数据设置到RecyclerView
-        rv_push.models = Get<ListModel>("list").await().data.list
+        rv_push.models = Get<Game>(Api.PATH).await().data.list
     }
 }.autoRefresh()
 ```

diff --git a/docs/auto-state.md b/docs/auto-state.md
@@ -37,7 +37,7 @@ StateConfig.apply {
     tools:context=".ui.fragment.StateLayoutFragment">
 
     <TextView
-        android:id="@+id/tvFragment"
+        android:id="@+id/tv"
         android:padding="32dp"
         android:textStyle="bold"
         android:layout_width="match_parent"
@@ -56,7 +56,7 @@ StateConfig.apply {
 ```kotlin
 state.onRefresh {
     scope {
-        tvFragment.text = Get<String>("api").await()
+        tv.text = Get<String>(Api.PATH).await()
     }
 }.showLoading()
 ```

diff --git a/docs/cache.md b/docs/cache.md
@@ -34,28 +34,28 @@ OkHttp默认的Http缓存协议控制, 要求以下条件
 - 响应头控制缓存: [Cache-Control](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Cache-Control)
 
 <br>
-通过`setCacheControl`可以控制Http缓存协议(原理是添加请求头)
+通过`setCacheControl`可以控制Http缓存协议, 原理是修改请求头
 
 ```kotlin
 scopeNetLife {
-    Post<String>("api") {
+    Post<String>(Api.PATH) {
         setCacheControl(CacheControl.FORCE_CACHE) // 强制使用缓存
         // setCacheControl(CacheControl.FORCE_NETWORK) // 强制使用网络
-        // setCacheControl(CacheControl.Builder().noStore().noCache().build()) // 完全禁止读取/写入缓存
+        // setCacheControl(CacheControl.Builder().noStore().noCache().build()) // 禁止缓存
     }.await()
 }
 ```
 
-如果无法实现Http标准缓存协议, 或要缓存Get以外的请求方法, 可以使用`强制缓存模式`来由客户端控制缓存
+如果无法实现Http标准缓存协议, 或要缓存Get以外的请求方法, 可以使用`强制缓存模式`
 
 ## 强制缓存模式
 
-无论请求是否存在Http标准缓存协议, 当你设置强制缓存模式时其会无视Http标准缓存协议
+无论当前请求是否存在Http标准缓存协议, 当设置强制缓存模式时会无视Http缓存协议
 
 ```kotlin
 scopeNetLife {
-    binding.tvFragment.text =
-        Post<String>("api") {
+    tv.text =
+        Post<String>(Api.PATH) {
             setCacheMode(CacheMode.REQUEST_THEN_READ) // 请求网络失败会读取缓存, 请断网测试
         }.await()
 }
@@ -76,8 +76,8 @@ scopeNetLife {
 
 ```kotlin
 scopeNetLife {
-    binding.tvFragment.text =
-        Post<String>("api") {
+    tv.text =
+        Post<String>(Api.PATH) {
             setCacheMode(CacheMode.REQUEST_THEN_READ) // 请求网络失败会读取缓存, 请断网测试
             setCacheKey("请求热门信息" + params) // 具体值都行
         }.await()
@@ -91,8 +91,8 @@ scopeNetLife {
 
 ```kotlin
 scopeNetLife {
-    binding.tvFragment.text =
-        Post<String>("api") {
+    tv.text =
+        Post<String>(Api.PATH) {
             setCacheMode(CacheMode.REQUEST_THEN_READ) // 请求网络失败会读取缓存, 请断网测试
             setCacheValidTime(1, TimeUnit.DAYS) // 缓存仅一天内有效
         }.await()
@@ -106,21 +106,21 @@ scopeNetLife {
 ```kotlin
 scopeNetLife {
     // 然后执行这里(网络请求)
-    binding.tvFragment.text = Get<String>("api") {
+    tv.text = Get<String>(Api.PATH) {
         setCacheMode(CacheMode.WRITE)
     }.await()
     Log.d("日志", "网络请求")
-}.preview(true) {
+}.preview {
     // 先执行这里(仅读缓存), 任何异常都视为读取缓存失败
-    binding.tvFragment.text = Get<String>("api") {
+    tv.text = Get<String>(Api.PATH) {
         setCacheMode(CacheMode.READ)
     }.await()
     Log.d("日志", "读取缓存")
 }
 ```
 
-!!! question "这和加载两次有什么区别?"
+!!! question "预览和加载两次有什么区别?"
     区别是`preview`可以控制以下行为
 
-    1. `breakError` 读取缓存成功后不再处理错误信息, 默认false
-    2. `breakLoading` 读取缓存成功后结束加载动画, 默认true
+    1. `breakError` 读取缓存成功后不再处理请求的错误, 默认false
+    2. `breakLoading` 读取缓存成功后立刻结束加载动画, 默认true
diff --git a/docs/callback.md b/docs/callback.md
@@ -14,7 +14,7 @@ Net.post("api").enqueue(object : Callback {
         val body = response.body?.string() ?: "无数据"
         runMain {
             // 此处为主线程
-            binding.tvFragment.text = body
+            tv.text = body
         }
     }
 })

diff --git a/docs/cancel.md b/docs/cancel.md
@@ -1,9 +1,9 @@
-部分场景需要手动取消请求, 例如取消下载
+部分场景开发者想手动取消请求
 
 ```kotlin
 downloadScope = scopeNetLife {
     // 下载文件
-    val file = Get<File>("download").await()
+    val file = Get<File>(Api.DOWNLOAD).await()
 }
 
 downloadScope.cancel() // 取消下载
@@ -14,7 +14,7 @@ downloadScope.cancel() // 取消下载
 
 ```kotlin
 scopeNetLife {
-    tvFragment.text = Get<String>("api"){
+    tv.text = Get<String>(Api.DOWNLOAD){
         setId("请求用户信息")
     }.await()
 }

diff --git a/docs/config.md b/docs/config.md
@@ -59,31 +59,32 @@ NetConfig.initialize(Api.HOST, this) {
 
 ## 多域名
 
-概念源于`Retrofit`(称为BaseUrl), 因为Retrofit无法二次修改请求Host, 但Net支持随时修改
-
-以下介绍三种修改方式
+Net可随时变更请求域名, 以下介绍三种方式
 
 === "修改Host"
     ```kotlin
-    NetConfig.host = Api.HOST_2
+    NetConfig.host = Api.HOST_VIDEO
     ```
 
 === "指定全路径"
-    指定Path(例如`/api/index`)会自动和`NetConfig.host`拼接组成Url, 但指定以`http/https`开头的全路径则直接作为请求Url
+    建议使用单例类管理请求Url
     ```kotlin
+    object Api {
+        const val HOST_IMG = "http://127.0.0.1"
+        const val BANNER = "$HOST_IMG/banner"
+    }
     scopeNetLife {
-        val data = Get<String>("https://github.com/path").await()
+        val data = Get<String>(Api.BANNER).await()
     }
     ```
 
 === "使用拦截器"
-    请求时指定`tag`, 然后拦截器中根据tag判断修改host, 拦截器能修改所有请求/响应信息
-
+    请求指定`tag`, 拦截器中根据tag修改Url, 建议tag为包含域名的枚举或单例
     ```kotlin
     scopeNetLife {
-        val data = Get<String>("/api/index", "User").await() // User即为tag
+        val data = Get<String>(Api.PATH, GAME).await() // User即为tag
     }
-    // 拦截器修改请求URL不做介绍
+    // 拦截器如何修改请搜索
     ```
 
 ## 网络安全配置

diff --git a/docs/converter-customize.md b/docs/converter-customize.md
@@ -7,7 +7,7 @@ Net自定义转换器可支持任何数据类型, 甚至`Bitmap`
 
 ```kotlin
 scopeNetLife {
-    val userList = Get<List<UserModel>>("list") {
+    val userList = Get<List<UserModel>>(Api.PATH) {
         converter = GsonConverter()
     }.await()
 }
@@ -26,7 +26,7 @@ Net由于低耦合原则不自带任何序列化框架
 === "单例"
     ```kotlin hl_lines="3"
     scopeNetLife {
-       tvFragment.text = Get<String>("api"){
+       tv.text = Get<String>(Api.PATH){
             converter = SerializationConverter()
        }.await()
     }

diff --git a/docs/converter-struct.md b/docs/converter-struct.md
@@ -32,7 +32,7 @@
 === "网络请求"
     ```kotlin
     scopeNetLife {
-        val data = Get<UserModel>("api").await().data
+        val data = Get<UserModel>(Api.USER).await().data
     }
     ```
 
@@ -81,7 +81,7 @@ class GsonConvert : JSONConvert(code = "code", message = "msg", success = "200")
 
 ```kotlin
 scopeNetLife {
-    val data = Get<UserModel>("api").await()
+    val data = Get<UserModel>(Api.USER).await()
 }
 ```
 

diff --git a/docs/converter.md b/docs/converter.md
@@ -1,6 +1,6 @@
 Net支持请求返回的数据类型取决于你的转换器实现
 
-# Get<任何对象>("path").await()
+# Get<任何对象>(Api.PATH).await()
 
 默认转换器支持返回以下数据类型
 
@@ -16,7 +16,7 @@ Net支持请求返回的数据类型取决于你的转换器实现
 
 ```kotlin
 scopeNetLife {
-    Get<Response>("api").await().headers("响应头名称") // 返回响应头
+    Get<Response>(Api.PATH).await().headers("响应头名称") // 返回响应头
 }
 ```
 

diff --git a/docs/cookie.md b/docs/cookie.md
@@ -1,4 +1,4 @@
-使用OkHttp的`CookieJar`, Net提供持久化Cookie`PersistentCookieJar`
+可以实现OkHttp的`CookieJar`, 且提供持久化的[PersistentCookieJar](https://github.com/liangjingkanji/Net/blob/2abf07e1d003ef44574278fd2010f3375225d964/net/src/main/java/com/drake/net/cookie/PersistentCookieJar.kt)
 
 ```kotlin
 NetConfig.initialize(Api.HOST, this) {

diff --git a/docs/coroutine-request.md b/docs/coroutine-request.md
@@ -7,7 +7,7 @@ val job = scopeNetLife {
     repeat(10000) {
         // 这里将返回的数据显示在TextView上
         launch {
-            tvFragment.text = Get<String>("https://github.com/liangjingkanji/Net/").await()
+            tv.text = Get<String>(Api.PATH).await()
         }
     }
 }

diff --git a/docs/debounce.md b/docs/debounce.md
@@ -22,13 +22,15 @@ var scope: CoroutineScope? = null
 binding.etInput.debounce().distinctUntilChanged().launchIn(this) {
     scope?.cancel() // 发起新的请求前取消旧的请求, 避免旧数据覆盖新数据
     scope = scopeNetLife { // 保存旧的请求到一个变量中
-        binding.tvFragment.text = "请求中"
-        binding.tvFragment.text = Get<String>(Api.TIME).await()
+        tv.text = "请求中"
+        tv.text = Get<String>(Api.TIME).await()
     }
 }
 ```
 
 指定参数设置节流阀超时时间
 ```kotlin
 fun EditText.debounce(timeoutMillis: Long = 800)
-```
+```
+<br>
+1. [示例-自动搜索分页列表](https://github.com/liangjingkanji/Net/blob/a78d46118666a3509d3fcc79c1d28ad81e2d5a57/sample/src/main/java/com/drake/net/sample/ui/fragment/EditDebounceFragment.kt)
diff --git a/docs/download-file.md b/docs/download-file.md
@@ -2,7 +2,7 @@
 
 ```kotlin
 scopeNetLife {
-    val file = Get<File>("download").await()
+    val file = Get<File>(Api.DOWNLOAD).await()
 }
 ```
 
@@ -13,7 +13,7 @@ scopeNetLife {
 ```kotlin
 scopeNetLife {
     val file =
-        Get<File>("https://download.sublimetext.com/Sublime%20Text%20Build%203211.dmg") {
+        Get<File>("https://github.com/liangjingkanji/Net/releases/latest/download/net-sample.apk") {
             setDownloadFileName("net.apk")
             setDownloadDir(requireContext().filesDir)
             setDownloadMd5Verify()

diff --git a/docs/error-single.md b/docs/error-single.md
@@ -7,28 +7,28 @@
 例如
 ```kotlin
 scopeNetLife {
-    Get<String>("api").await() // 失败
-    Get<String>("api2").await() // 上面失败, 此处也不会执行
+    Get<String>("path").await() // 失败
+    Get<String>("path2").await() // 上面失败, 此处也不会执行
 }
 ```
 
 捕获第一个协程避免终止后续执行
 ```kotlin
 scopeNetLife {
     try {
-        Get<String>("api").await() // 失败
+        Get<String>("path").await() // 失败
     } catch(e:Exception) {
     }
-    Get<String>("api2").await() // 上面失败, 此处继续执行
+    Get<String>("path2").await() // 上面失败, 此处继续执行
 }
 ```
 当然如果创建不同的作用域分别请求那是互不影响的
 ```kotlin
 scopeNetLife {
-    Get<String>("api").await() // 失败
+    Get<String>("path").await() // 失败
 }
 scopeNetLife {
-    Get<String>("api2").await() // 上面失败, 此处完全不受影响
+    Get<String>("path2").await() // 上面失败, 此处完全不受影响
 }
 ```
 
@@ -38,7 +38,7 @@ scopeNetLife {
 
 ```kotlin
 scope {
-    val data = Get<String>("http://www.thisiserror.com/").await()
+    val data = Get<String>("http://www.error.com/").await()
 }.catch {
     // 协程内发生错误回调, it为异常对象
 }.finally {