Net

异步任务库, Android 创新式的网络请求库(针对Kalle网络请求框架进行扩展), 支持协程高并发网络请求

本项目为Android项目中的所有的异步任务和网络请求而生

The project is supported by JetBrains, Best IDE to developer

1.0+ 版本为RxKotlin实现 2.0+ 版本开始引入Kotlin协程特性, 开发者无需掌握协程也可以使用, 两个版本存在Api变动需要手动迁移

主要新增特性

协程
并发网络请求
串行网络请求
切换线程
DSL编程
方便的缓存处理
自动错误信息吐司
自动异常捕获
自动日志打印异常
自动JSON解析
自动处理下拉刷新和上拉加载
自动处理分页加载
自动缺省页
自动处理生命周期
自动处理加载对话框
协程作用域支持错误和结束回调
支持先强制读取缓存后网络请求二次刷新
附带超强轮循器

同时完全不影响Kalle的特性

九种缓存模式
数据库缓存
缓存加密
上传进度监听
下载进度监听
断点续传
下载文件策略
网络连接判断
自定义数据转换器
网络拦截器
重定向
自定义请求体
全局配置
Cookie
SSH证书

安装

project 的 build.gradle

allprojects {
    repositories {
        // ...
        maven { url 'https://jitpack.io' }
    }
}

module 的 build.gradle

// 协程库
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.2.1'

implementation 'com.github.liangjingkanji:Net:2.0.11'

请求方式

请求方式支持同步和异步, 异步只允许在作用域内执行. 详情请看Net.kt文件

请求方式全部属于协程中的async异步函数, 运行在IO线程中. 函数返回Deferred<T>对象, 该对象通过await()函数获取结果.

执行await时会阻塞代码执行注意, 所以建议await在作用域最后一起执行, 保证请求全部发送出去然后统一获取结果.

Post

scopeLife {

  val data = post<String>(
    "https://raw.githubusercontent.com/liangjingkanji/BRV/master/README.md",
    absolutePath = true
  )

  textView.text = data.await()
}

Model 即JSONBean或者说POJO 数据模型, 会将服务器返回的JSON解析成该数据模型在net回调中可以使用it调用

Get

scopeLife {

  val data = get<String>(
    "https://raw.githubusercontent.com/liangjingkanji/BRV/master/README.md",
    absolutePath = true
  )

  textView.text = data.await()
}

Model 泛型如果换成String, 将会在成功回调中得到字符串对象.

文件上传

scopeLife {

  val data = post<String>(
    "https://raw.githubusercontent.com/liangjingkanji/BRV/master/README.md",
    absolutePath = true
  ){
    file("file", File())
  }.await()

  textView.text = data.await()
}

这是支持Kalle任何参数添加方式

文件下载

scopeLife {
  download("/path", "下载目录"){

    // 进度监听
    onProgress { progress, byteCount, speed ->

               }

  }.await()
}

下载图片

下载图片要求首先导入Glide依赖库, 下载图片和下载文件不同在于可以手动指定图片宽高

Context.downloadImg(url: String, with: Int = -1, height: Int = -1)

示例

scopeLife {

  val data = downImage(
    "https://cdn.sspai.com/article/ebe361e4-c891-3afd-8680-e4bad609723e.jpg?imageMogr2/quality/95/thumbnail/!2880x620r/gravity/Center/crop/2880x620/interlace/1".
    200,200
  ).await()

}

初始化

class App : Application() {

    override fun onCreate() {
        super.onCreate()

        initNet("主机名"){

            // 转换器, 也可以自己实现Convert或者复写DefaultConverter.
            converter(object : DefaultConverter() {
                override fun <S> convert(succeed: Type, body: String): S? {
					// 解析Json, 我这里是用的Moshi, 你也可以使用Gson之类的解析框架
                    return Moshi.Builder().build().adapter<S>(succeed).fromJson(body)
                }
            })
        }
    }
}

初始化配置

在初始化的时候可以选择配置网络请求

