Skip to content

Commit

Permalink
doc: 更新文档注释
Browse files Browse the repository at this point in the history
  • Loading branch information
@liangjingkanji
liangjingkanji committed Jul 31, 2023
1 parent 4636fe9 commit 72a8ee1
Show file tree
Hide file tree
Showing 6 changed files with 71 additions and 49 deletions.
9 changes: 4 additions & 5 deletions docs/cancel.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,8 @@ Net.cancelId("请求用户信息")
Net.cancelGroup("请求分组名称") // 设置分组
```

如果你要问我请求的Group和Id有什么区别, 其实本质上两者基本上没区别, 只是为了适配不同场景下使用.
Group和Id在使用场景上有所区别, 预期上Group允许重复赋值给多个请求, Id仅允许赋值给一个请求, 但实际上都允许重复赋值 <br>
在作用域中发起请求时会默认使用协程错误处理器作为Group: `setGroup(coroutineContext[CoroutineExceptionHandler])` <br>
如果你覆盖Group会导致协程结束不会自动取消请求

<br>

> 需要注意的是一旦为网络请求设置分组`setGroup`你就无法在作用域执行完毕自动取消网络请求了, 因为自动取消的原理就是使用作用域
的上下文来作为Group
<br>
4 changes: 2 additions & 2 deletions docs/download-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ scopeNetLife {
|-|-|
| setDownloadFileName | 下载的文件名称 |
| setDownloadDir | 下载保存的目录, 也支持包含文件名称的完整路径, 如果使用完整路径则无视`setDownloadFileName`设置 |
| setDownloadMd5Verify | 下载是否开启MD5校验, 如果服务器返回 "Content-MD5"响应头和制定路径已经存在的文件MD5相同是否直接返回File, 不会重新下载 |
| setDownloadFileNameConflict | 下载文件名如果在指定路径下存在同名会自动重新命名, 例如`file_name(1).apk` |
| setDownloadMd5Verify | 下载文件MD5校验, 如果服务器响应头`Content-MD5`值和指定路径已经存在的文件MD5相同, 则跳过下载直接返回该File |
| setDownloadFileNameConflict | 下载文件路径存在同名文件时是创建新文件(添加序号)还是覆盖, 例如`file_name(1).apk` |
| setDownloadFileNameDecode | 文件名称是否使用URL解码, 例如下载的文件名如果是中文, 服务器传输给你的会是被URL编码的字符串. 你使用URL解码后才是可读的中文名称 |
| setDownloadTempFile | 下载是否使用临时文件, 避免下载失败后覆盖同名文件或者无法判别是否已下载完整, 仅在下载完整以后才会显示为原有文件名 |
| addDownloadListener | 下载进度监听器, 具体介绍在[进度监听](progress.md)中 |
Expand Down
3 changes: 2 additions & 1 deletion net/src/main/java/com/drake/net/interceptor/RetryInterceptor.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ import okhttp3.internal.closeQuietly

/**
* 重试次数拦截器
*
* OkHttp自带重试请求规则, 本拦截器并不推荐使用
* 因为长时间阻塞用户请求是不合理的, 发生错误请让用户主动重试, 例如显示缺省页或者提示
* @property retryCount 重试次数
*/
class RetryInterceptor(@IntRange(from = 1) var retryCount: Int = 3) : Interceptor {
Expand Down
43 changes: 25 additions & 18 deletions net/src/main/java/com/drake/net/request/BaseRequest.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ import com.drake.net.reflect.TypeToken
import com.drake.net.reflect.typeTokenOf
import com.drake.net.response.convert
import com.drake.net.tag.NetTag
import kotlinx.coroutines.CoroutineExceptionHandler
import okhttp3.*
import okhttp3.HttpUrl.Companion.toHttpUrl
import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
Expand Down Expand Up @@ -79,14 +80,20 @@ abstract class BaseRequest {

//<editor-fold desc="ID">
/**
* 唯一的Id
* 请求ID
* Group和Id在使用场景上有所区别, 预期上Group允许重复赋值给多个请求, Id仅允许赋值给一个请求, 但实际上都允许重复赋值
* 在作用域中发起请求时会默认使用协程错误处理器作为Group: `setGroup(coroutineContext[CoroutineExceptionHandler])`
* 如果你覆盖Group会导致协程结束不会自动取消请求
*/
fun setId(id: Any?) {
okHttpRequest.id = id
}

/**
* 分组
* 请求分组
* Group和Id在使用场景上有所区别, 预期上Group允许重复赋值给多个请求, Id仅允许赋值给一个请求, 但实际上都允许重复赋值
* 在作用域中发起请求时会默认使用协程错误处理器作为Group: `setGroup(coroutineContext[CoroutineExceptionHandler])`
* 如果你覆盖Group会导致协程结束不会自动取消请求
*/
fun setGroup(group: Any?) {
okHttpRequest.group = group
Expand Down Expand Up @@ -234,11 +241,9 @@ abstract class BaseRequest {

//<editor-fold desc="Extra">
/**
* 添加标签
* 使用`Request.tag(name)`得到指定标签
*
* @param name 标签名称
* @param tag 标签
* 设置额外信息
* @see extra 读取
* @see extras 全部额外信息
*/
fun setExtra(name: String, tag: Any?) {
okHttpRequest.setExtra(name, tag)
Expand All @@ -250,23 +255,23 @@ abstract class BaseRequest {

/**
* 使用Any::class作为键名添加标签
* 使用Request.tag()返回标签
* 使用Request.tag()返回tag
*/
fun tag(tag: Any?) {
okHttpRequest.tag(tag)
}

/**
* 使用[type]作为键名添加标签
* 使用Request.label<T>()或者Request.tag(type)返回标签
* 使用[type]作为key添加标签
* 使用Request.tagOf<T>()或者Request.tag(Class)读取tag
*/
fun <T> tag(type: Class<in T>, tag: T?) {
okHttpRequest.tag(type, tag)
}

/**
* 使用[T]作为键名添加标签
* 使用Request.label<T>()或者Request.tag(type)返回标签
* 添加tag
* 使用Request.tagOf<T>()或者Request.tag(Class)读取tag
*/
inline fun <reified T> tagOf(tag: T?) {
okHttpRequest.tagOf(tag)
Expand Down Expand Up @@ -381,14 +386,16 @@ abstract class BaseRequest {
}

/**
* 如果服务器返回 "Content-MD5"响应头和制定路径已经存在的文件MD5相同是否直接返回File
* 下载文件MD5校验
* 如果服务器响应头`Content-MD5`值和指定路径已经存在的文件MD5相同, 则跳过下载直接返回该File
*/
fun setDownloadMd5Verify(enabled: Boolean = true) {
okHttpRequest.tagOf(NetTag.DownloadFileMD5Verify(enabled))
}

/**
* 假设下载文件路径已存在同名文件是否重命名, 例如`file_name(1).apk`
* 下载文件路径存在同名文件时是创建新文件(添加序号)还是覆盖
* 重命名规则是: $文件名_($序号).$后缀, 例如`file_name(1).apk`
*/
fun setDownloadFileNameConflict(enabled: Boolean = true) {
okHttpRequest.tagOf(NetTag.DownloadFileConflictRename(enabled))
Expand All @@ -405,16 +412,15 @@ abstract class BaseRequest {
/**
* 下载是否使用临时文件
* 避免下载失败后覆盖同名文件或者无法判别是否已下载完整, 仅在下载完整以后才会显示为原有文件名
* 临时文件命名规则: 文件名 + .net-download
* 下载文件名: install.apk, 临时文件名: install.apk.net-download
* 临时文件命名规则: 文件名 + .downloading
* 下载文件名: install.apk, 临时文件名: install.apk.downloading
*/
fun setDownloadTempFile(enabled: Boolean = true) {
okHttpRequest.tagOf(NetTag.DownloadTempFile(enabled))
}

/**
* 下载监听器
* [setDownloadMd5Verify] 启用MD5文件校验且匹配本地文件MD5值成功会直接返回本地文件对象, 不会触发下载监听器
*/
fun addDownloadListener(progressListener: ProgressListener) {
okHttpRequest.downloadListeners().add(progressListener)
Expand All @@ -423,7 +429,8 @@ abstract class BaseRequest {
//</editor-fold>

/**
* 为请求附着针对Kotlin的Type信息
* 为请求附着KType信息
* KType属于Kotlin特有的Type, 某些Kotlin框架可能会使用到, 例如 kotlin.serialization
*/
@OptIn(ExperimentalStdlibApi::class)
inline fun <reified T> setKType() {
Expand Down
26 changes: 17 additions & 9 deletions net/src/main/java/com/drake/net/request/RequestBuilder.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ package com.drake.net.request
import com.drake.net.convert.NetConverter
import com.drake.net.interfaces.ProgressListener
import com.drake.net.tag.NetTag
import kotlinx.coroutines.CoroutineExceptionHandler
import okhttp3.Headers
import okhttp3.OkHttpUtils
import okhttp3.Request
Expand All @@ -35,7 +36,10 @@ import kotlin.reflect.KType

//<editor-fold desc="Group">
/**
* 请求的Id
* 请求Id
* Group和Id在使用场景上有所区别, 预期上Group允许重复赋值给多个请求, Id仅允许赋值给一个请求, 但实际上都允许重复赋值
* 在作用域中发起请求时会默认使用协程错误处理器作为Group: `setGroup(coroutineContext[CoroutineExceptionHandler])`
* 如果你覆盖Group会导致协程结束不会自动取消请求
*/
var Request.Builder.id: Any?
get() = tagOf<NetTag.RequestId>()?.value
Expand All @@ -44,9 +48,10 @@ var Request.Builder.id: Any?
}

/**
* 请求的分组名
* Group和Id本质上都是任意对象Any. 但是Net网络请求中自动取消的操作都是通过Group分组. 如果你覆盖可能会导致自动取消无效
* 在设计理念上分组可以重复. Id不行
* 请求分组
* Group和Id在使用场景上有所区别, 预期上Group允许重复赋值给多个请求, Id仅允许赋值给一个请求, 但实际上都允许重复赋值
* 在作用域中发起请求时会默认使用协程错误处理器作为Group: `setGroup(coroutineContext[CoroutineExceptionHandler])`
* 如果你覆盖Group会导致协程结束不会自动取消请求
*/
var Request.Builder.group: Any?
get() = tagOf<NetTag.RequestGroup>()?.value
Expand All @@ -56,7 +61,8 @@ var Request.Builder.group: Any?
//</editor-fold>

/**
* KType属于Kotlin特有的Type, 某些kotlin独占框架可能会使用到. 例如 kotlin.serialization
* 为请求附着KType信息
* KType属于Kotlin特有的Type, 某些Kotlin框架可能会使用到, 例如 kotlin.serialization
*/
var Request.Builder.kType: KType?
get() = tagOf<NetTag.RequestKType>()?.value
Expand All @@ -74,7 +80,9 @@ fun Request.Builder.headers(): Headers.Builder {

//<editor-fold desc="Extra">
/**
* 设置键值对的tag
* 设置额外信息
* @see extra 读取
* @see extras 全部额外信息
*/
fun Request.Builder.setExtra(name: String, value: Any?) = apply {
val extras = extras()
Expand All @@ -86,7 +94,7 @@ fun Request.Builder.setExtra(name: String, value: Any?) = apply {
}

/**
* 全部键值对标签
* 全部额外信息
*/
fun Request.Builder.extras(): HashMap<String, Any?> {
return tagOf<NetTag.Extras>() ?: kotlin.run {
Expand All @@ -101,7 +109,7 @@ fun Request.Builder.extras(): HashMap<String, Any?> {
//<editor-fold desc="Tag">

/**
* 返回OkHttp的tag(通过Class区分的tag)
* 读取OkHttp的tag(通过Class区分的tag)
*/
inline fun <reified T> Request.Builder.tagOf(): T? {
return tags()[T::class.java] as? T
Expand All @@ -115,7 +123,7 @@ inline fun <reified T> Request.Builder.tagOf(value: T?) = apply {
}

/**
* 标签集合
* 全部tag
*/
fun Request.Builder.tags(): MutableMap<Class<*>, Any?> {
return OkHttpUtils.tags(this)
Expand Down
35 changes: 21 additions & 14 deletions net/src/main/java/com/drake/net/request/RequestExtension.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,18 @@ import com.drake.net.NetConfig
import com.drake.net.convert.NetConverter
import com.drake.net.interfaces.ProgressListener
import com.drake.net.tag.NetTag
import kotlinx.coroutines.CoroutineExceptionHandler
import okhttp3.OkHttpUtils
import okhttp3.Request
import java.util.concurrent.ConcurrentLinkedQueue
import kotlin.reflect.KType

//<editor-fold desc="ID">
/**
* 请求的Id
* 请求Id
* Group和Id在使用场景上有所区别, 预期上Group允许重复赋值给多个请求, Id仅允许赋值给一个请求, 但实际上都允许重复赋值
* 在作用域中发起请求时会默认使用协程错误处理器作为Group: `setGroup(coroutineContext[CoroutineExceptionHandler])`
* 如果你覆盖Group会导致协程结束不会自动取消请求
*/
var Request.id: Any?
get() = tagOf<NetTag.RequestId>()?.value
Expand All @@ -44,9 +48,10 @@ var Request.id: Any?
}

/**
* 请求的分组名
* Group和Id本质上都是任意对象Any. 但是Net网络请求中自动取消的操作都是通过Group分组. 如果你覆盖可能会导致自动取消无效
* 在设计理念上分组可以重复. Id不行
* 请求分组
* Group和Id在使用场景上有所区别, 预期上Group允许重复赋值给多个请求, Id仅允许赋值给一个请求, 但实际上都允许重复赋值
* 在作用域中发起请求时会默认使用协程错误处理器作为Group: `setGroup(coroutineContext[CoroutineExceptionHandler])`
* 如果你覆盖Group会导致协程结束不会自动取消请求
*/
var Request.group: Any?
get() = tagOf<NetTag.RequestGroup>()?.value
Expand All @@ -56,7 +61,8 @@ var Request.group: Any?
//</editor-fold>

/**
* KType属于Kotlin特有的Type, 某些kotlin独占框架可能会使用到. 例如 kotlin.serialization
* 为请求附着KType信息
* KType属于Kotlin特有的Type, 某些Kotlin框架可能会使用到, 例如 kotlin.serialization
*/
var Request.kType: KType?
get() = tagOf<NetTag.RequestKType>()?.value
Expand All @@ -67,15 +73,14 @@ var Request.kType: KType?

//<editor-fold desc="Extra">
/**
* 返回键值对的标签
* 键值对标签即OkHttp中的实际tag(在Net中叫label)中的一个Map集合
* 读取额外信息
*/
fun Request.extra(name: String): Any? {
return tagOf<NetTag.Extras>()?.get(name)
}

/**
* 全部键值对标签
* 全部额外信息
*/
fun Request.extras(): HashMap<String, Any?> {
val tags = tags()
Expand All @@ -89,7 +94,7 @@ fun Request.extras(): HashMap<String, Any?> {

//<editor-fold desc="Tag">
/**
* 返回OkHttp的tag(通过Class区分的tag)
* 读取OkHttp的tag(通过Class区分的tag)
*/
inline fun <reified T> Request.tagOf(): T? {
return tag(T::class.java)
Expand All @@ -107,7 +112,7 @@ inline fun <reified T> Request.tagOf(value: T?) = apply {
}

/**
* 标签集合
* 全部tag
*/
fun Request.tags(): MutableMap<Class<*>, Any?> {
return OkHttpUtils.tags(this)
Expand Down Expand Up @@ -142,14 +147,16 @@ fun Request.downloadListeners(): ConcurrentLinkedQueue<ProgressListener> {

//<editor-fold desc="Download">
/**
* 当指定下载目录存在同名文件是覆盖还是进行重命名, 重命名规则是: $文件名_($序号).$后缀
* 下载文件路径存在同名文件时是覆盖或创建新文件(添加序号)
* 重命名规则是: $文件名_($序号).$后缀, 例如`file_name(1).apk`
*/
fun Request.downloadConflictRename(): Boolean {
return tagOf<NetTag.DownloadFileConflictRename>()?.value == true
}

/**
* 是否进行校验文件md5, 如果校验则匹配上既马上返回文件而不会进行下载
* 下载文件MD5校验
* 如果服务器响应头`Content-MD5`值和指定路径已经存在的文件MD5相同, 则跳过下载直接返回该File
*/
fun Request.downloadMd5Verify(): Boolean {
return tagOf<NetTag.DownloadFileMD5Verify>()?.value == true
Expand Down Expand Up @@ -180,8 +187,8 @@ fun Request.downloadFileNameDecode(): Boolean {
/**
* 下载是否使用临时文件
* 避免下载失败后覆盖同名文件或者无法判别是否已下载完整, 仅在下载完整以后才会显示为原有文件名
* 临时文件命名规则: 文件名 + .net-download
* 下载文件名: install.apk, 临时文件名: install.apk.net-download
* 临时文件命名规则: 文件名 + .downloading
* 下载文件名: install.apk, 临时文件名: install.apk.downloading
*/
fun Request.downloadTempFile(): Boolean {
return tagOf<NetTag.DownloadTempFile>()?.value == true
Expand Down

0 comments on commit 72a8ee1

Please sign in to comment.