介绍 #

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.3</version>
</dependency>

Gradle #

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

版本迭代 #

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

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

v4.0 的新特性（v4.0.3） #

1. 更换 Maven 坐标 groupId: com.ejlchina -> cn.zhxu
2. 代码包名重构：com.ejlchina.* -> cn.zhxu.*
3. 新增 okhttps-fastjson2 模块
4. 新增 okhttps-fastjson2-jsonb 模块
5. 新增 okhttps-jackson-xml 模块
6. 新增 okhttps-jackson-yaml 模块
7. 新增 okhttps-snack3 模块
8. 依赖升级 data: v1.4.1 -> v1.5.2

v3.5 的新特性（v3.5.3） #

1. 增强：HttpTask 新增 Basic Auth 便捷方法：basicAuth(String username, String password)
2. 增强：HttpTask 新增 Bearer Auth 便捷方法：bearerAuth(String token)
3. 增强：HttpTask 新增 流式文件 上传方法：addFilePara(String name, String type, InputStream stream)
4. 增强：HttpTask 新增 流式文件 上传方法：addFilePara(String name, String type, String fileName, InputStream stream)
5. 增强：HttpTask 新增方法：addFilePara(String name, byte[] content, String fileName)（since v3.5.1）
6. 增强：HttpTask 新增方法：addFilePara(String name, InputStream stream, String fileName)（since v3.5.1）
7. 增强：HttpTask 增强 setBodyPara(Object body) 方法：使其可以接受 InputStream 类型的 流式报文体 参数
8. 增强：HttpTask 使用 ListMap 作为请求参数的内部集合容器：使其可以接受 多个同名参数 并可 保持参数的添加顺序
9. 增强：HTTP 的 HTTP.builder() 方法，使之支持通过指定系统环境变量来让该方法返回不同的构建器实现类
10. 增强：HTTP.Builder 新增 clearContentTypes() 方法
11. 增强：HttpResult 新增 allHeaders() 方法
12. 优化：HttpTask 放松校验：移除 必须将路径参数占位符全部填充的 检查
13. 优化：HttpTask 请求时 Content-Type 请求头 不再 默认携带 charset 信息
14. 优化：AbstractHttpClient 的 mediaType 映射机制
15. 完善：OkHttpBuilderImpl 常见的 mediaType 映射
16. 完善：DownloadHelper 添加更多常见的扩展名映射
17. 重构：java.util.function.Supplier 替代 cn.zhxu.okhttps.PingSupplier 接口
18. 重构：java.util.function.Consumer 替代 cn.zhxu.okhttps.OnCallback 接口
19. 升级：data：v1.1.2 -> v1.4.1：https://gitee.com/troyzhxu/data/releases
    • Mapper 新增 toBean(Class<T> type)、toBean(TypeRef<T> type) 与 toBean(Type type) 方法
    • Array 新增 toList(Class<T> type) 方法
    • DataConvertor 新增：toMapper(String in)、toArray(String in)、serialize(Object object)、toBean(Type type, String in)、toList(Class<T> type, String in) 方法
    • Deserializer 新增 getInstance() 方法
    • fastjson: v1.2.79 -> v1.2.80
    • jackson: v2.12.6 -> v2.13.2.2
    • 新增 ListMap 接口 与 ArrayListMap / LinkedListMap 相关实现类
20. 过时：HttpResult 的 getHeaders() 方法标记为已过时
21. 过时：HttpResult.Body 的 getType() 方法标记为已过时

v3.4 的新特性（v3.4.7） #

1. 重构: HttpTask 的 addBodyPara(..) 方法，使支持多层数据结构（JSON/XML）
2. 优化: Stomp，在 OnError/OnException 时重置 connecting 状态
3. HttpTask 新增 boundary(String boundary) 方法，用于自定义上传文件时 MultipartBody 的边界符（since v3.4.2）
4. 调用 addFilePara(..) 上传文件时，支持指定以 multipart/ 开头的 bodyType，来修改默认的 multipart/form-data 请求类型（since v3.4.2）
5. 构建 HTTP 实例时支持配置 DownloadHelper，可自定义下载文件时文件名生成规则（since v3.4.2）
6. 优化默认下载文件名生成逻辑，在未指定文件名的情况下更据 Content-Type 自动生成文件的扩展名（since v3.4.2）
7. Stomp 重复订阅时不再抛异常，只输出错误日志（since v3.4.6）

v3.3 的新特性（v3.3.2） #

1. 兼容 JDK9+ 的模块引入机制
2. 类 HTTP.Builder 接口化，试图与 okhttp3 解耦
3. 以下 类名/包名 重构：

4. 增强 HttpTask.addFilePara 方法的 type 参数，可直接传 MediaType 全称（since v3.3.1）
5. Websocket 支持设置 最大 Closing 时长，即在 OnClosing 回调执行后的指定时间内，可以保证 OnClosed 回调一定被执行（since v3.3.1）

v3.2 的新特性（v3.2.0） #

1. HttpTask 新增方法：addFilePara(String name, String type, String filePath)
2. HttpTask 新增方法：addFilePara(String name, String type, File file)
3. 优化异步请求回调机制：取消请求时，仍然执行 OnComplete 回调
4. 所有回调执行完毕后，HttpTask 不再可以取消，调用 cancel 时将返回 false
5. 新增枚举 Download.Status 类型，替换下载状态的整型常量
6. 下载控制器 Download.Ctrl 的 pause、resume 和 cancel 方法新增 boolean 返回值，表示是否操作成功
7. 当下载指定的目标文件不存在时，同样执行 onFailure 回调
8. Download 新增 OnComplete 下载结束回调（成功、失败、取消都执行）
9. 优化 HTTP.Builder.config(OkConfig config) 方法，支持多次注入配置

v3.1 的新特性（v3.1.5） #

1. 类 OkHttps 与 HttpUtils 开放 getHttp() 方法
2. 类 WebSocketTask 新增 close 方法，用于关闭当前连接
3. 优化 WebSocketTask：同一时间只能建立一个连接，如果已经建立连接并未断开，重复调用 listen() 方法将直接返回原有连接
4. 类 Stomp 新增 disconnect(int maxWaitSeconds) 方法
5. 类 Stomp 新增 disconnect(boolean immediate) 方法，用于立即断开连接
6. 类 Stomp 新增 isConnecting() 与 isDisconnecting() 方法
7. Stomp 模块抽象出 MsgCodec 接口，使得编解码模块易于扩展
8. Stomp 模块新增 MsgCodecImpl 实现类，并实现了半包粘包处理逻辑
9. Stomp 新增异常回调：setOnException(OnCallback<Throwable> onException)（since v3.1.1）

v3.0 的新特性（v3.0.4） #

1. JSON、XML 等结构化数据的统一抽象 API 分离作为独立的项目维护：

   https://gitee.com/troyzhxu/data

2. 依赖 data 项目中新增 HashMapper 与 ListArray 两个实现类

3. 升级事项: 用到以下四个类需要重新导包：

4. Stomp 在连接断开时重置 Subscriber 的状态，以便在重连后可以自动订阅（v3.0.3）
5. 重构 bodyType 与 Content-Type 机制，实现用户可以指定在 Content-Type 头中是否携带字符编码（v3.0.3）

v2.5 的新特性（v2.5.1） #

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 的新特性（v2.4.5） #

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 的新特性（v2.3.0） #

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

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

v2.2 的新特性（v2.2.0） #

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

v2.1 的新特性（v2.1.0） #

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 的新特性（v2.0.1） #

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）、具体请求可指定特殊编码功能。