WebSocket

OkHttps 使用webSocket(String url)方法发起 WebSocket 连接，并使用listen()方法启动监听。

连接参数

如果在连接时需要向服务器传递参数，处理方式和 HTTP 请求一样，例如需要用户名和密码才能连接 WebSocket 服务：

http.webSocket("/chat") 
        .addUrlPara("username", "Jack")
        .addUrlPara("password", "xxxxxxxx")
        .setOnMessage((WebSocket ws，Message msg) -> {

        })
        .listen();              // 启动监听

1
2
3
4
5
6
7

注意

WebSocket 连接只能添加 请求头、 Url 参数（查询参数）和 Path 参数, 报文体参数（Body）和文件参数是不允许添加的。

心跳机制

OkHttps 自带两种心跳机制

全局心跳配置

在构建HTTP实例时，可以配置一个全局心跳时间间隔：

HTTP http = HTTP.builder()
    .config((OkHttpClient.Builder builder) -> {

        // 配置 WebSocket 心跳间隔（默认没有心跳）
        builder.pingInterval(10, TimeUnit.SECONDS);
    })
    .build();

1
2
3
4
5
6
7

如上配置，当使用这个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();              // 启动监听

1
2
3
4
5
6

如上配置，客户端仍会每隔 10秒向服务器发送一次 PING 消息，并期望服务器回复 PONG 消息的间隔也是 10 秒一次，但如果服务器或网络由于某些未知原因导致客户端未能正确收到 PONG 消息，客户端还会容忍两次失败，当第三个 10 秒后还未收到服务器的任何消息时，则会触发SocketTimeoutException异常

OkHttps 的增强型心跳机制（单次心跳配置）相对于 OkHttp 的全局心跳配置主要有以下特点

客户端发送的任何消息都具有一次心跳作用
服务器发送的任何消息都具有一次心跳作用
若服务器超过 3 * pongSeconds 秒没有回复心跳，才触发心跳超时

固定心跳发送间隔（since v2.5.0）

默认的单次心跳机制的心跳发送间隔是灵活可变的，它可以保证客户端在一个心跳周期内一定有一帧数据发给服务端，但被发送的并不一定会是心跳帧。这在大多数情况下是可行，但是也不排除存在某些服务器，它严格要求客户端以固定的间隔发送心跳帧，这时我们可以使用 flexiblePing(boolean) 方法来控制心跳发送机制：

http.webSocket("/chat") 
        .heatbeat(10, 10)
        .flexiblePing(false)    // 传入 false 让客户端以固定间隔发送心跳
        .setOnMessage((WebSocket ws，Message msg) -> {
            // ...
        })
        .listen();

1
2
3
4
5
6
7

心跳内容定制

另外，在使用 OkHttps 的增强型心跳机制时，还可以同时使用pingSupplier(Supplier<ByteString> pingSupplier)方法来指定心跳时发送的具体内容：

http.webSocket("/chat") 
        .heatbeat(10, 10)
        .pingSupplier(() -> {
            // 每次心跳发送一个换行符
            return ByteString.encodeUtf8("\n");
        })
        .listen();

1
2
3
4
5
6
7

WARNING

如果你开发的是安卓应用，并需要兼容 Android 6.0 及以下版本，当使用增强型心跳机制时，请确保使用的 OkHttps 不低于 v2.4.5

消息收发

接收消息

发起 WebSocket 连接是，设置一个OnMessage回调，便可接收到服务器的消息：

http.webSocket("/chat") 
        .setOnMessage((WebSocket ws，Message msg) -> {
            // 接收到消息 msg
        })
        .listen();                     // 启动监听

1
2
3
4
5

在该回调内接收到一个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
status() 获取当前的连接状态（v2.4.5 起）

一个发送消息的例子

WebSocket ws = http.webSocket("/chat").listen();
ws.send("Hello World!")     // 该消息会先进入排队等待状态，当连接成功时发送给服务器

1
2

或者

http.webSocket("/chat") 
        .setOnOpen((WebSocket ws, HttpResult res) -> {
            // 当连接成功时发送给服务器
            ws.send("Hello World!")
        })
        .listen();

1
2
3
4
5
6

回调方法

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

需要注意的是

如果设置了全局回调监听, 它们对 WebSocket 连接同样起作用

最大 Closing 时长

http.webSocket("/websocket-endpoint")
        .setOnClosing((WebSocket ws, WebSocket.Close close) -> {
            // 连接正在关闭时回调
        })
        .setOnClosed((WebSocket ws, WebSocket.Close close) -> {
            // 某些情况下，该回调的执行时间 有较大的延迟
        })
        .setMaxClosingSecs(10)  // 指定 OnClosing 执行后，OnClosed 回调执行延时的最大时间，默认 10s
        .listen();

1
2
3
4
5
6
7
8
9

连接状态

除了可以在回调方法中获取当前的链接状态，当我们拿到一个WebSocket实例后，也可以直接取其中的状态（v2.4.5 起），例如：

WebSocket ws = http.webSocket("/websocket-endpoint")
        // ...
        .listen();

int status = ws.status();   // 获取当前的连接状态

if (status == WebSocket.STATUS_CONNECTING) {
    // 正在连接
}
if (status == WebSocket.STATUS_CONNECTED) {
    // 已建立连接
}
if (status == WebSocket.STATUS_DISCONNECTED) {
    // 已断开连接（正常断开）
}
if (status == WebSocket.STATUS_CANCELED) {
    // 已取消连接
}
if (status == WebSocket.STATUS_TIMEOUT) {
    // 已连接超时
}
if (status == WebSocket.STATUS_NETWORK_ERROR) {
    // 连接网络错误
}
if (status == WebSocket.STATUS_EXCEPTION) {
    // 连接发生异常
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

另外，当拿到WHttpTask时，也可以用它判断连接是否已建立，例如：

WHttpTask task = http.webSocket("/websocket-endpoint");
boolean connected = task.isConnected()  // 连接是否已建立

1
2

WebSocket #

连接参数 #

心跳机制 #

全局心跳配置 #

单次心跳配置（since V2.3.0） #

固定心跳发送间隔（since v2.5.0） #

心跳内容定制 #

消息收发 #

接收消息 #

发送消息 #

回调方法 #

最大 Closing 时长 #

连接状态 #

WebSocket

连接参数

心跳机制

全局心跳配置

单次心跳配置（since V2.3.0）

固定心跳发送间隔（since v2.5.0）

心跳内容定制

消息收发

接收消息

发送消息

回调方法

最大 Closing 时长

连接状态