介绍 #

OkHttps 简介 #

OkHttps 是 2020 年开源的对 OkHttp3 轻量封装的框架，它独创的异步预处理器，特色的标签，灵活的上传下载进度监听与过程控制功能，在轻松解决很多原本另人头疼问题的同时，设计上也力求纯粹与优雅。

• 链式调用，一点到底
• BaseURL、URL占位符、HTTP、WebSocket
• JSON、Xml 等自动封装与解析，且支持与任意格式的数据解析框架集成
• 同步拦截器、异步预处理器、回调执行器、全局监听、回调阻断
• 文件上传下载（过程控制、进度监听）
• 单方法回调，充分利用 Lambda 表达式
• TCP连接池、Http2

项目组成 #

依赖说明 #

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>

Gradle #

implementation 'com.squareup.okhttp3:okhttp:4.9.0'

版本迭代 #

OkHttps 从最初的 httputils 演变而来，期间共经历了二十多个版本迭代 以及 上百个前后端项目的生产检验，目前已非常稳定。详细的版本可参见 httputils 版本演变 和 okhttps 版本演变。

虽然目前 OkHttps 已非常稳定，所有暴露的 ISSUE 均已解决，但难免新手在使用的过程中会遇到各种各样的问题（这是学习任何一门框架必不可少的采坑过程），所以我们从 OkHttps 技术交流群里把一些高频问题整理成了一份 常见问题列表，可供大家在遇到困难时参考。

v2.5 的新特性 #

API 部分 #

1. HTTP#Builder新增contentTypes方法，可扩展配置默认支持的请求类型
2. HTTP#Builder新增clearPreprocessors、clearMsgConvertors方法
3. HttpResult新增getTask方法，可获取所属的请求任务
4. HttpResult新增of(HttpTask<?>, Response)方法，可构造一个HttpResult实例
5. WebSocketTask新增flexiblePing(boolean)方法，当传参false时，可兼容某些强制客户端必须以固定的间隔发送心跳的服务器
6. Stomp新增sendToTopic与sendToQueue方法，
7. Stomp新增isConnected方法，可直接判断连接是否已建立

优化部分 #

1. 优化自定义请求方法HttpTask#request()的参数处理：请求方法自动 toUpperCase，避免用户传入小写时造成意想不到的问题
2. 优化bodyType与msgType的参数处理，自动 toLowerCase，避免用户传入大写时造成意想不到的问题
3. 使得未添加MsgConvertor时，使用setBodyPara(String|byte[])与bodyType方法也能够发起对应格式的请求
4. 优化 Stomp 订阅与退订机制：同一个实例支持多线程并发订阅与退订操作
5. 优化 Stomp 消息匹配机制：兼容 RabbitMQ 在某些情况下的推送的 消息目的地 与 订阅目的地 不一致的情况
6. 优化 Stomp 连接的断开流程：在连接断开前保证已发消息到达服务器
7. 优化文件下载的异常处理流程

升级注意事项： #

1. 类FilePara从HttpTask中分离，不再是HttpTask的内部类，有直接引用FilePara的代码需要重新导包。

v2.4 的新特性 #

1. 全面兼容 OkHttp 4.x 版本
2. HttpTask 新增 getPathParas()、getUrlParas()、getBodyParas()、getFileParas()、getRequestBody() 方法
3. 优化HttpTask#addFilePara(String name, String type, byte[] content)方法，添加自动生成文件名逻辑，兼容某些必须要提供文件名才能接受到文件的后端接口
4. Stomp 新增setOnError方法，可监听处理处理服务器发出的 ERROR 帧
5. 新增超轻量无第三方依赖的 XML 解析扩展（v2.4.2 起）
6. 同一个 HttpResult 和 HttpBody 可以多线程并发访问（v2.4.3 起）
7. Websocket 新增 status() 方法，可查看当前连接的状态，WebSocketTask 新增 isConnected() 方法，可以判断是否已连接（v2.4.5 起）
8. 抽象 DataSet（只读数据集）接口，Mapper 和 Array 为其子接口（v2.4.5 起）

v2.3 的新特性 #

重新实现 WebSocket 心跳机制 使用者可以选择使用 OkHttp 自带的心跳机制，也可以选择使用 OkHttps 提供的增强型心跳机制，它具有如下特性

1. 客户端发送的任何消息都具有一次客户端心跳作用
2. 服务器发送的任何消息都具有一次服务器心跳作用
3. 若服务器超过 3 * pongSeconds 秒没有回复心跳，才判断心跳超时
4. 可指定心跳的具体内容（默认为空）

v2.2 的新特性 #

1. 增强泛型反序列化，支持复合泛型
2. HttpCall 接口新增 getTask 方法，可获取当前任务
3. OkHttps 工具类 新增 newBuilder 方法，可用于复制 SPI 方式注入的配置信息
4. HttpTask 类 新增 isAsyncHttp 和 isSyncHttp 方法（v2.1.0 新增了 isWebsocket 方法）可用于判断 HttpTask 的任务类型
5. 优化在 Android 端的异步请求性能

v2.1 的新特性 #

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

2. 优化性能：使用HTTP#newBuilder()方法克隆HTTP实例时，新实例与旧实例之间资源共享最大化。

v2.0 的新特性 #

1. HTTP 任务新增patch()和head()方法，可发起 PATCH 和 HEAD 请求，目前直接支持的 HTTP 方法有：GET、POST、PUT、PATCH、DELETE，并且暴露了request(String method)方法，可自定义发起任何请求，如：HEAD、OPTIONS、TRACE、CONNECT 等；
2. HTTP 任务新增skipPreproc()和skipSerialPreproc()方法，具体请求可跳过 所有 或只跳过 串行 预处理器；
3. 新增MsgConvertor接口，实现 OkHttps 与 fastjson 解耦，且不再依赖某个具体 json 框架、甚至不依赖 json，它可以与 任何格式 的数据解析框架集成，如：json 、xml 、protobuf 等;
4. 构建HTTP实例时支持注入多个MsgConvertor，可实现同一个HTTP实例下，既有 json 解析，又有 xml 解析等强大特性，同时还可以让表单（form）请求参数 同 json、xml 一样，支持序列化功能。
5. HTTP接口新增webSocket(String url)方法，与sync(String url)和async(String url)一样，支持 Lamda 编程、预处理器机制、消息数据自动序列化和反序列化机制；
6. 新增OkHttps工具类，支持 SPI 方式注入配置，OkHttps和HttpUtils默认自动以 SPI 方式寻找依赖中的MsgConvertor；
7. 新增可自定义默认编码（不自定义依然默认为 utf-8）、具体请求可指定特殊编码功能。

#