initNet("http://192.168.2.1") {

  // 默认错误处理
  onError {

  }

  // PageObserver 默认错误处理
  onPageError {

  }

  // 默认加载对话框
  onDialog {

    ProgressDialog(it)
  }

  converter(object : DefaultConverter() {
    override fun <S> convert(succeed: Type, body: String): S? {
      return Moshi.Builder().build().adapter<S>(succeed).fromJson(body)
    }
  })
}

错误信息

第一种覆盖onError函数

这里是默认的错误处理逻辑, 在初始化的时候也介绍过如何复写onError.

这里使用的系统默认的Toast进行错误信息提示用户, 你可以复写然后实现自己的吐司提示.

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()
}

第二种复写strings.xml文件中的属性

复写同name的属性可以达到修改文本信息内容或者进行国际化

<resources>
    <string name="app_name">Net</string>

    <!--网络请求异常-->
    <string name="network_error">当前网络不可用</string>
    <string name="url_error">请求资源地址错误</string>
    <string name="host_error">无法找到指定服务器主机</string>
    <string name="connect_timeout_error">连接服务器超时，请重试</string>
    <string name="connect_exception">请检查网络连接</string>
    <string name="write_exception">发送数据错误</string>
    <string name="read_timeout_error">读取服务器数据超时，请检查网络</string>
    <string name="download_error">下载过程发生错误</string>
    <string name="no_cache_error">读取缓存错误</string>
    <string name="parse_error">解析数据时发生异常</string>
    <string name="read_exception">读取数据错误</string>
    <string name="parse_json_error">解析JSON错误</string>
    <string name="request_error">请求参数错误</string>
    <string name="server_error">服务响应错误</string>
    <string name="other_error">服务器未响应</string>

</resources>

异常日志

网络请求的每个异常都会被自动打印到LogCat, 并且附带位置信息: location, 默认为url. 可以在拦截器中通过Request.location()设置

作用域

上面的网络请求方式全部使用的scopeLife, 该作用域属于跟随生命周期自动销毁作用域

所有作用域都会自动打印异常信息到LogCat, 作用域都是异步执行在主线程

异步作用域

该作用域的生命周期跟随整个应用, 不会自动取消, 需要你自己手动取消cancel()

scope {
	
}

生命周期作用域

该作用域默认在销毁OnDestroy时被销毁, 内部所有网络请求都会取消

scopeLife {
	
}

函数

fun LifecycleOwner.scopeLife(
    lifeEvent: Lifecycle.Event = Lifecycle.Event.ON_DESTROY, // 自定义销毁作用域的生命周期
    block: suspend CoroutineScope.() -> Unit
): AndroidScope

以上两种作用域不会自动吐司网络请求的异常信息

网络请求作用域

和异步作用域的区别就是会自动吐司网络请求的异常信息

scopeNet {

}

跟随生命周期的网络请求

scopeNetLife {
	
}

自动加载对话框

scopeDialog {

}

该作用域会在开始执行时显示对话框, 在作用域内全部任务执行完毕后取消对话框(异常或正常结束都会取消).

并且该对话框支持自定义全局或者通过函数参数传入单例对话框(仅该作用域对象使用的加载框)

自定义全局对话框

全局对话框设置通过NetConfig.onDialog设置

initNet("http://localhost.com") {
  onDialog {
    ProgressDialog(it).apply { setMessage("正在加载中") } // 返回一个Dialog
  }
}

自动缺省页

scopeState {

}

缺省页支持局部(使用控件对象)和全局页面(Activity或者Fragment对象)开启作用域

Fragment|Activity|View都支持直接通过scopeState函数开启作用域

StateLayout使用scope函数开启作用域

关于支持接收者类型有如下:

stateLayout
activity
fragment
view

自动下拉刷新

兼具功能下拉刷新|上拉加载|分页|缺省页

需要引入第三方库: BRV

pageRefreshLayout.onRefresh { 

  pageRefreshLayout.scope {

    val result = post<Model>("/path"){
      param("key", "value")
      param("page", index) // 页面索引使用pageRefreshLayout的属性index
    }

    val data = result.await().data

    if (data.isEmpty()){
      it.showEmpty()
      return
    }
    
    it.addData(data){
      index < data.totalPage // 判断是否存在下一页
    }
  }
}.showLoading

此时下拉和上拉都会调用该回调onRefresh中的接口请求.

