# 介绍

# 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 (opens new window) 2.5.1 OkHttps 核心模块
okhttps-fastjson (opens new window) 2.5.1 与 fastjson 集成
okhttps-gson (opens new window) 2.5.1 与 gson 集成
okhttps-jackson (opens new window) 2.5.1 与 jackson 集成
okhttps-stomp (opens new window) 2.5.1 超轻量 Stomp 客户端(无第三方依赖)
okhttps-xml (opens new window) 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

# Gradle

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

# 版本迭代

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

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

# v2.5 的新特性

# API 部分
  1. HTTP#Builder新增contentTypes方法,可扩展配置默认支持的请求类型
  2. HTTP#Builder新增clearPreprocessorsclearMsgConvertors方法
  3. HttpResult新增getTask方法,可获取所属的请求任务
  4. HttpResult新增of(HttpTask<?>, Response)方法,可构造一个HttpResult实例
  5. WebSocketTask新增flexiblePing(boolean)方法,当传参false时,可兼容某些强制客户端必须以固定的间隔发送心跳的服务器
  6. Stomp新增sendToTopicsendToQueue方法,
  7. Stomp新增isConnected方法,可直接判断连接是否已建立
# 优化部分
  1. 优化自定义请求方法HttpTask#request()的参数处理:请求方法自动 toUpperCase,避免用户传入小写时造成意想不到的问题
  2. 优化bodyTypemsgType的参数处理,自动 toLowerCase,避免用户传入大写时造成意想不到的问题
  3. 使得未添加MsgConvertor时,使用setBodyPara(String|byte[])bodyType方法也能够发起对应格式的请求
  4. 优化 Stomp 订阅与退订机制:同一个实例支持多线程并发订阅与退订操作
  5. 优化 Stomp 消息匹配机制:兼容 RabbitMQ 在某些情况下的推送的 消息目的地 与 订阅目的地 不一致的情况
  6. 优化 Stomp 连接的断开流程:在连接断开前保证已发消息到达服务器
  7. 优化文件下载的异常处理流程
# 升级注意事项:
  1. FileParaHttpTask中分离,不再是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()
  1. 优化性能:使用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 方式注入配置,OkHttpsHttpUtils默认自动以 SPI 方式寻找依赖中的MsgConvertor
  7. 新增可自定义默认编码(不自定义依然默认为 utf-8)、具体请求可指定特殊编码功能。

#