OkHttps 之 WebSocket
相关文章：OkHttps 之 Stomp 客户端
OkHttps
OkHttps 是 OkHttp 的轻量封装包。和 Retrofit 相比，它更加的开箱即用，并且 API 更加自然和语义化。它用起来很优美，有点像 RxJava 却比 RxJava 更简单。
中文网站：http://okhttps.ejlchina.com/
项目地址
Gitee：https://gitee.com/ejlchina-zhxu/okhttps
GitHub：https://github.com/ejlchina/okhttps
WebSocket
OkHttps 使用webSocket(String url)方法发起 WebSocket 连接，并使用listen()方法启动监听。
连接参数
如果在连接时需要向服务器传递参数，处理方式和 HTTP 请求一样，例如需要用户名和密码才能连接 WebSocket 服务：
HTTP http = HTTP.builder().build();
http.webSocket("/chat")
.addUrlPara("username", "Jack")
.addUrlPara("password", "xxxxxxxx")
.setOnMessage((WebSocket ws，Message msg) -> {
})
.listen(); // 启动监听
::: warning 注意
WebSocket 连接只能添加 请求头、 Url 参数（查询参数）和 Path 参数, 报文体参数（Body）和 文件参数是不允许添加的。
:::
心跳机制
OkHttps 自带两种心跳机制
全局心跳配置
在构建HTTP实例时，可以配置一个全局心跳时间间隔：
HTTP http = HTTP.builder()
.config((OkHttpClient.Builder builder) -> {
// 配置 WebSocket 心跳间隔（默认没有心跳）
builder.pingInterval(10, TimeUnit.SECONDS);
})
.build();
如上配置，当使用这个HTTP实例发起 WebSocket 连接时，客户端会每隔 10秒 向服务器发送一次 PING 消息，同时服务器必须在客户端发送心跳后的 10秒 内回复 PONG 消息，否则就会触发SocketTimeoutException异常
单次心跳配置（since V2.3.0）
自 V2.3.0 起 OkHttps 提供了另外一种心跳机制，它在发起具体的 WebSocket 连接时通过方法heatbeat(int pingSeconds, int pongSeconds)分别指定客户端与服务器的心跳时间间隔：
http.webSocket("/chat")
.heatbeat(10, 10)
.setOnMessage((WebSocket ws，Message msg) -> {
// ...
})
.listen(); // 启动监听
如上配置，客户端仍会每隔 10秒 向服务器发送一次 PING 消息，并期望服务器回复 PONG 消息的间隔也是 10 秒一次，但如果服务器或网络由于某些未知原因导致客户端未能正确收到 PONG 消息，客户端还会容忍两次失败，当第三个 10 秒后还未收到服务器的任何消息时，则会触发SocketTimeoutException异常
::: tip OkHttps 的心跳机制相对于 OkHttp 主要有以下特点
- 客户端发送的任何消息都具有一次心跳作用
- 服务器发送的任何消息都具有一次心跳作用
- 若服务器超过 3 * pongSeconds 秒没有回复心跳，才触发心跳超时
:::
另外，还可以使用pingSupplier(Supplier<ByteString> pingSupplier)方法来指定心跳时发送的具体内容：
http.webSocket("/chat")
.heatbeat(10, 10)
.pingSupplier(() -> {
// 每次心跳发送一个换行符
return ByteString.encodeUtf8("\n");
})
.listen();
消息收发
接收消息
发起 WebSocket 连接是，设置一个OnMessage回调，便可接收到服务器的消息：
http.webSocket("/chat")
.setOnMessage((WebSocket ws，Message msg) -> {
// 接收到消息 msg
})
.listen(); // 启动监听
在该回调内接收到一个Message类型的消息对象，它和HttpReault.Body都继承自Toable接口，他共有如下一些方法：
-
isText()判断是文本消息还是二进制消息 -
toByteStream()消息体转字节流 -
toBytes()消息体转字数组 -
toByteString()消息体转字数组 -
toCharStream()消息体转字符流 -
toString()消息体转字符串 -
toMapper()消息体转 Mapper 对象（不想定义 Java Bean 时使用） -
toArray()消息体转 Array 数组（不想定义 Java Bean 时使用） -
toBean(Class<T> type)报文体Json文本转JavaBean -
toBean(Type type)报文体Json文本转JavaBean -
toBean(TypeRef<T> type)报文体Json文本转JavaBean -
toList(Class<T> type)报文体Json文本转JavaBean列表
发送消息
向服务器发送消息，首先要获得一个WebSocket实例，该实例可以通过listen()方法的返回值或回调方法的参数获取，如:
WebSocket ws = http.webSocket("/chat").listen(); // 启动监听，并返回一个 WebSocket 实例
接口WebSocket继承自Cancelable，它共定义了如下方法：
-
cancel()取消连接（连接成功前可以取消） -
queueSize()排队待发送消息的数量 -
send(Object object)发送消息，参数是待发送的对象，可以是 String | ByteString | byte[] | Java Bean -
close(int code, String reason)关闭连接（连接成功后可以关闭） -
msgType(String type)设置消息传输类型，类似于bodyType
一个发送消息的例子
WebSocket ws = http.webSocket("/chat").listen();
ws.send("Hello World!") // 该消息会先进入排队等待状态，当连接成功时发送给服务器
或者
http.webSocket("/chat")
.setOnOpen((WebSocket ws, HttpResult res) -> {
// 当连接成功时发送给服务器
ws.send("Hello World!")
})
.listen();
回调方法
WebSocket 连接共可设置 5 种回调方法：
http.webSocket("/websocket-endpoint")
.setOnOpen((WebSocket ws, HttpResult res) -> {
// WebSocket 连接成功时回调
})
.setOnMessage((WebSocket ws, Message msg) -> {
// 收到服务器下发的消息时回调
})
.setOnException((WebSocket ws, Throwable thr) -> {
// 连接发生异常时回调
})
.setOnClosing((WebSocket ws, WebSocket.Close close) -> {
// 连接正在关闭时回调
})
.setOnClosed((WebSocket ws, WebSocket.Close close) -> {
// 连接已关闭（v2.0.0 之后包含连接被取消 和 连接发生异常）时回调
})
.listen();
需要注意的是 如果设置了 全局回调监听, 它们对 WebSocket 连接 同样起作用
