webscoket-mitt/README.md

A plugin library that implements native WebSocket

# 🚀 websocket-mitt

> 🔥 一个基于原生webscoket设计的简单插件

### 一、项目背景与设计目标
___
- 背景：项目需要websocket功能，但是直接使用其它三方库又不能和后端自己写的库很好结合。所以基于原生webscoket实现基本的消息通信、心跳检测、断连重试等基本功能，再进行有效的封装便于在前端项目中更好使用。
- 目标：提供一个简单易用原生websocket插件,主要目标是让使用时候更好用
- 声明：本库只是解决日常项目中的问题，不会提供过于繁杂的功能

### 二、安装与快速上手
___
#### 安装
```bash
npm i websocket-mitt
```

#### 应用中
```javascript
import WebsocketMitt from 'websocket-mitt'

// 在合适的地方初始化
const wsMitt = new WebsocketMitt({ url: 'ws://localhost:3000' })

// 连接服务
wsMitt.connect()

// 监听消息
wsMitt.$on('message', (msg) => {
  console.log(msg)
})
```

### 三、API 说明
___
#### `new WebsocketMitt(options: WebSocketMittOptions)`
- 用途: 初始化webSocketMitt实例
- `options`: WebSocketMittOptions
  - `url`: string 服务连接地址
  - `heartbeatInterval`: number 心跳包间隔时间（毫秒）
  - `heartbeatMaxMissCount`: number 心跳包允许的最大失败次数
  - `reconnectDelay`: number 首次重连等待的时间（毫秒）
  - `maxReconnectDelay`: number 最大重连延迟（毫秒）
  - `maxReconnectCount`: number 最大允许重连次数   
  - `logging`: boolean 是否开启日志
  
#### `setOptions(options: WebSocketMittOptions)`
- 用途: 设置webSocketMitt配置，参数于初始化时一致，主要用于在连接前动态设置配置。
- `options`: WebSocketMittOptions
  - `url`: string 服务连接地址
  - `heartbeatInterval`: number 心跳包间隔时间（毫秒）
  - `heartbeatMaxMissCount`: number 心跳包允许的最大失败次数
  - `reconnectDelay`: number 首次重连等待的时间（毫秒）
  - `maxReconnectDelay`: number 最大重连延迟（毫秒）
  - `maxReconnectCount`: number 最大允许重连次数   
  - `logging`: boolean 是否开启日志

#### `connect()`
- 用途: 开启webscokect服务连接。注意：在调用该方法前，url服务连接地址是必须设置的

#### `exit()`
- 用途: 退出WebsocketMitt。注意：这个是退出方法，会将WebsocketMitt相关资源清空

#### `$on(event: string, msgCallback: Function)`
- 用途: 监听消息
- `event`: 消息的事件类型
- `msgCallback`: 消息的回调函数，function (message: WebSocketMittMessage) {}
  - `message`: 消息来自于websocket服务端发送的消息
  
#### `$emit(event: string, message: any)`
- 用途: 发送消息
- `event`: 消息的事件类型
- `message`: 消息内容

### 四、常见问题 Q&A
___
1. **websocket-mitt和服务端交换的消息数据解构是怎么样的？**
   - websocket-mitt和服务端交换的消息数据解构进行了定制，结构如下
```
      export type WebSocketMittMessage = {
        // 唯一标识
        id: string,
        // 事件类型
        event: string,
        // 消息内容
        data: any,
        // 时间戳
        timestamp: number
      }

    接收消息时：$on(event: string, (message: WebSocketMittMessage) => {})
       message的数据结构就是如上面所示

    发送消息时：$emit(event: string, data: any)
       data可以是任何数据，最终内部会将其包装成如上所示数据结构，再发送给服务器端   
```

2. **websocket-mitt事件类型event的解释？**
   - 事件类型event是用于标识不同的消息类型，是使用者和websocket-mitt进行交换的关键信息，其值可以是任意字符串，但是建议使用有意义的字符串，方便后续维护。websocket-mitt内置的值大致如下：
```
      export type WebSocketMittMessageType = {
        // 心跳包
        Beat: 'beat',
        // 普通消息
        Message: 'message',
        // 生命周期消息 - 服务连接
        WS_CONNECT: 'ws:connect',
        // 生命周期消息 - 服务错误
        WS_ERROR: 'ws:error',
        // 生命周期消息 - 服务关闭
        WS_CLOSE: 'ws:close',
        // 生命周期消息 - 服务退出
        WS_EXIT: 'ws:exit',
        // 生命周期消息 - 重连
        WS_RECONNECT: 'ws:reconnect',
        // 生命周期消息 - 重连失败
        WS_RECONNECT_FAILED: 'ws:reconnect-failed',
        // 生命周期消息 - 重连成功
        WS_RECONNECT_SUCCESS: 'ws:reconnect-success',
        // 生命周期消息 - 心跳响应失败
        WS_HEARBEAT_FAILED: 'ws:heartbeat-failed'
      } 
```


### 五、版本更新记录
___
- v0.0.1: 首次发布，完成应用间通信、心跳检测、断连重试基本功能
---