🚀 websocket-mitt

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

一、项目背景与设计目标

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

二、安装与快速上手

安装

npm i websocket-mitt

应用中

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: 首次发布，完成应用间通信、心跳检测、断连重试基本功能