介绍
OkHttps 简介
OkHttps 是 2020 年开源的对 OkHttp3 轻量封装的框架,它独创的异步预处理器,特色的标签,灵活的上传下载进度监听与过程控制功能,在轻松解决很多原本另人头疼问题的同时,设计上也力求纯粹与优雅。
- 链式调用,一点到底
- BaseURL、URL占位符、HTTP、WebSocket
- JSON、Xml 等自动封装与解析,且支持与任意格式的数据解析框架集成
- 同步拦截器、异步预处理器、回调执行器、全局监听、回调阻断
- 文件上传下载(过程控制、进度监听)
- 单方法回调,充分利用 Lambda 表达式
- TCP连接池、Http2
TIP
- OkHttps 非常轻量(最新版仅 90KB),除 Okhttp 无第三方依赖,并且更加的开箱即用,API 也更加自然和语义化。
- OkHttps 是一个纯粹的 Java 网络开发包,并不依赖 Android,这一点和 Retrofit 不同
- OkHttps 用起来很优美,可以像 RxJava 那样链式用,却比 RxJava 更简单。
项目组成
项目 | 最新版本 | 描述 |
---|---|---|
okhttps | 2.5.1 | OkHttps 核心模块 |
okhttps-fastjson | 2.5.1 | 与 fastjson 集成 |
okhttps-gson | 2.5.1 | 与 gson 集成 |
okhttps-jackson | 2.5.1 | 与 jackson 集成 |
okhttps-stomp | 2.5.1 | 超轻量 Stomp 客户端(无第三方依赖) |
okhttps-xml | 2.5.1 | 超轻量 XML 解析扩展(无第三方依赖,但仅支持 Java 8) |
依赖说明
OkHttps 默认依赖 OkHttp3 的 3.x 的最新 3.14.9 版本,但是已经全面兼容 OkHttp3 的 4.x 版本。默认依赖之所以不是 4.x,主要考虑到:
- OkHttp3 4.x 是用 Kotlin 重写,包体相对较大(约是 3.x 的 1.8 倍)
- 在没有 Kotlin 依赖的纯 Java 项目中,使用 4.x 会存在一些问题。
如果你的项目使用的是 Kotlin 语言,并且想使用 OkHttp3 4.x 的话,可以在项目的依赖文件中添加以下配置来覆盖:
Mavel
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>4.9.0</version>
</dependency>
1
2
3
4
5
2
3
4
5
Gradle
implementation 'com.squareup.okhttp3:okhttp:4.9.0'
1
版本迭代
OkHttps 从最初的 httputils 演变而来,期间共经历了二十多个版本迭代 以及 上百个前后端项目的生产检验,目前已非常稳定。详细的版本可参见 httputils 版本演变 和 okhttps 版本演变。
虽然目前 OkHttps 已非常稳定,所有暴露的 ISSUE 均已解决,但难免新手在使用的过程中会遇到各种各样的问题(这是学习任何一门框架必不可少的采坑过程),所以我们从 OkHttps 技术交流群里把一些高频问题整理成了一份 常见问题列表,可供大家在遇到困难时参考。
v2.5 的新特性
API 部分
HTTP#Builder
新增contentTypes
方法,可扩展配置默认支持的请求类型HTTP#Builder
新增clearPreprocessors
、clearMsgConvertors
方法HttpResult
新增getTask
方法,可获取所属的请求任务HttpResult
新增of(HttpTask<?>, Response)
方法,可构造一个HttpResult
实例WebSocketTask
新增flexiblePing(boolean)
方法,当传参false
时,可兼容某些强制客户端必须以固定的间隔发送心跳的服务器Stomp
新增sendToTopic
与sendToQueue
方法,Stomp
新增isConnected
方法,可直接判断连接是否已建立
优化部分
- 优化自定义请求方法
HttpTask#request()
的参数处理:请求方法自动 toUpperCase,避免用户传入小写时造成意想不到的问题 - 优化
bodyType
与msgType
的参数处理,自动 toLowerCase,避免用户传入大写时造成意想不到的问题 - 使得未添加
MsgConvertor
时,使用setBodyPara(String|byte[])
与bodyType
方法也能够发起对应格式的请求 - 优化 Stomp 订阅与退订机制:同一个实例支持多线程并发订阅与退订操作
- 优化 Stomp 消息匹配机制:兼容 RabbitMQ 在某些情况下的推送的 消息目的地 与 订阅目的地 不一致的情况
- 优化 Stomp 连接的断开流程:在连接断开前保证已发消息到达服务器
- 优化文件下载的异常处理流程
升级注意事项:
- 类
FilePara
从HttpTask
中分离,不再是HttpTask
的内部类,有直接引用FilePara
的代码需要重新导包。
v2.4 的新特性
- 全面兼容 OkHttp 4.x 版本
- HttpTask 新增
getPathParas()
、getUrlParas()
、getBodyParas()
、getFileParas()
、getRequestBody()
方法 - 优化
HttpTask#addFilePara(String name, String type, byte[] content)
方法,添加自动生成文件名逻辑,兼容某些必须要提供文件名才能接受到文件的后端接口 - Stomp 新增
setOnError
方法,可监听处理处理服务器发出的 ERROR 帧 - 新增超轻量无第三方依赖的 XML 解析扩展(v2.4.2 起)
- 同一个 HttpResult 和 HttpBody 可以多线程并发访问(v2.4.3 起)
- Websocket 新增 status() 方法,可查看当前连接的状态,WebSocketTask 新增 isConnected() 方法,可以判断是否已连接(v2.4.5 起)
- 抽象 DataSet(只读数据集)接口,Mapper 和 Array 为其子接口(v2.4.5 起)
v2.3 的新特性
重新实现 WebSocket 心跳机制 使用者可以选择使用 OkHttp 自带的心跳机制,也可以选择使用 OkHttps 提供的增强型心跳机制,它具有如下特性
- 客户端发送的任何消息都具有一次客户端心跳作用
- 服务器发送的任何消息都具有一次服务器心跳作用
- 若服务器超过 3 * pongSeconds 秒没有回复心跳,才判断心跳超时
- 可指定心跳的具体内容(默认为空)
v2.2 的新特性
- 增强泛型反序列化,支持复合泛型
- HttpCall 接口新增 getTask 方法,可获取当前任务
- OkHttps 工具类 新增 newBuilder 方法,可用于复制 SPI 方式注入的配置信息
- HttpTask 类 新增 isAsyncHttp 和 isSyncHttp 方法(v2.1.0 新增了 isWebsocket 方法)可用于判断 HttpTask 的任务类型
- 优化在 Android 端的异步请求性能
v2.1 的新特性
- 对异步请求的响应提供了 6 种便捷回调方法,在不关心具体状态时(与全局响应监听组合使用),使用非常方便;
setOnResBody
在回调里直接取得Body
对象,无需再使用res.getBody()
setOnResBean
在回调里直接取得 Java Bean 对象,无需再使用res.getBody().toBean(Class<?>)
setOnResList
在回调里直接取得 Java List 列表,无需再使用res.getBody().toList(Class<?>)
setOnResMapper
在回调里直接取得 Mapper 对象,无需再使用res.getBody().toMapper()
setOnResArray
在回调里直接取得 Array 对象,无需再使用res.getBody().toArray()
setOnResString
在回调里直接取得 String 对象,无需再使用res.getBody().toString()
- 优化性能:使用
HTTP#newBuilder()
方法克隆HTTP
实例时,新实例与旧实例之间资源共享最大化。
v2.0 的新特性
- HTTP 任务新增
patch()
和head()
方法,可发起 PATCH 和 HEAD 请求,目前直接支持的 HTTP 方法有:GET、POST、PUT、PATCH、DELETE,并且暴露了request(String method)
方法,可自定义发起任何请求,如:HEAD、OPTIONS、TRACE、CONNECT 等; - HTTP 任务新增
skipPreproc()
和skipSerialPreproc()
方法,具体请求可跳过 所有 或只跳过 串行 预处理器; - 新增
MsgConvertor
接口,实现 OkHttps 与 fastjson 解耦,且不再依赖某个具体 json 框架、甚至不依赖 json,它可以与 任何格式 的数据解析框架集成,如:json 、xml 、protobuf 等; - 构建
HTTP
实例时支持注入多个MsgConvertor
,可实现同一个HTTP
实例下,既有 json 解析,又有 xml 解析等强大特性,同时还可以让表单(form)请求参数 同 json、xml 一样,支持序列化功能。 HTTP
接口新增webSocket(String url)
方法,与sync(String url)
和async(String url)
一样,支持 Lamda 编程、预处理器机制、消息数据自动序列化和反序列化机制;- 新增
OkHttps
工具类,支持 SPI 方式注入配置,OkHttps
和HttpUtils
默认自动以 SPI 方式寻找依赖中的MsgConvertor
; - 新增可自定义默认编码(不自定义依然默认为 utf-8)、具体请求可指定特殊编码功能。