如果下拉刷新和上拉加载的接口不一致可以再实现onLoadMore回调

pageRefreshLayout.onLoadMore {
	// 上拉加载网络请求
}

showLoading属于现实缺省页中的加载页, 你也可以使用autoRefresh()显示下拉刷新的动画而不是缺省页

如果仅仅是自动完成下拉加载. 例如一般用户中心页面只需要自动处理下拉刷新的状态

pageRefreshLayout.scopeRefresh{

}

Tip: PageRefreshLayout只要加载成功后即使后续请求失败也不会显示错误缺省页

错误处理

所有作用域都支持catch|finally函数回调

scopeDialog {

  val data = get<String>(
    "https://raw.githubusercontent.com/liangjingkanji/BRV/master/README.md",
    absolutePath = true
  )

  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即可.

initNet("http://localhost.com") {
    converter(object : DefaultConverter() {
        override fun <S> convert(succeed: Type, body: String): S? {
            return Moshi.Builder().build().adapter<S>(succeed).fromJson(body)
        }
    })
}

DefaultConvert构造函数拥有三个参数默认值

abstract class DefaultConverter(
    val successCode: String = "0",
    val codeName: String = "code",
    val msgName: String = "msg"
)

因为内部需要得到错误码codeName来判断请求是否真正成功以及错误消息msgName来在错误的时候进行打印吐司错误信息.

所以需要知道解析JSON时的Key来获取.

如果涉及到响应的JSON数据需要解密或者错误码为某个数字时跳转登录界面可以直接重写Convert(建议复制参考DefaultConvert源码).

缓存和网络请求

很多App要求秒启动展示首页数据, 然后断网以后也可以展示缓存数据, 这种需求需要做到刷新UI数据两遍, 本框架同样方便实现

首先在初始化的时候启用缓存功能

initNet("http://localhost.com") {
	cacheEnabled()
}

可配置参数

fun KalleConfig.Builder.openCache(
    path: String = NetConfig.app.cacheDir.absolutePath, // 缓存保存位置, 默认应用缓存目录
    password: String = "cache" // 缓存密码, 默认cache
)

发起缓存请求

scopeNetLife {

  Log.d("日志", "网络请求")

  val data = get<String>(
    "https://raw.githubusercontent.com/liangjingkanji/BRV/master/README.md",
    cache = CacheMode.NETWORK_YES_THEN_WRITE_CACHE,
    absolutePath = true
  )

  textView.text = data.await()

}.cache {

  Log.d("日志", "读取缓存")

  val data = get<String>(
    "https://raw.githubusercontent.com/liangjingkanji/BRV/master/README.md",
    cache = CacheMode.READ_CACHE,
    absolutePath = true
  )

  textView.text = data.await()
}

上面示例代码这种属于: 先加载缓存(没有缓存不会报异常), 后网络请求(缓存和网络请求都失败报异常信息), 网络请求成功缓存到本地并刷新界面UI.

注意事项

CacheMode: 属于Kalle的缓存模式, 共有九种缓存模式适用于不同的业务场景: 文档
cache: 该作用域内部允许抛出任何异常都不算错误, 这里的cache会比scopeNetLife先执行.
当缓存读取成功视为作用域执行成功, 默认情况即使后续的网络请求失败也不会提示错误信息(cache函数参数指定true则提示)

轮循器

本框架附带一个超级强大的轮循器Interval, 基本上包含轮循器所需要到所有功能

支持多个观察者订阅同一个计时器
开始 | 暂停 | 继续 | 停止
同时包含RxJava的操作符interval|intervelRange功能
轮循器即Observable对象, 所以可以进行任意操作符转换. 例如轮循器控制网络请求

示例

Interval(1, TimeUnit.SECONDS).subscribe { 
	
}.finish { 
	
}.start()

函数

subscribe() // 即开启定时器, 订阅多个也会监听同一个计数器
start() // 开始
stop() // 结束
pause() // 暂停
resume() // 继续
reset // 重置轮循器 (包含计数器count和计时period) 不会停止轮循器
switch //  切换轮循器开关

state // 得到当前轮循器的状态

README.md 15 KB Історія Запис

Net

安装