更新文档

README.md

@@ -19,7 +19,9 @@
 
 
 
-Android上不是最强网络任务库, 创新式的网络请求库(针对[Kalle](https://github.com/yanzhenjie/Kalle)网络请求框架进行扩展), 支持协程高并发网络请求 <br>
+Android上不是最强网络任务库, 创新式的网络请求库(基于Kalle/OkHttp), 支持协程高并发网络请求 <br>
+<br>
+我是目前Android上最简洁和功能最多的网络请求库, 也是扩展性最强的, 可以完美适应任何项目的后端要求, 有最详细的文档和最简练的Demo. 并且我还是一个异步任务库
 
 <br>
 
@@ -61,6 +63,7 @@ Net 2.x 版本为协程实现(开发者无需掌握协程也可以使用)
 - 自动处理加载对话框
 - 协程作用域支持错误和结束回调
 - 内置超强轮循器(计时器)
+- 解析JSON数组返回集合
 
 
 

docs/auto-refresh.md

@@ -11,7 +11,6 @@ Net属于低耦合框架, 自动下拉刷新需要依赖第三方组件: [BRV](h
     xmlns:app="http://schemas.android.com/apk/res-auto"
     android:id="@+id/page"
     android:layout_width="match_parent"
-    app:srlEnableLoadMore="false"
     android:layout_height="match_parent"
     tools:context=".ui.fragment.PushRefreshFragment">
 
@@ -31,7 +30,7 @@ rv_push.linear().setup {
 ```
 
 创建网络请求
-```kotlin
+```kotlin hl_lines="2"
 page.onRefresh {
     scope {
         // 请求到数据设置到RecyclerView
@@ -42,6 +41,11 @@ page.onRefresh {
 
 <br>
 
+!!! note
+    注意高亮处使用的是`scope`而不是其他作用域, 只能使用scope, 否则无法跟随PageRefreshLayout生命周期等功能
+
+<br>
+
 - 使用上和自动缺省页相似
 - BRV同样属于具备完善功能独立的RecyclerView框架
 - BRV的下拉刷新扩展自[SmartRefreshLayout_v2](https://github.com/scwang90/SmartRefreshLayout), 支持其全部功能且更多

docs/auto-state.md

@@ -35,6 +35,10 @@ state.onRefresh {
     }
 }.showLoading()
 ```
+<br>
+
+!!! note
+    注意高亮处使用的是`scope`而不是其他作用域, 只能使用scope, 否则无法跟随StateLayout生命周期(自动显示对应缺省页)等功能
 
 ## 生命周期
 

docs/config.md

@@ -6,8 +6,12 @@ class App : Application() {
 
         // http://182.92.97.186/  这是接口全局域名, 可以使用NetConfig.host读写
         initNet("http://182.92.97.186/") {
+
+            // 大括号内部都是可选项配置
+
             converter(JsonConvert()) // 转换器
             cacheEnabled() // 开启缓存
+            logEnabled = false // 关闭异常信息打印
         }
     }
 }

docs/convert.md

@@ -67,31 +67,27 @@ abstract class DefaultConvert(
     val message: String = "msg"
 ) : Converter {
 
-    override fun <S, F> convert(
+    override fun <S> convert(
         succeed: Type,
-        failed: Type,
         request: Request,
         response: Response,
-        result: Result<S, F>
-    ) {
-
+        cache: Boolean
+    ): S? {
         val body = response.body().string()
+        response.log = body  // 日志记录响应信息
         val code = response.code()
-
         when {
-            code in 200..299 -> {  // 服务器错误码为200-299时为成功
-                val jsonObject = JSONObject(body)
-                if (jsonObject.getString(this.code) == success) { // 对比后端返回的自定义错误码
-                    result.success =
-                        if (succeed === String::class.java) body as S else body.parseBody(succeed)
-                } else {
-                    // 如果不匹配后端自定义错误码则认为请求失败, [result.failure]写入错误异常, 会自动吐司出该信息
-                    result.failure =
-                        ResponseException(code, jsonObject.getString(message), request) as F
+            code in 200..299 -> { // 请求成功
+                val jsonObject = JSONObject(body) // 获取JSON中后端定义的错误码和错误信息
+                if (jsonObject.getString(this.code) == success) { // 对比后端自定义错误码
+                    return if (succeed === String::class.java) body as S else body.parseBody(succeed)
+                } else { // 错误码匹配失败, 开始写入错误异常
+                    throw ResponseException(code, jsonObject.getString(message), request, body)
                 }
             }
             code in 400..499 -> throw RequestParamsException(code, request) // 请求参数错误
             code >= 500 -> throw ServerResponseException(code, request) // 服务器异常错误
+            else -> throw ParseError(request)
         }
     }
 
@@ -106,4 +102,9 @@ DefaultConvert对于的核心逻辑
 1. 如果判断错误则创建一个包含错误信息的异常
 1. 如果都判断成功则开始解析数据
 
-根据需要你可以在这里加上常见的日志打印, 解密数据, 跳转登录界面等逻辑
+根据需要你可以在这里加上常见的日志打印, 解密数据, 跳转登录界面等逻辑
+
+<br>
+
+!!! note
+    转换器允许返回null, 如果你有任何认为不支持或者需要中断请求的操作可以在转换器中抛出任何异常, 推荐你的自定义异常继承`NetException`

docs/log-recorder.md

@@ -39,15 +39,14 @@ abstract class DefaultConvert(
     val message: String = "msg"
 ) : Converter {
 
-    override fun <S, F> convert(
+    override fun <S> convert(
         succeed: Type,
-        failed: Type,
         request: Request,
         response: Response,
-        result: Result<S, F>
-    ) {
+        cache: Boolean
+    ): S? {
         val body = response.body().string()
-        result.logResponseBody = body // 将字符串响应赋值给result.logResponseBody
+        response.log = body // 将字符串响应赋值给response.log
         // .... 其他操作
     }
 }
@@ -55,7 +54,7 @@ abstract class DefaultConvert(
 <br>
 
 !!! note
-    假设后端返回的加密数据, 可以为`result.logResponseBody`赋值解密后的字符串
+    假设后端返回的加密数据, 可以为`response.log`赋值解密后的字符串 <br>
 
 
 ### 请求参数加密
@@ -67,7 +66,7 @@ class NetInterceptor : Interceptor {
     override fun intercept(chain: Chain): Response {
         val request = chain.request()
 
-        request.logRequestBody("解密后的请求参数字符串")
+        request.log = "解密后的请求参数字符串"
 
         return chain.proceed(request)
     }
@@ -76,6 +75,13 @@ class NetInterceptor : Interceptor {
 
 <br>
 
+响应和请求都可以设置日志信息, 以在插件中查看
+
+| 函数 | 描述 |
+|-|-|
+| request.log | 请求的日志信息, 默认是params |
+| response.log | 响应的日志信息, 默认为空 |
+
 !!! note
     实际上Net的网络日志还是会被打印到LogCat, 然后通过插件捕捉显示. 如果不想LogCat的冗余日志影响查看其它日志, 可以通过AndroidStudio的功能折叠隐藏
     <img src="https://i.imgur.com/F6DoICr.png" width="100%"/>
@@ -90,5 +96,4 @@ class NetInterceptor : Interceptor {
 | generateId | 产生一个唯一标识符, 用于判断为同一网络请求 |
 | recordRequest | 记录请求信息 |
 | recordResponse | 记录响应信息 |
-| recordException | 记录请求异常信息 |
-| recordDuration | 记录请求间隔时间 |
+| recordException | 记录请求异常信息 |

docs/parse-list.md

@@ -0,0 +1,61 @@
+一般的JSON数据都是
+```json
+{
+    code:"200",
+    msg:"错误信息",
+    data: {
+        name: "drake"
+    }
+}
+```
+
+我们可以直接复制这个JSON来创建数据模型
+```kotlin
+scopeNetLife {
+    val data = Get<UserInfo>("/list").await().data
+}
+```
+
+但是这样每次都要`.data`才是你要的真实数据. 有些人就想省略直接不写code和msg, 希望直接返回data. 这样的确可以, 但是面临一个问题, 部分后端开发可能让data直接为JSON数组.
+由于Java的类型擦除机制, List的泛型在运行时将被擦除, 导致Gson或者FastJson等无法解析出正确的List模型
+
+所以这样的代码将报错
+```kotlin
+scopeNetLife {
+    val data = Get<List<Data>>("/list").await().data
+}
+```
+
+这里我推荐的解决方式是, 针对会data会为JSON数组的情况, 我们可以直接使用String创建一个扩展函数
+
+### 1) 定义解析函数
+
+创建一个顶层函数(即在类之外的函数, 直接存在kt文件中)
+```kotlin
+inline fun <reified T> String.toJsonArray(): MutableList<T> {
+    return JSON.parseArray(this, T::class.java)
+}
+```
+<br>
+
+!!! note
+    `JSON.parseArray`这是FastJson的函数, 如果你使用的是Gson可以使用
+    ```kotlin
+    inline fun <reified T> String.toJsonArray(): MutableList<T> {
+        return Gson().fromJson(this, TypeToken.getParameterized(List::class.java, T::class.java).type)
+    }
+    ```
+
+### 2) 使用
+
+```kotlin
+scope {
+    val listData = Post<String>("/list").await().toJsonArray<Data>()
+    listData[0]
+}
+```
+<br>
+
+!!! note
+    这样的优点是扩展方便, 整体清晰. 毕竟不是每个接口的data都可能是JSON数组, 而且这样还支持List嵌套(JSON数组嵌套)<br>
+    该扩展函数太简单我就不加入到框架中了, 大家复制粘贴下就OK了

docs/scope.md

@@ -3,10 +3,23 @@ Net的网络请求本身支持在官方的自带的作用域内使用, 但是考
 <br>
 全部使用顶层扩展函数
 
+
+## 异步任务的作用域
+
+快速创建可以捕捉异常的协程作用域
+
 |函数|描述|
 |-|-|
 |`scope`|创建最基础的作用域, 所有作用域都包含异常捕捉|
 |`scopeLife`|创建跟随生命周期取消的作用域|
+
+
+## 网络请求的作用域
+
+网络请求的作用域可以根据生命周期自动取消网络请求, 发生错误也会自动弹出吐司(可以自定义或者取消), 并且具备一些场景的特殊功能(例如加载对话框, 缺省页, 下拉刷新等)
+
+| 函数 | 描述 |
+|-|-|
 |`scopeNet`|创建自动处理网络错误的作用域|
 |`scopeNetLife`|创建自动处理网络错误的作用域, 且包含跟随生命周期|
 |`scopeDialog`|创建自动加载对话框的作用域, 生命周期跟随对话框|

mkdocs.yml

@@ -39,6 +39,7 @@ nav:
   - 作用域: scope.md
   - 全局配置: config.md
   - 转换器: convert.md
+  - 解析JSON数组: parse-list.md
   - 拦截器: interceptor.md
   - 异常追踪: exception-track.md
   - 自动化: