更新toResult/onResult的使用文档和示例

README.md

@@ -44,6 +44,7 @@ Net 3.x 版本为OkHttp4.x实现
 - DSL作用域编程
 - 配合ViewModel
 - 数据转换器
+- 队列/同步请求返回Result
 - 自动JSON解析
 - 自动处理下拉刷新和上拉加载
 - 自动处理分页加载

docs/config.md

@@ -44,7 +44,7 @@
 | setLog | 日志 |
 | setHost | 全局域名, 和initNet("Host")函数中的第一个参数等效 |
 | setConverter | [转换器](converter.md) |
-| setRequestInterceptor | [请求拦截器](interceptor.md) |
+| setRequestInterceptor | [请求拦截器](interceptor.md), 用于添加全局请求头/参数 |
 | onError | [全局错误处理](error-handle.md) |
 | onStateError | [全局缺省页错误处理](error-handle.md) |
 | onDialog | [全局对话框](auto-dialog.md) |

docs/convert-json-array.md

@@ -4,7 +4,7 @@
 
 ```kotlin
 scopeNetLife {
-    tv_fragment.text = Post<Model>("api").await()
+    tv_fragment.text = Post<UserModel>("api").await()
 }
 ```
 
@@ -52,7 +52,7 @@ scopeNetLife {
 
 ```kotlin
 scopeNetLife {
-    val arr = Post<Array<Model>>("api").await()
+    val arr = Post<Array<UserModel>>("api").await()
     arr.toMutableList() // 如果你就是要求集合, 可以使用函数将数组转换成集合
 }
 ```
@@ -61,6 +61,12 @@ scopeNetLife {
 
 我们可以直接使用String创建一个扩展函数
 
+```kotlin
+scopeNetLife {
+    tv_fragment.text = Post<String>("api").await().toJsonArray<List<UserModel>>()
+}
+```
+
 
 ### 1. 定义解析函数
 

docs/enqueue-request.md

@@ -2,6 +2,10 @@ Net支持OkHttp的原有的队列请求 -- `enqueue`
 
 > 队列属于接口回调请求, 由于其代码复杂, 非特殊情况下还是建议使用协程发起请求
 
+## Callback
+
+Callback属于OkHttp最原始的请求回调接口
+
 ```kotlin
 Net.post("api").enqueue(object : Callback {
     override fun onFailure(call: Call, e: IOException) {
@@ -32,6 +36,29 @@ NetCallback相较于Callback的特性
 2. 新增三个回调函数: onSuccess/onFailure/onComplete
 3. 以上三个回调函数都运行在主线程
 
+## onResult
+
+使用`onResult`可以更加灵活方便的处理队列请求. 使用Kotlin的空安全函数可以区分处理请求结果
+
+```kotlin
+Net.post("api").onResult<String> {
+
+    getOrNull()?.let { // 如果成功就不为Null
+        Log.d("日志", "请求成功")
+        tv_fragment.text = it
+    }
+
+    exceptionOrNull()?.apply {
+        Log.d("日志", "请求失败")
+        printStackTrace() // 如果发生错误就不为Null
+    }
+
+    Log.d("日志", "完成请求")
+}
+```
+
+onResult也是在主线程中执行
+
 |请求函数|描述|
 |-|-|
 |Net.get|标准Http请求方法|

docs/index.md

@@ -8,7 +8,7 @@ Net支持使用协程发起网络, 当然即使不会协程也可以使用该框
 
 ## 建议
 
-1. 禁止写一个函数封装一个请求函数, 如果公司工资不是按行数算钱, 禁止俄罗斯套娃. <br>
+1. 避免写一个函数封装一个请求函数, 禁止俄罗斯套娃. <br>
 2. Post/Get等函数本身就是高扩展性的`请求动作`. 你有特殊请求可以在拦截器/转换器处理, 或者使用TAG标签区分请求. <br>
 3. 如果想快速改变项目全局的请求URL可以声明为全局常量
 

docs/sync-request.md

@@ -2,14 +2,29 @@ Net支持在当前线程执行, 会阻塞当前线程的同步请求 -- `execute
 
 这里介绍的是不使用协程的同步请求. 由于Android主线程不允许发起网络请求, 这里我们得随便创建一个子线程才可以开发起同步请求
 
-```kotlin
-thread {
-    val result = Net.post("api").execute<String>() // 网络请求不允许在主线程
-    tv_fragment?.post {
-        tv_fragment?.text = result  // view要求在主线程更新
+=== "同步请求"
+
+    ```kotlin
+    thread {
+        val result = Net.post("api").execute<String>() // 网络请求不允许在主线程
+        tv_fragment?.post {
+            tv_fragment?.text = result  // view要求在主线程更新
+        }
+    }
+    ```
+=== "toResult"
+
+    ```kotlin
+    thread {
+        val result = Net.post("api").toResult<String>().getOrDefault("请求发生错误, 我这是默认值")
+        tv_fragment?.post {
+            tv_fragment?.text = result  // view要求在主线程更新
+        }
     }
-}
-```
+    ```
+
+1. `execute`在请求发生错误时会抛出异常
+2. `toResult`不会抛出异常, 通过`exception*`函数来获取异常信息, 且支持默认值等特性
 
 > 同步请求应用场景一般是在拦截器中使用, 拦截器默认是子线程
 

docs/updates.md

@@ -1,3 +1,8 @@
+## 3.0.3
+添加`onResult`函数来执行队列请求: [队列请求](../enqueue-request/#-result)
+
+添加`toResult`函数来执行同步请求: [同步请求](../sync-request/)
+
 ## 3.0.2
 修复多渠道无法安装问题
 

mkdocs.yml

@@ -72,4 +72,4 @@ nav:
   - 日志记录器: log-recorder.md
   - 轮循器: interval.md
   - 更新日志: updates.md
-  - 2.x文档: api/net/index.md
+  - 3.x文档: api/net/index.md

sample/src/main/java/com/drake/net/sample/ui/fragment/EnqueueRequestFragment.kt

@@ -1,13 +1,12 @@
 package com.drake.net.sample.ui.fragment
 
 import android.os.Bundle
+import android.util.Log
 import android.view.View
 import androidx.fragment.app.Fragment
 import com.drake.net.Net
-import com.drake.net.interfaces.NetCallback
 import com.drake.net.sample.R
 import kotlinx.android.synthetic.main.fragment_fastest.*
-import okhttp3.Call
 
 class EnqueueRequestFragment : Fragment(R.layout.fragment_enqueue_request) {
 
@@ -24,12 +23,28 @@ class EnqueueRequestFragment : Fragment(R.layout.fragment_enqueue_request) {
         // })
 
         // NetCallback支持数据转换
-        Net.post("api") {
-            param("password", "Net123")
-        }.enqueue(object : NetCallback<String>() {
-            override fun onSuccess(call: Call, data: String) {
-                tv_fragment.text = data // onSuccess 属于主线程
+        // Net.post("api") {
+        //     param("password", "Net123")
+        // }.enqueue(object : NetCallback<String>() {
+        //     override fun onSuccess(call: Call, result: String) {
+        //         tv_fragment.text = result // onSuccess 属于主线程
+        //     }
+        // })
+
+        // 简化版本的队列请求
+        Net.post("api").onResult<String> {
+
+            getOrNull()?.let { // 如果成功就不为Null
+                Log.d("日志", "请求成功")
+                tv_fragment.text = it
             }
-        })
+
+            exceptionOrNull()?.apply {
+                Log.d("日志", "请求失败")
+                printStackTrace() // 如果发生错误就不为Null
+            }
+
+            Log.d("日志", "完成请求")
+        }
     }
 }

sample/src/main/java/com/drake/net/sample/ui/fragment/SyncRequestFragment.kt

@@ -14,6 +14,7 @@ class SyncRequestFragment : Fragment(R.layout.fragment_sync_request) {
 
         thread {
             val result = Net.post("api").execute<String>() // 网络请求不允许在主线程
+            // val result = Net.post("api").toResult<String>().getOrDefault("请求发生错误, 我这是默认值")
             tv_fragment?.post {
                 tv_fragment?.text = result  // view要求在主线程更新
             }