WebSocket 客户端

build coverage pub package style: very good analysis License: MIT

一个简单的 Dart WebSocket 客户端，包含自动重连逻辑。

快速开始 ?

// Create a WebSocket client.
final socket = WebSocket(Uri.parse('ws://:8080'));

// Listen to messages from the server.
socket.messages.listen((message) {
  // Handle incoming messages.
});

// Send a message to the server.
socket.send('ping');

// Close the connection.
socket.close();

建立连接？

WebSocket 客户端将在初始化时立即尝试建立连接。默认情况下，如果建立连接超过 60 秒，将发生超时，但可以提供自定义的 timeout 持续时间。

final uri = Uri.parse('ws://:8080');

// Trigger a timeout if establishing a connection exceeds 10s.
final timeout = Duration(seconds: 10);
final socket = WebSocket(uri, timeout: timeout);

重新连接？

如果 WebSocket 客户端未能建立连接，它将使用提供的 Backoff 策略自动尝试重新连接。默认情况下，使用 BinaryExponentialBackoff，但可以提供自定义的 backoff。

有三种内置的退避策略，但可以通过实现 Backoff 接口来编写自定义退避策略。

ConstantBackoff

此退避策略将使 WebSocket 客户端在重连尝试之间等待恒定的时间。

// Wait a constant 1s between reconnection attempts.
// [1, 1, 1, ...]
const backoff = ConstantBackoff(Duration(seconds: 1));
final socket = WebSocket(uri, backoff: backoff);

LinearBackoff

此退避策略将使 WebSocket 客户端等待线性递增的时间，直到达到可选的最大持续时间。

// Initially wait 0s and increase the wait time by 1s until a maximum of 5s is reached.
// [0, 1, 2, 3, 4, 5, 5, 5, ...]
const backoff = LinearBackoff(
  initial: Duration(seconds: 0),
  increment: Duration(seconds: 1),
  maximum: Duration(seconds: 5),
);
final socket = WebSocket(uri, backoff: backoff);

BinaryExponentialBackoff

此退避策略将使 WebSocket 客户端等待指数递增的时间，直到达到最大步数。

// Initially wait 1s and double the wait time until a maximum step of of 3 is reached.
// [1, 2, 4, 4, 4, ...]
const backoff = BinaryExponentialBackoff(
  initial: Duration(seconds: 1),  
  maximumStep: 3
);
final socket = WebSocket(uri, backoff: backoff);

监控连接 ⚡️

WebSocket 客户端公开了一个 connection 对象，该对象可用于在任何给定时间查询连接状态以及监听连接状态的实时变化。

final uri = Uri.parse('ws://:8080');
final socket = WebSocket(uri);

// Listen to changes in the connection state.
socket.connection.listen((state) {
  // Handle changes in the connection state.
});

// Query the current connection state.
final connectionState = socket.connection.state;

连接状态可以是以下任一状态：

  • connecting：连接尚未建立。
  • connected：连接已建立，可以进行通信。
  • reconnecting：连接已丢失，正在重新建立。
  • reconnected：连接已丢失并已重新建立。
  • disconnecting：连接正在进行关闭握手，或已调用 close 方法。
  • disconnected：WebSocket 连接已关闭或未能建立。

* disconnected 连接状态包含可空的关闭代码、关闭原因、错误和堆栈跟踪字段。

发送消息？

一旦建立了 WebSocket 连接，就可以通过 send 将消息发送到服务器。

final socket = WebSocket(Uri.parse('ws://:8080'));

// Wait until a connection has been established.
await socket.connection.firstWhere((state) => state is Connected);

// Send a message to the server.
socket.send('ping');

接收消息？

通过 messages 流监听来自服务器的传入消息。

final socket = WebSocket(Uri.parse('ws://:8080'));

// Listen for incoming messages.
socket.message.listen((message) {
  // Handle the incoming message.
});

关闭连接？

一旦建立了 WebSocket 连接，如果连接中断，它将自动尝试重新连接。调用 close() 将把连接状态更新为 disconnecting，执行关闭握手，并将状态设置为 disconnected。此时，WebSocket 客户端将不会尝试重新连接，需要创建新的 WebSocket 客户端实例才能建立新连接。

final socket = WebSocket(Uri.parse('ws://:8080'));

// Later, close the connection with an optional code and reason.
socket.close(1000, 'CLOSE_NORMAL');

GitHub

查看 Github