# Net Android上最强网络任务库, 创新式的网络请求库(针对[Kalle](https://github.com/yanzhenjie/Kalle)网络请求框架进行扩展), 支持协程高并发网络请求本项目为Android项目中的所有的异步任务和网络请求而生, Demo示例代码不过百行, 欢迎阅读任何框架问题加群回复: [752854893](https://jq.qq.com/?_wv=1027&k=vWsXSNBJ) The project is supported by [JetBrains](https://www.jetbrains.com/), Best IDE to developer

1.0+ 版本为RxKotlin实现 2.0+ 版本开始引入Kotlin协程特性, 开发者无需掌握协程也可以使用目前计划 - [ ] 重写使用文档 - [ ] 升级到OkHttp4.7 - [ ] 插件输出网络日志, 支持超长输出 - [ ] WebSocket路由

主要新增特性 - 协程 - 并发网络请求 - 串行网络请求 - 切换线程 - DSL编程 - 方便的缓存处理 - 自动错误信息吐司 - 自动异常捕获 - 自动日志打印异常 - 自动JSON解析 - 自动处理下拉刷新和上拉加载 - 自动处理分页加载 - 自动缺省页 - 自动处理生命周期 - 自动处理加载对话框 - 协程作用域支持错误和结束回调 - 支持先强制读取缓存后网络请求二次刷新 - 附带超强轮循器同时完全不影响[Kalle](https://github.com/yanzhenjie/Kalle)的特性 - 九种缓存模式 - 数据库缓存 - 缓存加密 - 上传进度监听 - 下载进度监听 - 断点续传 - 下载文件策略 - 网络连接判断 - 自定义数据转换器 - 网络拦截器 - 重定向 - 自定义请求体 - 全局配置 - Cookie - SSH证书 ## 安装 project 的 build.gradle ```groovy allprojects { repositories { // ... maven { url 'https://jitpack.io' } } } ``` module 的 build.gradle ```groovy // 协程库 implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.0' implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.0' // 支持自动下拉刷新和缺省页的, 可选, 刷新头和上拉加载参考SmartRefreshLayout (可选) implementation 'com.github.liangjingkanji:BRV:1.3.6' implementation 'com.github.liangjingkanji:Net:2.2.6' ``` ## 请求方式请求方式支持同步和异步, 异步只允许在作用域内执行. 详情请看`Net.kt`文件 ![image-20200626032128956](https://i.imgur.com/gjWnbLx.png) 请求方式全部属于协程中的`async`异步函数, 运行在IO线程中. 函数返回`Deferred`对象, 该对象通过`await()`函数获取结果. 执行await时会阻塞代码执行注意, 所以建议await在作用域最后一起执行, 保证请求全部发送出去然后统一获取结果. ### Post ```kotlin scopeNetLife { tv_fragment.text = Post("api").await() } ``` `Model` 即JSONBean或者说POJO 数据模型, 会将服务器返回的JSON解析成该数据模型在`net`回调中可以使用`it`调用 ### Get ```kotlin scopeNetLife { tv_fragment.text = Get("api").await() } ``` `Model` 泛型如果换成String, 将会在成功回调中得到字符串对象. ### 文件上传 ```kotlin scopeNetLife { Post("upload", requireContext().cacheDir.path) { val saveFile = getFile() file("file", saveFile) }.await() } ``` ### 文件下载 ```kotlin scopeNetLife { Download("download", requireContext().filesDir.path).await() } ``` ### 下载图片下载图片要求首先导入Glide依赖库, 下载图片和下载文件不同在于可以手动指定图片宽高 ```kotlin Context.DownloadImage(url: String, with: Int = -1, height: Int = -1) ``` 示例 ```kotlin scopeDialog { val file = DownloadImage(NetConfig.host + "download/img", 100, 100).await() val uri = Uri.fromFile(file) iv_img.setImageURI(uri) } ``` ## 初始化 ```kotlin class App : Application() { override fun onCreate() { super.onCreate() initNet("http://182.92.97.186/"){ // 转换器, 也可以自己实现Convert或者复写DefaultConverter. converter(object : DefaultConverter() { override fun convert(succeed: Type, body: String): S? { // 解析Json, 我这里是用的Moshi, 你也可以使用Gson之类的解析框架 return Moshi.Builder().build().adapter(succeed).fromJson(body) } }) } } } ``` ### 初始化配置在初始化的时候可以选择配置网络请求 ```kotlin initNet("http://182.92.97.186/") { // 默认错误处理 onError { } // PageObserver 默认错误处理 onPageError { } // 默认加载对话框 onDialog { ProgressDialog(it) } converter(object : DefaultConverter() { override fun convert(succeed: Type, body: String): S? { return Moshi.Builder().build().adapter(succeed).fromJson(body) } }) } ``` ### 错误信息第一种覆盖`onError`函数这里是默认的错误处理逻辑, 在初始化的时候也介绍过如何复写onError. 这里使用的系统默认的Toast进行错误信息提示用户, 你可以复写然后实现自己的吐司提示. ```kotlin internal var onError: Throwable.() -> Unit = { val message = when (this) { is NetworkError -> app.getString(R.string.network_error) is URLError -> app.getString(R.string.url_error) is HostError -> app.getString(R.string.host_error) is ConnectTimeoutError -> app.getString(R.string.connect_timeout_error) is ConnectException -> app.getString(R.string.connect_exception) is WriteException -> app.getString(R.string.write_exception) is ReadTimeoutError -> app.getString(R.string.read_timeout_error) is DownloadError -> app.getString(R.string.download_error) is NoCacheError -> app.getString(R.string.no_cache_error) is ReadException -> app.getString(R.string.read_exception) is ParseError -> app.getString(R.string.parse_error) is ParseJsonException -> app.getString(R.string.parse_json_error) is RequestParamsException -> app.getString(R.string.request_error) is ServerResponseException -> app.getString(R.string.server_error) is ResponseException -> msg else -> { printStackTrace() app.getString(R.string.other_error) } } Toast.makeText(app, message, Toast.LENGTH_SHORT).show() } ``` 1. 所有网络异常都可以通过字段`request`获取请求对象, 包含请求信息. 2. 本框架中自动打印的吐司内部是使用的[Tooltip](https://github.com/liangjingkanji/Tooltip)框架, 最好的吐司工具. 保证异步吐司和不会覆盖和长时间显示第二种复写`strings.xml`文件中的属性复写同name的属性可以达到修改文本信息内容或者进行国际化 ```xml Net 当前网络不可用请求资源地址错误无法找到指定服务器主机连接服务器超时，请重试请检查网络连接发送数据错误读取服务器数据超时，请检查网络下载过程发生错误读取缓存错误解析数据时发生异常读取数据错误解析JSON错误请求参数错误服务响应错误服务器未响应 ``` ### 异常日志网络请求的每个异常都会被自动打印到LogCat, 并且附带位置信息: location, 默认为url. 可以在拦截器中通过Request.location()设置 ## 作用域上面的网络请求方式全部使用的`scopeLife`, 该作用域属于跟随生命周期自动销毁作用域所有作用域都会自动打印异常信息到LogCat, 作用域都是异步执行在主线程 ### 异步作用域该作用域的生命周期跟随整个应用, 不会自动取消, 需要你自己手动取消`cancel()` ``` scope { } ``` ### 生命周期作用域该作用域默认在销毁`OnDestroy`时被销毁, 内部所有网络请求都会取消 ``` scopeLife { } ``` 函数 ```kotlin fun LifecycleOwner.scopeLife( lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_DESTROY, // 自定义销毁作用域的生命周期 block: suspend CoroutineScope.() -> Unit ): AndroidScope ``` 以上两种作用域不会自动吐司网络请求的异常信息 ### 网络请求作用域和异步作用域的区别就是会自动吐司网络请求的异常信息 ```kotlin scopeNet { Post("api"){ param("key", "value") }.await() } ``` 跟随生命周期的网络请求 ```kotlin scopeNetLife { Post("api"){ param("key", "value") } } ``` ### 自动加载对话框 ```kotlin scopeDialog { tv_fragment.text = Post("dialog") { param("u_name", "drake") param("pwd", "123456") }.await() } ``` 该作用域会在开始执行时显示对话框, 在作用域内全部任务执行完毕后取消对话框(异常或正常结束都会取消). 并且该对话框支持自定义全局或者通过函数参数传入单例对话框(仅该作用域对象使用的加载框) **自定义全局对话框** 全局对话框设置通过NetConfig.onDialog设置 ```kotlin initNet("http://182.92.97.186/") { onDialog { ProgressDialog(it).apply { setMessage("正在加载中") } // 返回一个Dialog } } ``` ### 自动缺省页 ```kotlin state.onRefresh { scope { // 异步作用域 val data = Post("api"){ param("key", "value") }.await() if(data == null){ showEmpty() }else { textView.text = data } } }.showLoading() ``` 缺省页支持局部(使用控件对象)和全局页面(Activity或者Fragment对象)开启作用域 Fragment|Activity|View都支持直接通过`scopeState`函数开启作用域 StateLayout使用`scope`函数开启作用域关于支持接收者类型有如下: - stateLayout - activity - fragment - view ### 自动下拉刷新兼具功能下拉刷新|上拉加载|分页|缺省页需要引入第三方库: [BRV](https://github.com/liangjingkanji/BRV) ```kotlin pageRefreshLayout.onRefresh { pageRefreshLayout.scope { val data = Get("list") { param("page", index) // index会自增 }.await().data addData(data){ index < data.totalPage // 判断是否存在下一页 } } }.showLoading() ``` 此时下拉和上拉都会调用该回调`onRefresh`中的接口请求. 如果下拉刷新和上拉加载的接口不一致可以再实现`onLoadMore`回调 ```kotlin pageRefreshLayout.onLoadMore { // 上拉加载网络请求 } ``` showLoading属于现实缺省页中的加载页, 你也可以使用`autoRefresh()`显示下拉刷新的动画而不是缺省页 Tip: PageRefreshLayout只要加载成功后即使后续请求失败也不会显示错误缺省页 ### 错误处理所有作用域都支持`catch|finally`函数回调 ```kotlin scopeDialog { val data = Get("error") textView.text = data.await() }.catch { // 只有发生异常才会执行, it为异常对象 }.finally { // 无论是否正常结束还是异常都会执行, it为异常对象, 如果非异常结束为NULL } ``` ## 请求和响应规范很多时候存在请求和响应的后台接口规范不是常规统一的, 这个时候我们可以自己拦截处理数据. 主要是实现拦截器(`Interceptor`)和转换器(`Convert`) Interceptor 这个和Okhttp同样, 可以拦截和修改请求参数, 并且可以获得Response的实例. ### Interceptor > 这里可以得到Request和Response, 进行数据添加修改以及重新拼装请求, 不熟悉的请搜索Okhttp Interceptor使用. ### Convert Convert 主要进行数据转换, 这里一般解析JSON对象. 这就是实现`DefaultConvert`自己解析Json对象. DefaultConverter是框架中定义的一个默认处理JSON示例, 一般情况使用它解析下JSON即可. ```kotlin initNet("hhttp://182.92.97.186/") { converter(object : DefaultConverter() { override fun String.parseBody(succeed: Type): S? { return Moshi.Builder().build().adapter(succeed).fromJson(this) } }) } ``` DefaultConvert构造函数拥有三个参数默认值 ```kotlin abstract class DefaultConverter(val success: String = "0", val code: String = "code", val msg: String = "msg") ``` 因为内部需要得到错误码`code`来判断请求是否真正成功以及错误消息`msg`来在错误的时候进行打印吐司错误信息. 所以需要知道解析JSON时的Key来获取. 一般情况下重写两个函数即可 ```kotlin /** * 解析数据用于获取基本接口信息 */ abstract fun String.parseBody(succeed: Type): S? ``` 如果涉及到响应的JSON数据需要解密或者错误码为某个数字时跳转登录界面可以直接重写`Convert`(建议复制参考DefaultConvert源码). ## 预缓存和网络请求很多App要求秒启动展示首页数据, 然后断网以后也可以展示缓存数据, 这种需求需要做到刷新UI数据两遍, 本框架同样方便实现首先在初始化的时候启用缓存功能 ```kotlin initNet("http://182.92.97.186/") { cacheEnabled() } ``` 可配置参数 ```kotlin fun KalleConfig.Builder.cacheEnabled( path: String = NetConfig.app.cacheDir.absolutePath, // 缓存保存位置, 默认应用缓存目录 password: String = "cache" // 缓存密码, 默认cache ) ``` 发起缓存请求 ```kotlin scopeNetLife { Log.d("日志", "网络请求") textView.text = Get("api", cache = CacheMode.NETWORK_YES_THEN_WRITE_CACHE).await() }.cache { Log.d("日志", "读取缓存") textView.text = Get("api", cache = CacheMode.READ_CACHE).await() } ``` 上面示例代码这种属于: 先加载缓存(没有缓存不会报异常), 后网络请求(缓存和网络请求都失败报异常信息), 网络请求成功缓存到本地并刷新界面UI 注意事项 1. CacheMode: 属于Kalle的缓存模式, 共有九种缓存模式适用于不同的业务场景: [文档](https://yanzhenjie.com/Kalle/cache/) 2. cache: 该作用域内部允许抛出任何异常都不算错误, 这里的`cache`会比`scopeNetLife`先执行. 3. 当缓存读取成功视为作用域执行成功, 默认情况即使后续的网络请求失败也不会提示错误信息(cache函数参数指定true则提示) ```kotlin fun cache(error: Boolean = false, // 缓存读取成功但网络请求失败是否吐司错误信息 animate: Boolean = false, // 缓存读取成功是否立即停止加载动画, 只有PageRefreshLayout有效 onCache: suspend CoroutineScope.() -> Unit): AndroidScope ``` ## 轮循器本框架附带一个超级强大的轮循器`Interval`, 基本上包含轮循器所需要到所有功能 - 支持多个观察者订阅同一个计时器 - 开始 | 暂停 | 继续 | 停止 - 同时包含RxJava的操作符`interval|intervelRange`功能 - 轮循器即Observable对象, 所以可以进行任意操作符转换. 例如轮循器控制网络请求示例 ```kotlin Interval(1, TimeUnit.SECONDS).subscribe { }.finish { }.start() ``` 函数 ``` subscribe() // 订阅定时器, 订阅多个也会监听同一个计数器 start() // 开始 stop() // 结束 pause() // 暂停 resume() // 继续 reset // 重置轮循器 (包含计数器count和计时period) 不会停止轮循器 switch // 切换轮循器开关 state // 得到当前轮循器的状态 life() // 绑定生命周期, 自动取消轮循器 ```