("api")
- fastest(backupTask, backupTask1)
+ fastest(listOf(backupTask, backupTask1))
}
}
-```
-
-
-
-
-> 不要尝试使用这种方式来取代CDN加速
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/docs/https.md b/docs/https.md
index ff3a0e9f1..f1cfcffd8 100644
--- a/docs/https.md
+++ b/docs/https.md
@@ -1,10 +1,8 @@
-Https访问主要就是证书配置问题, Net可以使用OkHttp一切函数组件, 且简化证书配置流程
-
-> OkHttp如何配置证书, Net就可以如何配置证书
+Net可快速配置Https证书, 且允许使用OkHttp任何Api
## 使用CA证书
-Https如果是使用的CA颁发的证书, 不需要任何配置Net可以直接访问
+Https如果使用的CA证书, 不需要任何配置可以直接访问
```kotlin
scopeNetLife {
@@ -14,12 +12,12 @@ scopeNetLife {
## 信任所有证书
-信任所有证书可以解决无法访问私有证书的Https地址问题, 但是这么做就失去了使用证书的含义, 不建议此做法
+信任所有证书可以解决无法访问私有证书的Https地址问题
=== "全局配置"
```kotlin
- NetConfig.initialize("https://github.com/liangjingkanji/Net/", this){
+ NetConfig.initialize(Api.HOST, this){
trustSSLCertificate() // 信任所有证书
}
```
@@ -37,12 +35,12 @@ scopeNetLife {
## 导入证书
-私有证书可以放到任何位置, 只要能读取到`InputStream`流对象即可
+私有证书可以放到任何位置, 只要读取到`InputStream`流对象即可
=== "全局配置"
```kotlin
- NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
+ NetConfig.initialize(Api.HOST, this) {
val privateCertificate = resources.assets.open("https.certificate")
setSSLCertificate(privateCertificate)
}
diff --git a/docs/img/book-open.svg b/docs/img/book-open.svg
new file mode 100644
index 000000000..b0cbc997c
--- /dev/null
+++ b/docs/img/book-open.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/img/code-preview.png b/docs/img/code-preview.png
new file mode 100644
index 000000000..b6fd23b99
Binary files /dev/null and b/docs/img/code-preview.png differ
diff --git a/docs/img/preview.png b/docs/img/preview.png
new file mode 100644
index 000000000..da466e86e
Binary files /dev/null and b/docs/img/preview.png differ
diff --git a/docs/index.md b/docs/index.md
index 01ee9d217..9a2400302 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,71 +1,69 @@
-本框架使用Android主流的Http框架OkHttp作为请求内核, 遵守不影响OkHttp原有的函数组件使用原则开发
+Net是基于[OkHttp](https://github.com/square/okhttp)/协程的非侵入式框架(可使用所有Api), 可升级OkHttp版本保持网络安全
-STAR/分享可以让更多人参与到本开源项目, 点击文档右上角小铅笔可直接修订文档 ↗
+STAR/分享可以让更多人参与到本开源项目
-## 前言
-
-1. 任何本文档没有提到的功能都可以通过搜索`"OkHttp如何**"`来解决, 因为本框架支持OkHttp所有功能/组件
-1. 建议创建一个Api.kt的`object`单例类存储所有请求路径常量
-1. `Post/Get等`函数属于请求动作. `scope**`等函数属于作用域, 假设你有某个请求需要重复使用建议封装`请求动作`而不是作用域
-1. 如果你觉得文档看不懂或者有歧义那肯定是作者问题, 请反馈给作者或者自我修订
+!!! note "前言"
+ - 未实现功能可以搜索`"OkHttp如何XX"`来扩展
+ - 阅读示例/源码来学习如何封装
+ - 如果觉得文档看不懂那肯定是作者问题, 请反馈给作者或者自我修订
## 使用
-这里演示发起网络`请求百度网站`内容的三个步骤
+这里演示发起网络`请求网站内容`的三个步骤
1. 创建作用域
-1. 发起请求
-1. 接收数据
+1. 发起请求动作
+1. 等待数据返回
-=== "单个请求"
+=== "简单请求"
```kotlin
- scopeNetLife { // 创建作用域
+ scopeNetLife { 创建作用域
// 这个大括号内就属于作用域内部
val data = Get("https://github.com/liangjingkanji/Net/").await() // 发起GET请求并返回`String`类型数据
}
```
-=== "串行请求"
+=== "同步请求"
```kotlin
scopeNetLife {
- val data = Get("http://www.baidu.com/").await() // 请求A 发起GET请求并返回数据
- val data = Get("https://github.com/liangjingkanji/Net/").await() // 请求B 将等待A请求完毕后发起GET请求并返回数据
+ val userInfo = Get("https://github.com/liangjingkanji/BRV/").await() // 立即请求
+ val config = Get("https://github.com/liangjingkanji/Net/"){
+ param("userId", userInfo.id) // 使用上个请求的数据作为参数
+ }.await() // 请求B 将等待A请求完毕后发起GET请求并返回数据
}
```
=== "并发请求"
```kotlin
scopeNetLife {
// 以下两个网络请求属于同时进行中
- val aDeferred = Get("https://github.com/liangjingkanji/Net/") // 发起GET请求并返回一个对象(Deferred)表示"任务A"
- val bDeferred = Get("https://github.com/liangjingkanji/Net/") // 发起请求并返回"任务B"
+ val getUserInfoAsync = Get("https://github.com/liangjingkanji/Net/") // 立即请求
+ val getConfigAsync = Get("https://github.com/liangjingkanji/BRV/") // 立即请求
- // 随任务同时进行, 但是数据依然可以按序返回
- val aData = aDeferred.await() // 等待任务A返回数据
- val bData = bDeferred.await() // 等待任务B返回数据
+ val userInfo = getUserInfoAsync.await() // 等待数据返回
+ val config = getConfigAsync.await()
}
```
-多个网络请求放在同一个作用域内就可以统一控制, 如果你的多个网络请求毫无关联, 你可以创建多个作用域.
+多个网络请求在同一个作用域内可以统一控制, 如果多个网络请求之间毫无关联, 可以创建多个作用域来请求
-> 多进程或Xposed项目要求[初始化](config.md/#_1)
+> 多进程或Xposed项目要求先[初始化](config.md/#_1)
-> 当`Get`或`Post`等函数调用就会开始发起网络请求, `await`只是等待其请求成功返回结果, 所以如果你在`await`后执行的网络请求,这不属于并发(属于串行)
+并发请求错误示例
-并发的错误示例
```kotlin hl_lines="3"
scopeNetLife {
// 请求A
- val aDeferred = Get("https://github.com/liangjingkanji/Net/").await()
- // 请求B, 由于上面使用`await()`函数, 所以必须等待A请求返回结果后才会执行B
- val bDeferred = Get("https://github.com/liangjingkanji/Net/")
+ val userInfo = Get("https://github.com/liangjingkanji/Net/").await()
+ // 由于上面使用`await()`函数, 所以必须等待A请求返回结果后才会执行B
+ val getConfigAsync = Post("https://github.com/liangjingkanji/Net/")
- val bData = bDeferred.await() // 等待任务B返回数据
+ val config = getConfigAsync.await() // 等待任务B返回数据
}
```
@@ -81,38 +79,16 @@ scopeNetLife {
| Response | 最基础的响应 |
| File | 文件对象, 这种情况其实应当称为[下载文件](download-file.md) |
-非以上类型要求[自定义转换器](converter.md)
-
-> 转换器的返回值决定你的网络请求的返回结果类型, 你甚至可以返回null, 前提是泛型为可空类型
-
-
-## RestFul
-Net支持RestFul设计风格
-
```kotlin
scopeNetLife {
- tvFragment.text = Get("https://github.com/liangjingkanji/Net/").await()
- tvFragment.text = Post("https://github.com/liangjingkanji/Net/").await()
- tvFragment.text = Head("https://github.com/liangjingkanji/Net/").await()
- tvFragment.text = Put("https://github.com/liangjingkanji/Net/").await()
- tvFragment.text = Patch("https://github.com/liangjingkanji/Net/").await()
- tvFragment.text = Delete("https://github.com/liangjingkanji/Net/").await()
- tvFragment.text = Trace("https://github.com/liangjingkanji/Net/").await()
- tvFragment.text = Options("https://github.com/liangjingkanji/Net/").await()
+ val file = Get(Api.FILE).await()
}
```
-## 函数
-
-默认在IO线程执行网络请求(通过作用域参数可以控制Dispatch调度器), 要求在协程作用域内执行.
+详细查看[转换器](converter.md), 非以上类型要求[自定义转换器](converter-customize.md)
-|请求函数|描述|
-|-|-|
-| [Get](api/-net/com.drake.net/-get.html)|标准Http请求方法|
-| [Post](api/-net/com.drake.net/-post.html)|标准Http请求方法|
-| [Head](api/-net/com.drake.net/-head.html)|标准Http请求方法|
-| [Options](api/-net/com.drake.net/-options.html)|标准Http请求方法|
-| [Trace](api/-net/com.drake.net/-trace.html)|标准Http请求方法|
-| [Delete](api/-net/com.drake.net/-delete.html)|标准Http请求方法|
-| [Put](api/-net/com.drake.net/-put.html)|标准Http请求方法|
-| [Patch](api/-net/com.drake.net/-patch.html)|标准Http请求方法|
\ No newline at end of file
+---
+[下载Apk](https://github.com/liangjingkanji/Net/releases/latest/download/net-sample.apk){ .md-button }
+[下载源码](https://github.com/liangjingkanji/Net.git){ .md-button }
+[示例代码](https://github.com/liangjingkanji/Net/tree/master/sample/src/main/java/com/drake/net/sample/ui/fragment){ .md-button }
+[界面演示](https://github.com/liangjingkanji/BRV){ .md-button }
diff --git a/docs/interceptor.md b/docs/interceptor.md
index f489654ff..abd10aed7 100644
--- a/docs/interceptor.md
+++ b/docs/interceptor.md
@@ -1,11 +1,12 @@
-总共支持两种拦截器
+根据使用场景实现以下接口来拦截网络请求
-1. `Interceptor`, 支持市面上的所有OkHttp拦截器组件库, 更方便修改请求/响应信息, 可以转发请求
-2. `RequestInterceptor`, 部分场景更简单易用的轻量拦截器, 更方便添加全局请求头/参数, 无法转发请求
+1. `Interceptor`: 支持三方OkHttp拦截器组件, 允许修改请求/响应信息, 可以转发请求
+2. `RequestInterceptor`: Net独有的轻量级拦截器, 允许修改全局请求头/请求参数, 无法转发请求
-> 实际项目中可能存在需求加密请求/解密响应, 非常不建议封装Post/Get等请求动作(低扩展性/增加学习成本), 任何项目需求都可以通过自定义拦截器和转换器实现
-> [常见拦截器示例](https://github.com/liangjingkanji/Net/tree/master/sample/src/main/java/com/drake/net/sample/interceptor)
+!!! Failure "禁止随意封装"
+ 不应为全局参数/加密等封装请求方法, 应自定义拦截器/转换器来实现, [常见拦截器示例](https://github.com/liangjingkanji/Net/tree/master/sample/src/main/java/com/drake/net/sample/interceptor)
+
## 拦截器
@@ -17,14 +18,14 @@ class App : Application() {
override fun onCreate() {
super.onCreate()
- NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
+ NetConfig.initialize(Api.HOST, this) {
addInterceptor(RefreshTokenInterceptor())
}
}
}
```
-以下为简单演示客户端自动刷新token拦截器
+演示客户端自动刷新token的拦截器
```kotlin
/**
@@ -50,12 +51,10 @@ class RefreshTokenInterceptor : Interceptor {
## 请求拦截器
-RequestInterceptor属于轻量级的请求拦截器, 在每次请求的时候该拦截器都会被触发(无法修改响应信息), 方便添加全局请求头/参数
-
-示例
+轻量级拦截器(`RequestInterceptor`), 其Api更适合添加全局请求头/参数
```kotlin
-NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
+NetConfig.initialize(Api.HOST, this) {
setRequestInterceptor(object : RequestInterceptor {
override fun interceptor(request: BaseRequest) {
request.param("client", "Net")
@@ -65,4 +64,4 @@ NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
}
```
-可以看到`setRequestInterceptor`是set开头. 仅支持一个请求拦截器, 不像`addInterceptor`支持多个请求拦截器
\ No newline at end of file
+可以看出`setRequestInterceptor`仅支持一个, `addInterceptor`支持多个拦截器
\ No newline at end of file
diff --git a/docs/interval.md b/docs/interval.md
index 094c54a4a..0f9a5cc4f 100644
--- a/docs/interval.md
+++ b/docs/interval.md
@@ -1,4 +1,4 @@
-轮询器(计时器)属于项目中常见需求, 而本框架拥有非常强大的轮询器工具. 支持以下特性
+Net自带轮询器(计时器), 包含以下特性
- 正计时
- 倒计时
@@ -8,11 +8,11 @@
- 页面销毁自动取消
-=== "指定轮循次数/间隔"
+=== "限制次数/间隔"
```kotlin
interval = Interval(100, 1, TimeUnit.SECONDS).life(this) // 自定义计数器个数的轮询器
```
-=== "仅轮循间隔"
+=== "无限执行"
```kotlin
interval = Interval(1, TimeUnit.SECONDS) // 每秒回调一次, 不会自动结束
```
@@ -31,7 +31,7 @@ interval.subscribe {
}.start()
```
-| Interval函数 | 描述 |
+| Interval | 描述 |
|-|-|
| start | 开始轮询器 |
| stop | 停止 |
@@ -43,6 +43,4 @@ interval.subscribe {
| subscribe | 每次计时都会执行该回调 |
| finish | 当计时器完成时执行该回调, 执行stop后也会回调 |
| life | 指定生命周期自动取消轮询器 |
-| onlyResumed | 当界面不可见时暂停, 当界面可见时继续 |
-
-[完整源码](https://github.com/liangjingkanji/Net/blob/master/sample/src/main/java/com/drake/net/sample/ui/fragment/SuperIntervalFragment.kt)
\ No newline at end of file
+| onlyResumed | 当界面不可见时暂停, 当界面可见时继续 |
\ No newline at end of file
diff --git a/docs/issues.md b/docs/issues.md
index 5c6bd24ce..d927868b8 100644
--- a/docs/issues.md
+++ b/docs/issues.md
@@ -1,8 +1,19 @@
-## 常见问题
-
-- [networkSecurityConfig导致无法打包](https://github.com/liangjingkanji/Net/issues/57)
-- [没有我需要的请求参数类型](https://github.com/liangjingkanji/Net/issues/56)
-- [没有我需要的功能](https://github.com/liangjingkanji/Net/issues/58)
-- [使用inline reified封装请求函数导致崩溃](https://github.com/liangjingkanji/Net/issues/54)
-- [错误提示 toast 内存泄漏](https://github.com/liangjingkanji/Net/issues/65)
-- [如何使用Cookie](https://github.com/liangjingkanji/Net/issues/51)
+Net最大的特点在于完美支持OkHttp的所有功能组件,
+而Android上大部分都是基于OkHttp的网络请求解决方案
+所以如果存在Net没有实现的功能可以百度/谷歌搜索`"OkHttp如何实现XX"`, 然后可以很容易在Net中使用
+
+## 低版本兼容
+
+如果你是在 Android 5 (API level 21)
+以上开发建议使用最新版本: [Net](https://github.com/liangjingkanji/Net)
+如果要求低至 Android 4.4 (API level 19)
+请使用兼容版本: [Net-okhttp3](https://github.com/liangjingkanji/Net-okhttp3)
+
+如果需更低版本支持建议拉取仓库修改`minSdkVersion`后编译成aar使用
+
+## 开发者交流
+
+- [反馈问题](https://github.com/liangjingkanji/Net/issues)
+- [其他开发者提及问题](https://github.com/liangjingkanji/Net/issues)
+- [交流社区](https://github.com/liangjingkanji/Net/discussions)
+- 
diff --git a/docs/kotlin-serialization.md b/docs/kotlin-serialization.md
index 8bfbba6c1..0a2bc6678 100644
--- a/docs/kotlin-serialization.md
+++ b/docs/kotlin-serialization.md
@@ -1,25 +1,30 @@
-1. 从Net3开始支持使用[kotlin-serialization](https://github.com/Kotlin/kotlinx.serialization)(以下简称ks)
+1. 从Net3开始支持使用 [Kotlin-Serialization](https://github.com/Kotlin/kotlinx.serialization) (以下简称ks)
+2. 更多了解请阅读: [Kotlin最强解析库 - kotlin-serialization](https://juejin.cn/post/6963676982651387935)
-1. 更多使用教程请阅读: [Kotlin最强解析库 - kotlin-serialization](https://juejin.cn/post/6963676982651387935)
+## 特点
-
-## kotlin-serialization 特点
-
-- kotlin官方库
+- 官方库
- 动态数据类型解析
- 自定义序列化器
- 支持ProtoBuf/JSON等数据结构序列化
-- 非空覆盖(即返回的Json字段为null则使用数据类默认值)
-- 启用宽松模式, Json和数据类字段无需一致
+- 非空覆盖(即JSON字段为null则使用变量默认值)
+- 启用宽松模式, JSON和数据类结构无需一致
- 解析任何类型(Map/List/Pair...)
-> ks的数据模型类都要求使用注解`@Serializable`(除非自定义解析过程), 父类和子类都需要使用
-> 一般开发中都是使用[插件生成数据模型](model-generate.md), 所以这并不会增加工作量. 即使手写也只是一个注解, 但是可以带来默认值支持和更安全的数据解析
+!!! Failure "强制注解"
+ ks的数据类都要求使用注解`@Serializable`(除非自定义解析), 父类和子类都需要
+
+
+
+!!! Success "生成默认值"
+ 使用[插件生成数据Model](model-generate.md), 支持自动生成默认值和注解
+
+ 生成默认值可避免后端返回异常数据导致解析崩溃, 以及反复编写判空代码
## 依赖
-项目 build.gradle
+Project build.gradle
```kotlin
@@ -27,7 +32,7 @@ classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
// 和Kotlin插件同一个版本号即可
```
-module build.gradle
+Model build.gradle
```kotlin
apply plugin: "kotlin-kapt"
@@ -37,12 +42,11 @@ implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.0"
## 配置转换器
-这里使用Demo中的[SerializationConvert](https://github.com/liangjingkanji/Net/blob/master/sample/src/main/java/com/drake/net/sample/converter/SerializationConverter.kt)作演示.
-如果你业务有特殊需要可以复制Demo中的转换器代码稍加修改
+这里使用示例代码中 [SerializationConvert](https://github.com/liangjingkanji/Net/blob/master/sample/src/main/java/com/drake/net/sample/converter/SerializationConverter.kt) 作为演示
=== "全局配置"
```kotlin
- NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
+ NetConfig.initialize(Api.HOST, this) {
setConverter(SerializationConvert())
// ... 其他配置
}
@@ -58,7 +62,6 @@ implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.0"
```kotlin
scopeNetLife {
- // 这里后端直接返回的Json数组
val userList = Get>("list") {
converter = SerializationConvert()
}.await()
@@ -72,9 +75,6 @@ scopeNetLife {
data class UserModel(var name: String, var age: Int, var height: Int)
```
-> 具体解析返回的JSON中的某个字段请在转换器里面自定, 其注意如果存在父类, 父类和子类都需要使用`@Serializable`注解修饰
-如果想详细了解KS, 请阅读文章: [Kotlin最强解析库 - kotlin-serialization](https://juejin.cn/post/6963676982651387935)
-
## 常用配置
以下为反序列化Json常用配置
@@ -91,7 +91,6 @@ val jsonDecoder = Json {
@Serializable
data class Data(var name:String = "", var age:Int = 0)
```
-> 建议为数据类所有字段设置默认值, 避免后端数据缺失导致解析异常, 也减少频繁判空操作
### 启用默认值
diff --git a/docs/log-notice.md b/docs/log-notice.md
index 1d66f83dc..1efc53960 100644
--- a/docs/log-notice.md
+++ b/docs/log-notice.md
@@ -1,10 +1,11 @@
-前面介绍过如何使用AndroidStudio来抓取网络日志. 但是我们可能需要在App使用过程或者让测试人员查看日志
+使用三方库 [Chucker](https://github.com/ChuckerTeam/chucker) 在通知栏记录网络请求日志
-这里介绍一个第三方日志拦截器[chucker](https://github.com/ChuckerTeam/chucker), 他会在Net发起请求后自动在设备通知栏显示网络请求记录, 点击通知可以跳转详情
+
+ { width="300" }
+ Chucker
+
-
-
-添加依赖
+依赖
```groovy
implementation "com.github.chuckerteam.chucker:library:3.5.2"
@@ -34,4 +35,4 @@ override fun onCreate() {
}
```
-更多自定义功能请查看[chucker](https://github.com/ChuckerTeam/chucker)主页
+自定义功能浏览 [Chucker](https://github.com/ChuckerTeam/chucker) 官网
diff --git a/docs/log-recorder.md b/docs/log-recorder.md
index 78639be5d..62f692d16 100644
--- a/docs/log-recorder.md
+++ b/docs/log-recorder.md
@@ -1,23 +1,24 @@
-由于LogCat日志可读性差, 所以Net支持以下两种方案
+Net支持两种方式
+1. AndroidStudio的[Profiler](https://developer.android.com/studio/profile/network-profiler?hl=zh-cn)
+ - 动态曲线图
+ - 可查看所有OkHttp的请求
+ - 无法捕获启动一瞬间的请求
+
-1. 使用AndroidStudio的[Profiler](https://developer.android.com/studio/profile/network-profiler?hl=zh-cn)监听网络
- - 可以查看项目所有OkHttp框架发起的网络请求
- - 网络请求是动态曲线图, 查不太方便
- - 启动应用时立刻触发的请求无法捕捉
+2. [Okhttp Profiler](https://github.com/itkacher/OkHttpProfiler)
+ - 列表显示
+ - 要求添加`LogRecordInterceptor`
+ - 原理是插件捕获LogCat日志, 线上环境请关闭
-
-2. 安装[Okhttp Profiler](https://github.com/itkacher/OkHttpProfiler)插件 (推荐)
- - 列表显示请求
- - 要求添加Net的`LogRecordInterceptor`拦截器
- - 实际上是插件捕获logCat生成的日志, 线上环境需要关闭
+以下介绍`LogRecordInterceptor`
## 添加日志拦截器
```kotlin hl_lines="2"
-NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
+NetConfig.initialize(Api.HOST, this) {
addInterceptor(LogRecordInterceptor(BuildConfig.DEBUG))
}
```
@@ -28,7 +29,7 @@ NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
| requestByteCount | 请求日志信息最大字节数, 默认1MB |
| responseByteCount | 响应日志信息最大字节数, 默认4MB |
-这样会可以在LogCat看到日志输出, 但是我们要使用插件预览就需要第 2 步
+此时仅LogCat输出日志, 要预览请安装插件
## 安装插件
@@ -43,7 +44,10 @@ NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
-> 请在每次使用前都先打开插件窗口, 如果有延迟或者不显示就反复打开下窗口
+!!! warning "不显示日志"
+ 请在请求前确保有打开过插件窗口, 如果依然不显示可以反复打开/关闭窗口
+
+ 每次AS更新都需要该插件作者适配, 可能存在beta版本作者没有适配情况
@@ -60,35 +64,36 @@ NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
| 
清空 | 清空记录 |
-## 自定义日志(解密)
+## 自定义日志
-通过继承`LogRecordInterceptor`可以覆写函数自定义自己的日志输出逻辑
+继承`LogRecordInterceptor`复写函数实现自定义
-1. 如果你的请求体是被加密的内容, 你可以通过覆写`requestString`函数返回解密后的请求信息
-2. 如果你的响应体是被加密的内容, 你可以通过覆写`responseString`函数返回解密后的响应信息
+1. 复写`getRequestLog`返回解密请求参数
+2. 复写`getResponseLog`返回解密响应参数
-然后初始化时添加自己实现拦截器即可
+初始化时添加自己的拦截器
```kotlin
-NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
+NetConfig.initialize(Api.HOST, this) {
addInterceptor(MyLogRecordInterceptor(BuildConfig.DEBUG))
}
```
-## LogCat过滤
-实际上Net的网络日志还是会被打印到LogCat, 然后通过插件捕捉显示.
+## 日志过滤
-如果不想LogCat的冗余日志影响查看其它日志, 可以通过AndroidStudio的功能折叠隐藏, 添加一个`OKPREL_`过滤字段即可
+不想网络日志影响其他日志查看, 可以添加`OKPREL_`为日志折叠规则
## 其他网络框架
-可能你项目中还残留其他网络框架, 也可以使用Net的日志记录器`LogRecorder`来为其他框架打印日志信息. 如果是基于OkHttp的框架那可以直接使用LogRecordInterceptor
+`LogRecordInterceptor`属于OkHttp拦截器, 其他网络请求框架也可以使用
+
+甚至可以直接使用`LogRecorder`输出日志
-| 函数 | 描述 |
+| LogRecorder | 描述 |
|-|-|
| generateId | 产生一个唯一标识符, 用于判断为同一网络请求 |
| recordRequest | 记录请求信息 |
diff --git a/docs/model-generate.md b/docs/model-generate.md
index 2be5e70a3..5fbdf56fd 100644
--- a/docs/model-generate.md
+++ b/docs/model-generate.md
@@ -1,6 +1,4 @@
-在请求网络数据过程中会需要编写大量的数据模型对象, 映射后端返回的数据创建数据对象. 因为我们业务逻辑中一般是直接数据对象更为方便
-
-创建数据模型我不推荐手写, 错误率高且不方便. 我推荐使用`JSON To Kotlin Class` 插件自动生成
+应该没人会完全手写数据模型吧? 建议使用`JSON To Kotlin Class` 插件完成
## 安装插件
@@ -18,9 +16,10 @@
-然后就会在你选中的分包下生成一个数据模型类了
+然后就会在选中的分包下生成一个数据模型类了
-> 不要输入json数组去生成, 输入数组里面的对象即可(否则生成的类会自动继承ArrayList). 然后请求的时候使用List泛型即可, 例如`Get>`
+!!! Warning "不要生成数组"
+ 不要输入JSON数组生成(否则生成的类会继承ArrayList), 输入JSON对象, 请求使用`Get>`
## 高级设置
@@ -38,7 +37,7 @@
### 使用的框架
-生成数据模型时会兼容你使用的框架, 例如Moshi和Ks可能需要注解, 然后会自动生成SerialName这些名称注解
+生成数据模型时会兼容你使用的框架, 例如Moshi和ks可能需要注解, 然后会自动生成SerialName这些名称注解
diff --git a/docs/okhttp-client.md b/docs/okhttp-client.md
index 8b7937ff7..3cf60cabe 100644
--- a/docs/okhttp-client.md
+++ b/docs/okhttp-client.md
@@ -1,6 +1,4 @@
-每个请求都会存在一个客户端对象, 既OkHttpClient
-
-Net在全局维护了一个OkHttpClient对象, 在NetConfig.okHttpClient的字段
+Net全局持有一个`OkHttpClient`对象发起请求
```kotlin
object NetConfig {
@@ -8,40 +6,38 @@ object NetConfig {
}
```
-> 当然也支持创建一个新的客户端来发起请求(配置区别于全局客户端)
-
-## 全局OkHttpClient
+## 全局
```kotlin
-NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
+NetConfig.initialize(Api.HOST, this) {
// 此处this即为OkHttpClient.Builder
}
```
-## 单例OkHttpClient
+## 单例
每个请求可能存在独立的OkHttpClient配置, 我们可以单例配置客户端选项
-1. 在全局的OkHttpClient配置基础下修改
-
-```kotlin
-scopeNetLife {
- tv_response.text = Get("https://github.com/liangjingkanji/Net/") {
- setClient {
- // 此处this即为OkHttpClient.Builder
- trustCertificate()
- }
- }.await()
-}
-```
-
-2. 完全重新创建一个OkHttpClient, 一般情况不推荐重新创建一个OkHttpClient, 因为一个新的OkHttpClient会重新创建线程池/连接池等造成内存消耗等
-
-```kotlin
-scopeNetLife {
- tv_response.text = Get("https://github.com/liangjingkanji/Net/") {
- okHttpClient = OkHttpClient.Builder().build()
- }.await()
-}
-```
\ No newline at end of file
+=== "修改全局客户端"
+ ```kotlin
+ scopeNetLife {
+ tv_response.text = Get(Api.PATH) {
+ setClient {
+ // 此处this即为OkHttpClient.Builder
+ trustCertificate()
+ }
+ }.await()
+ }
+ ```
+ 在全局的OkHttpClient配置基础下修改
+
+=== "创建新客户端"
+ ```kotlin
+ scopeNetLife {
+ tv_response.text = Get(Api.PATH) {
+ okHttpClient = OkHttpClient.Builder().build()
+ }.await()
+ }
+ ```
+ 创建新的OkHttpClient, 一般不推荐, 因为新OkHttpClient会重新创建线程池/连接池等造成内存消耗
\ No newline at end of file
diff --git a/docs/practice.md b/docs/practice.md
deleted file mode 100644
index 5cadd8326..000000000
--- a/docs/practice.md
+++ /dev/null
@@ -1,11 +0,0 @@
-本章节毫无意义, 仅仅是有些人完全没有下载过本仓库, 且不知道项目中存在sample模块
-
-## 使用场景
-实际上本框架使用也就两三行代码而已, 并且常见使用场景在本项目的sample模块中也进行了全面的讲解
-
-
-
-## 结合案例
-但有些人可能完全是新手, 那么推荐结合BRV的sample, 里面有常见的界面数据加载示例
-
-
\ No newline at end of file
diff --git a/docs/read-cache.md b/docs/read-cache.md
deleted file mode 100644
index a937006ef..000000000
--- a/docs/read-cache.md
+++ /dev/null
@@ -1,59 +0,0 @@
-Net_v2基于[Kalle](https://github.com/yanzhenjie/Kalle)开发, 支持Kalle的9种缓存模式
-
-缓存模式要求在初始化的时候开启
-
-```kotlin
-NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
- cacheEnabled() // 开启缓存
-}
-```
-
-=== "请求缓存或网络"
- ```kotlin
- scopeNetLife {
- // 先读取缓存, 如果缓存不存在再请求网络
- tvFragment.text = Get("api", cache = CacheMode.READ_CACHE_NO_THEN_NETWORK).await()
- Log.d("日志", "读取缓存")
- }
- ```
-=== "读取缓存然后请求网络"
-
- ```kotlin
- scopeNetLife {
- // 然后执行这里(网络请求)
- tvFragment.text = Post("api", cache = CacheMode.NETWORK_YES_THEN_WRITE_CACHE).await()
- Log.d("日志", "网络请求")
- }.preview {
- // 先执行这里(仅读缓存), 任何异常都视为读取缓存失败
- tvFragment.text = Get("api", cache = CacheMode.READ_CACHE).await()
- Log.d("日志", "读取缓存")
- }
- ```
-
-预读模式本质上就是创建一个`preview`附加作用域, 里面的所有异常崩溃都会被静默捕捉(算作缓存失败), 会优先于`scope*`执行, 然后再执行scope本身,
-而且一旦缓存读取成功(`preview`内部无异常)即使网络请求失败也可以不提醒用户任何错误信息(可配置)
-
-
-
-> `preview`并没有说只能用在网络缓存上, 也可以用于其他的处理场景
-
-
-
-## 缓存模式
-
-缓存模式属于`CacheMod`枚举, 建议开发者浏览缓存模式的源码和注释，有助于理解和更好的使用缓存模式。
-
-| 常量 | 描述 |
-| ------------------------------ | ------------------------------------------------------------ |
-| `HTTP` | 发起请求前如果本地已经有缓存，如果缓存未过期则返回缓存数据，
如果过期则带上缓存头去服务器做校验。如果服务器响应304则返回缓存数据，否则读取服务器数据，
根据服务器响应头来决定是否写入缓存数据 |
-| `HTTP_YES_THEN_WRITE_CACHE` | 发起请求前如果本地已经有缓存则带缓存头，服务器响应304才返回缓存数据，否则读取服务器数据，
并写入缓存数据 |
-| `NETWORK` | 发起请求前不管本地是否有缓存，都不会带上缓存头，
不论服务器响应头如何，绝不写入缓存数据 |
-| `NETWORK_YES_THEN_HTTP` | 发起请求前不管本地是否有缓存，都不会带上缓存头，
根据服务器响应头来决定是否写入缓存数据 |
-| `NETWORK_YES_THEN_WRITE_CACHE` | 发起请求前不管本地是否有缓存，都不会带上缓存头，
请求成功后写入缓存数据 |
-| `NETWORK_NO_THEN_READ_CACHE` | 发起请求前不管本地是否有缓存，都不会带上缓存头，请求失败后尝试读取缓存,
根据服务器响应头来决定是否写入缓存数据 |
-| `READ_CACHE ` | 仅读取缓存 |
-| `READ_CACHE_NO_THEN_NETWORK` | 读取缓存，如果缓存不存在就请求网络，
不写入缓存数据 |
-| `READ_CACHE_NO_THEN_HTTP` | 先读取缓存，如果缓存不存在就请求网络，
根据服务器响应头来决定是否写入缓存数据 |
-| `READ_CACHE_NO_THEN_NETWORK_THEN_WRITE_CACHE` | 先本地有缓存则读取缓存，如果没有缓存则读取网络并且写入缓存,
该模式请求成功后会永久使用缓存, 但你可以指定动态的cacheKey来让缓存失效
例如一天后失效, 可以做到客户端完全控制缓存 |
-
-
\ No newline at end of file
diff --git a/docs/repeat-request.md b/docs/repeat-request.md
index 99f260f94..a14219524 100644
--- a/docs/repeat-request.md
+++ b/docs/repeat-request.md
@@ -1,25 +1,20 @@
-某个重复发起的请求, 在发起的时候自动取消旧的网络请求.
+常用于筛选列表请求, 选择新的筛选条件时应将上次未完成的取消后再发起请求
-这种应用场景常见于筛选菜单, 每次点击菜单都会发起网络请求返回筛选后的列表, 但是请求未完成时, 用户又点击了新的筛选条件, 这个时候应该取消上次请求, 重新发起新的请求
+在Net禁止重复请求仅2行代码
-这个需求在Net中非常好实现, 保存一个变量即可
-
-```kotlin
+```kotlin hl_lines="4"
var scope: AndroidScope? = null
-btn_request.setOnClickListener {
- tv_result.text = "请求中"
- scope?.cancel() // 如果存在则取消
+btnFilter.setOnClickListener {
+ scope?.cancel()
scope = scopeNetLife {
val result = Post("api").await()
- Log.d("日志", "请求到结果") // 你一直重复点击"发起请求"按钮会发现永远无法拿到请求结果, 因为每次发起新的请求会取消未完成的
- tv_result.text = result
}
}
```
-当`scope`不为空时即表示存在上个请求, 我们无论上个请求是否完成都调用`cancel`函数保证取消即可
+当`scope`不为空时表示存在旧请求, 无论旧请求是否完成都可以调用`cancel()`保证取消即可
-> 详细的关于取消网络请求的操作查看: [取消请求](cancel.md)
-> 可以限制部分重复请求一定时间内读取缓存: [缓存有效期](/cache/#_3)
\ No newline at end of file
+1. [取消请求](cancel.md)
+2. 限制时间强制使用缓存, [配置缓存有效期](cache.md#_3)
\ No newline at end of file
diff --git a/docs/request.md b/docs/request.md
index 1577fafbb..478767757 100644
--- a/docs/request.md
+++ b/docs/request.md
@@ -1,73 +1,44 @@
-Net中关于请求的类只有两个类和他们共同的抽象父类
-```kotlin
-BaseRequest
- |- UrlRequest
- |- BodyRequest
-```
-
-
-根据请求方法不同使用的Request也不同
+!!! question "请求参数"
+ 根据请求方式不同请求参数分为两类
-```kotlin
-GET, HEAD, OPTIONS, TRACE, // Url request
-POST, DELETE, PUT, PATCH // Body request
-```
+ UrlRequest: GET, HEAD, OPTIONS, TRACE // Query(请求参数位于Url中)
+ BodyRequest: POST, DELETE, PUT, PATCH // Body(请求体为流)
-代码示例
+使用示例
```kotlin
scopeNetLife {
- Get("api") {
- // this 即为 UrlRequest
- }.await()
-
- Post("api") {
- // this 即为 BodyRequest
+ val userInfo = Post(Api.LOGIN) {
+ param("username", "drake")
+ param("password", "6f2961eb44b12123393fff7e449e50b9de2499c6")
}.await()
}
```
-## 请求参数
-
-```kotlin
-scopeNetLife { // 创建作用域
- // 这个大括号内就属于作用域内部
- val data = Get("https://github.com/liangjingkanji/Net/"){
- param("u_name", "drake")
- param("pwd", "123456")
- }.await() // 发起GET请求并返回`String`类型数据
-}
-```
-
-|请求函数|描述|
+|函数|描述|
|-|-|
-|`param`|支持基础类型/文件/RequestBody/Part|
-|`json`|请求参数为JSONObject/JsonArray/String|
-|`setQuery/addQuery`|设置/添加Url参数, 如果当前请求为Url请求则该函数等效于`param`函数|
+|`param`| Url请求时为Query, Body请求时为表单/文件|
+|`json`|JSON字符串|
+|`setQuery/addQuery`|Url中的Query参数, 如果当为Url请求则该函数等效`param`|
|`setHeader/addHeader`|设置/添加请求头|
-如果没有添加文件/流那么就是通过BodyRequest内部的`FormBody`发起请求. 反之就是通过`MultipartBody`发起请求.
-
-> 当然你可以完全自定义Body来请求, 譬如以下的Json请求
-
+## JSON请求
-## Json请求
+这里仅演示三种参数类型上传JSON, 详细请查看方法重载
-这里提供三种创建Json请求的示例代码. 酌情选用
-
-=== "JSON键值对(推荐)"
+=== "Pair(推荐)"
```kotlin
val name = "金城武"
val age = 29
val measurements = listOf(100, 100, 100)
-
- scopeNetLife {
- tvFragment.text = Post("api") {
- // 只支持基础类型的值, 如果值为对象或者包含对象的集合/数组会导致其值为null
- json("name" to name, "age" to age, "measurements" to measurements)
- }.await()
- }
+
+ scopeNetLife {
+ tvFragment.text = Post("api") {
+ // 只支持基础类型的值, 如果值为对象或者包含对象的集合/数组会导致其值为null
+ json("name" to name, "age" to age, "measurements" to measurements)
+ }.await()
+ }
```
=== "JSONObject"
@@ -87,34 +58,34 @@ scopeNetLife { // 创建作用域
}
```
-=== "自定义的body"
+=== "自定义RequestBody"
```kotlin
val name = "金城武"
val age = 29
val measurements = listOf(100, 100, 100)
-
+
scopeNetLife {
tvFragment.text = Post("api") {
- body = MyJsonBody(name, age, measurements)
+ body = CustomizerJSONBody(name, age, measurements)
}.await()
}
```
-对于某些可能JSON请求参数存在固定值:
+个别项目JSON中存在固定值, 开发者不想每次都写一遍:
-1. 可以考虑继承RequestBody来扩展出自己的新的Body对象, 然后赋值给`body`字段
-2. 添加请求拦截器[RequestInterceptor](/interceptor/#_1)
+1. 实现RequestBody默认添加参数
+2. 使用请求拦截器来添加全局参数 [RequestInterceptor](/interceptor/#_1)
-## 自定义请求函数
+## 自定义扩展函数
-前面提到`json(Pair)`函数不支持对象值, 因为框架内部使用的`org.json.JSONObject`其不支持映射对象字段
+前面提到`json()`不能传对象, 因为内部使用`org.json.JSONObject`不支持映射对象字段
-这里可以创建扩展函数来支持你想要的Json解析框架, 比如以下常用的Json解析框架示例
+那可以自己创建扩展函数来使用支持解析对象的序列化框架, 如下
=== "Gson"
```kotlin
fun BodyRequest.gson(vararg body: Pair) {
- this.body = Gson().toJson(body.toMap()).toRequestBody(MediaConst.JSON)
+ this.body = Gson().toJson(body.toMap()).toRequestBody(MediaConst.JSON)
}
```
=== "FastJson"
@@ -135,23 +106,25 @@ scopeNetLife {
}
```
-- 举一反三可以创建其他功能自定义的请求函数
-- 扩展函数要求为顶层函数, 即直接在文件中 (kotlin基础语法)
-
## 全局请求参数
-对于动态生成的全局请求头或参数都可以通过实现`RequestInterceptor`来设置全局的请求拦截器来添加, 如果RequestInterceptor不满足你的需求可以使用拦截器(Interceptor)来实现
+使用`RequestInterceptor`请求拦截器添加全局参数/请求头, 如果不满足需求可以使用更复杂的`Interceptor`
```kotlin
-NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
- // 添加请求拦截器, 每次请求都会触发的, 可配置全局/动态参数
- setRequestInterceptor(MyRequestInterceptor())
+class GlobalHeaderInterceptor : RequestInterceptor {
+
+ /** 本方法每次请求发起都会调用, 这里添加的参数可以是动态参数 */
+ override fun interceptor(request: BaseRequest) {
+ request.setHeader("client", "Android")
+ request.setHeader("token", UserConfig.token)
+ }
}
```
-## 请求函数
-
-关于全部的请求配置选项推荐阅读函数文档或者阅读源码. Net提供清晰的函数结构浏览方便直接阅读源码
-
-
+```kotlin
+NetConfig.initialize(Api.HOST, this) {
+ setRequestInterceptor(GlobalHeaderInterceptor())
+}
+```
+更多请求参数相关请阅读Api文档/函数列表
\ No newline at end of file
diff --git a/docs/scope.md b/docs/scope.md
index 85d631e39..6dc1b3a39 100644
--- a/docs/scope.md
+++ b/docs/scope.md
@@ -1,28 +1,26 @@
-协程请求要求在协程的作用域中调用, 这里介绍如何创建不同的作用域获取不同的功能
+创建不同协程作用域可以实现不同的功能
-本质上Net的请求动作函数返回的是一个Deferred对象. 可以在任何协程作用域内执行. 但是考虑到完整的生命周期和错误处理等推荐使用Net内部定义的作用域.
-
-> 发生在Net作用域内的任何异常都会被捕获, 有效减少应用崩溃率. 如果配合[kotlin-serialization](kotlin-serialization.md)还可以解决因服务器返回null字段导致的崩溃
+!!! Success "减少崩溃"
+ Net所有作用域内抛出异常都会被捕获到, 可以防止应用崩溃
## 异步任务的作用域
-创建可以捕捉异常的协程作用域, 但是不会触发`NetErrorHandler`(全局错误处理者). 该作用域于一般用于普通的异步任务
+可以捕捉异常的协程作用域, 用于构建普通异步任务
|函数|描述|
|-|-|
-|`scope`|创建最基础的作用域, 所有作用域都包含异常捕捉|
-|`scopeLife`|创建跟随生命周期取消的作用域|
+|`scope`|创建最基础的作用域|
+|`scopeLife`|创建跟随生命周期自动取消的作用域|
|`ViewModel.scopeLife`|创建跟随ViewModel生命周期的作用域, [如何在ViewModel创建作用域](view-model.md)|
## 网络请求的作用域
-网络请求的作用域可以根据生命周期自动取消网络请求, 发生错误也会自动弹出吐司(可以自定义或者取消), 并且具备一些场景的特殊功能(例如加载对话框, 缺省页, 下拉刷新等)
-
-网络请求的作用域比上面提到的异步任务的作用域多的区别就是
+除异步任务外还适用于网络请求场景的作用域, 对比上面`异步任务的作用域`区别:
-1. 发生错误会触发全局错误处理`NetErrorHandler`
-2. 具备一些特殊场景功能, 比如自动下拉刷新, 自动显示加载库等
+1. 发生错误自动吐司(可以自定义或者取消)
+2. 发生错误会触发全局错误处理`NetErrorHandler`
+3. 具备一些特殊场景功能, 比如根据网络请求结果自动处理下拉刷新/上拉加载/缺省页/加载框的状态
| 函数 | 描述 |
|-|-|
@@ -33,23 +31,25 @@
|`PageRefreshLayout.scope`|创建跟随[PageRefreshLayout](https://github.com/liangjingkanji/BRV)生命周期的作用域|
|`StateLayout.scope`|创建跟随[StateLayout](https://github.com/liangjingkanji/BRV)生命周期的作用域|
-
-> PageRefreshLayout/StateLayout 属于[BRV](https://github.com/liangjingkanji/BRV)框架中的布局, 用于支持[自动化缺省页/下拉刷新](auto-state.md)
-
+!!! Failure "区分函数接受者"
+ 注意`StateLayout.scope`等存在`函数接受者`的方法和`scope`属于两个方法, 严禁混用
+!!! quote "第三方库支持"
+ PageRefreshLayout/StateLayout 属于第三方开源项目 [BRV](https://github.com/liangjingkanji/BRV)
+ 框架中的布局, 可用于支持[自动化缺省页/下拉刷新](auto-state.md)
-> 如果想了解详细的协程使用方式, 可以查看一篇文章: [最全面的Kotlin协程: Coroutine/Channel/Flow 以及实际应用](https://juejin.im/post/6844904037586829320)
+如果想更了解协程使用方式,
+可以阅读一篇文章: [最全面的Kotlin协程: Coroutine/Channel/Flow 以及实际应用](https://juejin.im/post/6844904037586829320)
-有时候可能面临嵌套的`scope*`函数或者作用域内有子作用域情况, 这个时候的生命周期是如何
+## 嵌套作用域
-
-## 嵌套Scope
+有时候可能面临内嵌`scopeXX`函数(嵌套作用域), 这时候生命周期如下
```kotlin hl_lines="5"
-scopeNet {
+scopeNetLife {
val task = Post("api0").await()
- scopeNet {
+ scopeNetLife {
val task = Post("api0").await() // 此时发生请求错误
}.catch {
// A
@@ -59,9 +59,9 @@ scopeNet {
}
```
-- 以下嵌套作用域错误将会仅发生在`A`处, 并被捕获, 同时不影响外部`scopeNet`的请求和异常捕获
-- 两个`scopeNet`的异常抛出和捕获互不影响
-- `scopeNet/scopeDialog/scope`等函数同理
+- 错误将在`A`处可以获取到, 且不影响外部`scopeNetLife`的请求
+- 两个`scopeNetLife`的异常抛出和捕获互不影响
+- `scopeXX()`等函数同理
## 子作用域
diff --git a/docs/switch-thread.md b/docs/switch-thread.md
deleted file mode 100644
index 8a223c5e5..000000000
--- a/docs/switch-thread.md
+++ /dev/null
@@ -1,50 +0,0 @@
-所有`scope*`前缀函数的创建的作用域都默认情况下为主线程, 即可以在作用域内直接操作UI
-
-既然是默认当然也可以直接修改scope内的作用域线程也可以在里面进行多次切换
-
-> 在协程中切换线程只需要切换调度器即可
-
-## 切换作用域调度器
-
-```kotlin
-scopeNetLife(dispatcher = Dispatchers.IO) {
- binding.tvFragment.text = Get("api").await()
-}
-```
-
-## 在作用域内部切换
-
-可能某些情况只是作用域内部分阻塞任务需要在其他线程执行. 我们可以直接在作用域内部进行多次的线程切换
-
-=== "主线程作用域内切换子线程"
- ```kotlin hl_lines="2"
- scopeNetLife {
- binding.tvFragment.text = withIO {
- // 假设此处是一个IO读写阻塞任务
- return "读出结果"
- }
- }
- ```
-
-=== "子线程作用域内切换主线程"
- ```kotlin hl_lines="2"
- scopeNetLife(dispatcher = Dispatchers.IO) {
- binding.tvFragment.text = withMain {
- // 假设此处是一个IO读写阻塞任务
- return "读出结果"
- }
- }
- ```
-
-|函数|描述|
-|-|-|
-|[withMain](api/-net/com.drake.net.utils/with-main.html)|切换到主线程|
-|[withIO](api/-net/com.drake.net.utils/with-i-o.html)|切换到IO线程|
-|[withDefault](api/-net/com.drake.net.utils/with-default.html)|切换到默认线程(属于子线程)|
-|[withUnconfined](api/-net/com.drake.net.utils/with-unconfined.html)|切换到无限制调度器, 其取决于上一个执行的线程切换|
-|launch|无返回值的协程挂起函数, 可指定线程|
-|async|有返回值的协程挂起函数, 但得通过`await()`返回值. 可指定线程|
-|[runMain](api/-net/com.drake.net.utils/with-unconfined.html)|切换到主线程, 该函数可以在任何地方调用不限于协程作用域|
-
-- `with*`函数属于调用就立即执行, 在作用域内会阻塞(不会阻塞主线程)
-- `launch/async` 属于执行并发任务, 两者区分就是有无返回值
diff --git a/docs/sync-request.md b/docs/sync-request.md
index 569781cd1..6dcfd61e6 100644
--- a/docs/sync-request.md
+++ b/docs/sync-request.md
@@ -1,8 +1,13 @@
-Net支持在当前线程执行, 会阻塞当前线程的同步请求 -- `execute`
+Net支持在当前线程执行阻塞线程的同步请求
-这里介绍的是不使用协程的同步请求. 由于Android主线程不允许发起网络请求, 这里我们得随便创建一个子线程才可以开发起同步请求
+!!! question "什么是同步请求"
+ 即上个请求结束才会发起下个请求, 实际上协程也可以实现但是他不会阻塞线程
-=== "同步请求"
+ 同步请求应用场景一般是在拦截器(执行在子线程)中使用
+
+因为Android主线程不允许发起网络请求, 这里我们创建一个子线程来演示
+
+=== "返回数据"
```kotlin
thread {
@@ -12,31 +17,22 @@ Net支持在当前线程执行, 会阻塞当前线程的同步请求 -- `execute
}
}
```
-=== "toResult"
+
+=== "返回Result"
```kotlin
thread {
- val result = Net.post("api").toResult().getOrDefault("请求发生错误, 我这是默认值")
+ val result = Net.post("api").toResult().getOrDefault("请求发生错误, 我是默认值")
tvFragment?.post {
tvFragment?.text = result // view要求在主线程更新
}
}
```
-1. `execute`在请求发生错误时会抛出异常
-2. `toResult`不会抛出异常, 通过`exception*`函数来获取异常信息, 且支持默认值等特性
+1. `execute`在请求错误时会直接抛出异常
+2. `toResult`不会抛出异常, 可`getOrThrow/exceptionOrNull`等返回异常对象
+
+
-> 同步请求应用场景一般是在拦截器中使用, 拦截器默认是子线程
-作用域具体介绍可以看[创建作用域](scope.md)
-|请求函数|描述|
-|-|-|
-|Net.get|标准Http请求方法|
-|Net.post|标准Http请求方法|
-|Net.head|标准Http请求方法|
-|Net.options|标准Http请求方法|
-|Net.trace|标准Http请求方法|
-|Net.delete|标准Http请求方法|
-|Net.put|标准Http请求方法|
-|Net.patch|标准Http请求方法|
diff --git a/docs/tag.md b/docs/tag.md
index 4a0866287..fa4bfe84a 100644
--- a/docs/tag.md
+++ b/docs/tag.md
@@ -1,9 +1,9 @@
-Net支持两种类型数据贯穿整个请求流程(请求 -> 拦截器 -> 转换器)
+Net支持两种方式携带数据, 贯穿整个请求流程(请求 -> 拦截器 -> 转换器)
- tag: `HashMap, Any?>` 标签
- extra: `HashMap` 额外数据
-> 他们的区别是key是Class还是String类型, 具体使用哪一种请根据自己方便来
+区别为key是`Class`还是`String`, 自由选择
## 标签使用
@@ -18,8 +18,10 @@ scopeNetLife {
}
```
-> `tagOf(Person())` 等效 `tag(Person::class.java, Person())`, 只是使用泛型推断区别
-> 但`tag(Person())` 等效 `tag(Any::class.java, Person())`, 可以查看方法实现
+!!! warning "泛型"
+ `tagOf(Person())` 等于 `tag(Person::class.java, Person())`, 使用泛型推断
+
+ 但`tag(Person())` 等于 `tag(Any::class.java, Person())`, 为OkHttp自带方法
### 2) 拦截器中读取标签
```kotlin hl_lines="4"
@@ -52,7 +54,7 @@ class MyConvert : NetConvert {
-我们通过Request的函数可以读取/写入标签/额外数据
+通过`Request`可以读写数据
| 方法 | 描述 |
|-|-|
diff --git a/docs/thread.md b/docs/thread.md
new file mode 100644
index 000000000..eaf79fcb1
--- /dev/null
+++ b/docs/thread.md
@@ -0,0 +1,49 @@
+所有`scopeXX`作用域内为主线程, 可直接更新视图
+
+!!! question "调度器"
+ 协程中的调度器实际上为线程池, 通过切换调度器可以切换到不同线程上
+
+## 切换调度器
+
+```kotlin
+scopeNetLife(dispatcher = Dispatchers.IO) {
+ binding.tvFragment.text = Get("api").await()
+}
+```
+
+## 作用域内部切换
+
+有时需开启新的线程处理耗时任务
+
+=== "主线程作用域内切换子线程"
+ ```kotlin hl_lines="2"
+ scopeNetLife {
+ binding.tvFragment.text = withIO {
+ // 假设此处是一个IO读写阻塞任务
+ return "读出结果"
+ }
+ }
+ ```
+
+=== "子线程作用域内切换主线程"
+ ```kotlin hl_lines="2"
+ scopeNetLife(dispatcher = Dispatchers.IO) {
+ binding.tvFragment.text = withMain {
+ // 假设此处是一个IO读写阻塞任务
+ return "读出结果"
+ }
+ }
+ ```
+
+| 函数 | 描述 |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| [withMain](api/-net/com.drake.net.utils/with-main.html) | 切换到主线程 |
+| [withIO](api/-net/com.drake.net.utils/with-i-o.html) | 切换到IO线程 |
+| [withDefault](api/-net/com.drake.net.utils/with-default.html) | 切换到子线程 |
+| [withUnconfined](api/-net/com.drake.net.utils/with-unconfined.html) | 切换到无限制调度器, 其取决于上一个执行的线程切换 |
+| launch | 无返回值的挂起函数, 可指定线程 |
+| async | 有返回值的挂起函数, 通过`await()`返回值, 可指定线程 |
+| [runMain](api/-net/com.drake.net.utils/with-unconfined.html) | 切换到主线程, 该函数不属于协程可以在任何地方调用 |
+
+- `withXX()` 协程阻塞挂起
+- `launch()/async()` 非阻塞执行, 两者区别是有无返回值
diff --git a/docs/timing.md b/docs/timing.md
index bfb0f0b28..d33bfd4a3 100644
--- a/docs/timing.md
+++ b/docs/timing.md
@@ -1,8 +1,10 @@
-以下仅提供一些如何实现定时/限时请求功能的思路, 并不限定只有以下描述的方式可以实现
+以下为提供实现定时/限时请求思路, 并不限定只有以下方式
## 限时请求
+即超过指定时间后立即取消请求
+
```kotlin
scopeDialog {
// 当接口请求在100毫秒内没有完成会抛出异常TimeoutCancellationException
@@ -41,7 +43,6 @@ scopeNetLife {
```kotlin
scopeNetLife {
- // 每两秒请求一次, 总共执行10次
while (true) {
delay(1.toDuration(DurationUnit.SECONDS))
val data =
diff --git a/docs/track.md b/docs/track.md
new file mode 100644
index 000000000..15ff2d3e5
--- /dev/null
+++ b/docs/track.md
@@ -0,0 +1,24 @@
+Net中网络请求异常会LogCat输出, 除非开发者修改全局错误处理
+
+
+演示访问一个不存在的请求路径
+```kotlin
+scopeNetLife {
+ tvFragment.text = Get("https://githuberror.com/liangjingkanji/Net/").await()
+}
+```
+
+LogCat可以看到异常堆栈信息, 包含具体Url和代码位置
+
+
+
+
+### 关闭日志
+
+可以关闭日志打印
+
+```kotlin
+NetConfig.initialize(Api.HOST, this) {
+ setDebug(false) // 关闭日志, 一般使用 BuildConfig.DEBUG
+}
+```
diff --git a/docs/updates.md b/docs/updates.md
index 009156d46..ad79871f2 100644
--- a/docs/updates.md
+++ b/docs/updates.md
@@ -241,7 +241,7 @@
- 修复未知的TypeToken访问权限问题
## 3.0.6
-- 所有Json解析框架都可以解析`List`等嵌套泛型数据结构: [特殊结构解析](convert-special.md)
+- 所有Json解析框架都可以解析`List`等嵌套泛型数据结构
## 3.0.5
- 修复Path编码问题
diff --git a/docs/upload-file.md b/docs/upload-file.md
index 95f6665a5..9d0b2d19a 100644
--- a/docs/upload-file.md
+++ b/docs/upload-file.md
@@ -1,5 +1,3 @@
-上传文件和普通接口请求区别不大
-
```kotlin
scopeNetLife {
Post(Api.UPLOAD) {
@@ -8,11 +6,11 @@ scopeNetLife {
}
```
-使用`addUploadListener`添加上传进度监听器, 监听上传进度具体介绍在[进度监听](progress.md)中
+使用`addUploadListener`添加上传进度监听器, 介绍在[进度监听](progress.md)中
## 指定类型
-默认会根据文件的后缀名产生MediaType. 但是如果你想自定义MediaType可以直接创建RequestBody参数
+默认会根据文件的后缀名产生MediaType, 如果像自定义MediaType可以直接创建RequestBody
```kotlin
scopeNetLife {
diff --git a/docs/view-model.md b/docs/view-model.md
index 0a26d8c37..8477991ea 100644
--- a/docs/view-model.md
+++ b/docs/view-model.md
@@ -1,30 +1,44 @@
-Net支持在ViewModel中创建网络请求/异步任务, 并且在ViewModel被销毁时自动取消
+Net支持在ViewModel中创建网络请求/异步任务
+!!! Warning "不推荐"
+ 1. 网络请求不一定要写在ViewModel
+ 2. 网络请求不要写接口回调
+ 3. 可以在Activity中直接返回请求结果
-## 使用
-和一般网络请求没有区别, 在ViewModel中使用函数`scopeLife/scopeNetLife`这两个函数创建作用域即可, 具体介绍看[作用域](scope.md)
+## 自动生命周期
+
+- [示例代码](https://github.com/liangjingkanji/Net/blob/c4d7c4cde6a34b9fa97a75cb357276b75432f8d1/sample/src/main/java/com/drake/net/sample/ui/fragment/ViewModelRequestFragment.kt)
+
+使用`scopeXXLife()`创建作用域, 在ViewModel被销毁时自动取消请求
```kotlin
class UserViewModel : ViewModel() {
// 用户信息
- var userInfo: MutableLiveData = MutableLiveData()
+ private var userInfo: MutableLiveData = MutableLiveData()
/**
- * 拉取用户信息, 会自动通知页面更新, 同时页面销毁会自动取消网络请求
+ * 使用LiveData接受请求结果, 将该liveData直接使用DataBinding绑定到页面上, 会在请求成功自动更新视图
*/
fun fetchUserInfo() = scopeNetLife {
- userInfo.value = Get("api").await()
+ userInfo.value = Get(Api.GAME).await()
}
-}
-```
-
-1. 不建议使用LiveData实现MVVM. 应当使用DataBinding. 但LiveData像ObservableField一样使用
-1. 简单地业务直接在Activity/Fragment中进行请求会更加方便
-1. ViewModel这个类本质是属于防止数据意外销毁或者桥接VM, 但不是每个页面都有这种需求
+ /**
+ * 开始非阻塞异步任务
+ * 返回Deferred, 调用await()才会返回结果
+ */
+ fun fetchList(scope: CoroutineScope) = scope.Get(Api.TEST)
-
+ /**
+ * 开始阻塞异步任务
+ * 直接返回结果
+ */
+ suspend fun fetchPrecessData() = coroutineScope {
+ val response = Get(Api.TEST).await()
+ response + "处理数据"
+ }
+}
+```
-
diff --git a/mkdocs.yml b/mkdocs.yml
index 6cdb21437..f7a29bf4a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,37 +1,76 @@
site_name: Net
-site_author: drake
site_description: Net document
-copyright: Copyright © 2018 - 2020 劉強東
-
-repo_name: GitHub
repo_url: https://github.com/liangjingkanji/Net
+site_author: 劉強東
+copyright: Copyright © 2018 - 2020 劉強東
+repo_name: GitHub
+docs_dir: 'docs'
+extra:
+ social:
+ - icon: fontawesome/brands/github
+ link: https://github.com/liangjingkanji
+ - icon: fontawesome/brands/qq
+ link: https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/img/group-qrcode.png
+ - icon: fontawesome/brands/twitch
+ link: https://github.com/liangjingkanji/Net/discussions
extra_css:
- css/extra.css
-
-docs_dir: docs
-
theme:
name: material
custom_dir: docs/material
+ favicon: img/book-open.svg
+ logo: img/book-open.svg
palette:
- scheme: drake
- primary: white
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
+ primary: white
font: false
- language: 'zh'
+ language: zh
features:
+ - navigation.top
+ - navigation.prune
+ - navigation.footer
+ - navigation.instant
- search.highlight
-
+ - search.suggest
+ - search.share
+ - content.code.copy
+ - content.code.annotate
+plugins:
+ - offline
+ - search:
+ separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
+ lang:
+ - en
+ - zh
markdown_extensions:
- 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
+ - pymdownx.caret
+ - pymdownx.keys
+ - pymdownx.mark
+ - pymdownx.tilde
+ - pymdownx.emoji:
+ emoji_index: !!python/name:materialx.emoji.twemoji
+ emoji_generator: !!python/name:materialx.emoji.to_svg
nav:
- 使用: index.md
@@ -41,25 +80,25 @@ nav:
- 请求参数: request.md
- 全局配置: config.md
- 请求结果:
- - 默认结果: default-response.md
- - 自定义转换器: converter.md
- - 自定义结构解析: convert-special.md
+ - 转换器: converter.md
+ - 自定义转换器: converter-customize.md
+ - 自定义结构解析: converter-struct.md
- Kotlin-Serialization: kotlin-serialization.md
- 数据类生成插件: model-generate.md
- 自动化:
- 自动加载框: auto-dialog.md
- 自动缺省页: auto-state.md
- 自动下拉刷新: auto-refresh.md
- - 自动分页加载: auto-page.md
- - 切换线程: switch-thread.md
+ - 自动分页加载: auto-pull.md
+ - 切换线程: thread.md
- ViewModel: view-model.md
- - 异常追踪: exception-track.md
+ - 异常追踪: track.md
- 错误处理:
- - 默认错误处理: error-default.md
- - 单例错误捕获: error-single.md
- - 全局错误捕获: error-global.md
+ - 错误处理: error.md
+ - 单例捕获: error-single.md
+ - 全局捕获: error-global.md
- 自定义错误提示: error-tip.md
- - 自定义异常抛出: error-exception.md
+ - 自定义异常抛出: error-throws.md
- OkHttpClient: okhttp-client.md
- 拦截器: interceptor.md
- Https证书: https.md
@@ -71,7 +110,7 @@ nav:
- 进度监听: progress.md
- 取消请求: cancel.md
- 重复请求: repeat-request.md
- - 自动搜索: debounce.md
+ - 搜索节流: debounce.md
- 最快请求结果: fastest.md
- 日志插件: log-recorder.md
- 通知栏日志: log-notice.md
@@ -79,7 +118,6 @@ nav:
- Callback: callback.md
- 轮询器/倒计时: interval.md
- 社区讨论: https://github.com/liangjingkanji/Net/discussions
- - 常见问题: https://github.com/liangjingkanji/Net/blob/master/docs/issues.md
- - 项目实践: practice.md
+ - 常见问题: issues.md
- 更新日志: updates.md
- 3.x文档: api/index.html
diff --git a/sample/proguard-rules.pro b/sample/proguard-rules.pro
index bc5d812e1..481bb4348 100644
--- a/sample/proguard-rules.pro
+++ b/sample/proguard-rules.pro
@@ -1,5 +1,5 @@
# Add project specific ProGuard rules here.
-# You can control the setKalle of applied configuration files using the
+# You can control the set of applied configuration files using the
# proguardFiles setting in build.gradle.
#
# For more details, see
diff --git a/sample/src/main/java/com/drake/net/sample/vm/UserViewModel.kt b/sample/src/main/java/com/drake/net/sample/vm/UserViewModel.kt
index aa51e4254..2372f561f 100644
--- a/sample/src/main/java/com/drake/net/sample/vm/UserViewModel.kt
+++ b/sample/src/main/java/com/drake/net/sample/vm/UserViewModel.kt
@@ -10,37 +10,28 @@ import kotlinx.coroutines.coroutineScope
/**
- * 强烈建议不要封装作用域, 封装异步任务即可, 作用域灵活随用随写(Activity/Fragment都可以写作用域)
- *
- * 不要企图把所有逻辑代码都写在ViewModel中就觉得自己会写MVVM了, 给代码换个位置不叫架构设计, 特别是还增加一堆无效代码情况下
+ * 不要将请求结果抛来抛去, 增加代码复杂度
*/
class UserViewModel : ViewModel() {
// 用户信息
var userInfo: MutableLiveData = MutableLiveData()
- var updateTime: Long = 0
-
/**
- * 拉取用户信息, 只能监听返回结果, 仅当外部调用对象不在乎返回结果时使用
- * 会自动通知页面更新: 因为使用LiveData将请求结果回调出去, 建议将该liveData对象直接使用DataBinding绑定到页面上, 就会自动触发UI
- * 同时页面销毁会自动取消网络请求: 因为他使用`scopeNetLife`. 生命周期跟随当前viewModel
- *
- * 本质上我并不推荐将Scope定义在ViewModel中(仅仅换个位置要多写很多代码), 特别是妄图在ViewModel中请求网络却要求更新UI
+ * 使用LiveData接受请求结果, 将该liveData直接使用DataBinding绑定到页面上, 会在请求成功自动更新视图
*/
fun fetchUserInfo() = scopeNetLife {
userInfo.value = Get(Api.GAME).await()
- updateTime = System.currentTimeMillis()
}
/**
- * 非阻塞异步任务
- * 返回Deferred, 调用await()才会返回结果. 调用即执行任务
+ * 开始非阻塞异步任务
+ * 返回Deferred, 调用await()才会返回结果
*/
fun fetchList(scope: CoroutineScope) = scope.Get(Api.TEST)
/**
- * 阻塞异步任务
+ * 开始阻塞异步任务
* 直接返回结果
*/
suspend fun fetchPrecessData() = coroutineScope {
-
-## 指定单例加载框
+## 单例自定义
-就是仅针对当前网络请求指定加载框
+指定当前请求加载框
```kotlin
val dialog = BubbleDialog(requireActivity(), "加载中")
@@ -36,61 +36,46 @@ scopeDialog(dialog) {
-> 这里使用的iOS风格对话框: [BubbleDialog](https://liangjingkanji.github.io/Tooltip/bubble.html)
+!!! quote "菊花加载对话框"
+ 示例使用的iOS风格对话框: [BubbleDialog](https://liangjingkanji.github.io/Tooltip/bubble.html)
-## 指定全局加载框
+## 全局自定义
-在Application中配置Net时就可以设置默认的Dialog
+初始化时指定加载对话框构造器`NetDialogFactory`
-=== "初始配置全局加载框"
- ```kotlin
- NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
- setDialogFactory { // 全局加载对话框
- ProgressDialog(it).apply {
- setMessage("我是全局自定义的加载对话框...")
- }
+```kotlin
+NetConfig.initialize(Api.HOST, this) {
+ setDialogFactory {
+ ProgressDialog(it).apply {
+ setMessage("我是全局自定义的加载对话框...")
}
- }
- ```
-=== "修改全局加载框"
- ```kotlin
- NetConfig.dialogFactory = NetDialogFactory {
- ProgressDialog(it).apply {
- setMessage("我是全局自定义的加载对话框...")
}
- }
- ```
-
-
-使用固定版本号替换+符号
-
```groovy
-implementation 'com.github.liangjingkanji:BRV:+'
+implementation 'com.github.liangjingkanji:BRV:+' // 使用固定版本号替换+符号
```
-> 当然如果自己处理下拉刷新也是可以的, Net可以仅仅作为网络框架存在
+## PageRefreshLayout
-创建PageRefreshLayout
```xml
+
+## 设置转换器
+
+转换器分为全局和单例, 单例可以覆盖全局的转换器. 如果不设置转换器就会采用默认的转换器
+
+=== "全局"
+ ```kotlin hl_lines="2"
+ NetConfig.initialize(Api.HOST, this) {
+ setConverter(SerializationConverter())
+ }
+ ```
+=== "单例"
+ ```kotlin hl_lines="3"
+ scopeNetLife {
+ tvFragment.text = Get
+
+比如截图中的意为, 当返回的Json中包含state字段且值为ok时请求才算是真正成功才会返回数据, 否则都会抛出异常.
+其中message为错误信息字段名
+
+假设简单的指定名称不能满足你复杂的业务逻辑, 请复制`JSONConvert`
+源码到你项目中修改或者直接自己实现`NetConverter`
+
+> 注意解析器(Gson或者Moshi)的解析对象记得定义为类成员, 这样可以不会导致每次解析都要创建一个新的解析对象,
+> 减少内存消耗
+
+ Net.debug(e)
+ TipUtils.toast(message)
+ }
+ ```
diff --git a/docs/error.md b/docs/error.md
new file mode 100644
index 000000000..47b3e80f9
--- /dev/null
+++ b/docs/error.md
@@ -0,0 +1,25 @@
+Net有完善的错误处理机制, 具备捕获异常/取消请求/错误提示/追踪链路
+
+!!! success "收集网络日志"
+ 在Net作用域内发生的异常都会被全局错误处理捕获, 可以将其筛选上传日志
+
+