kxmall-ui/kxmall-rider-ui/utils/README.md

骑手端WebSocket工具说明

📁 文件结构

utils/
├── websocket.js          # WebSocket连接管理器
├── messageHandlers.js    # 消息处理器
└── README.md            # 说明文档

mixins/
└── websocketMixin.js    # WebSocket功能混入

config/
└── websocket.js         # WebSocket配置文件

store/modules/
└── websocket.js         # WebSocket状态管理

🚀 快速开始

1. 在页面中使用WebSocket功能

// 在页面组件中引入mixin
import websocketMixin from '@/mixins/websocketMixin.js';

export default {
  mixins: [websocketMixin],
  
  onLoad() {
    // mixin会自动处理WebSocket连接
    // 如果用户已通过审核，会自动连接WebSocket
  }
}

2. 自定义消息处理

// 在页面中重写消息处理方法
export default {
  mixins: [websocketMixin],
  
  methods: {
    // 重写新订单通知处理
    handleNewOrderNotification(message) {
      console.log('自定义处理新订单:', message);
      // 自定义逻辑
      this.showCustomOrderDialog(message);
    }
  }
}

3. 手动控制WebSocket

export default {
  mixins: [websocketMixin],
  
  methods: {
    // 手动连接
    connectManually() {
      this.initWebSocket();
    },
    
    // 手动断开
    disconnectManually() {
      this.disconnectWebSocket();
    },
    
    // 重连
    reconnectManually() {
      this.reconnectWebSocket();
    },
    
    // 发送消息
    sendTestMessage() {
      this.sendWebSocketMessage('test message');
    },
    
    // 检查连接状态
    checkStatus() {
      const status = this.getWebSocketStatus();
      console.log('WebSocket状态:', status);
    }
  }
}

🔧 配置说明

WebSocket配置 (config/websocket.js)

export default {
  connection: {
    maxReconnectAttempts: 5,    // 最大重连次数
    reconnectInterval: 5000,    // 重连间隔(ms)
    heartbeatInterval: 30000,   // 心跳间隔(ms)
    connectionTimeout: 10000    // 连接超时(ms)
  },
  
  notification: {
    enableSound: true,          // 启用声音提醒
    enableVibration: true,      // 启用震动提醒
    enableToast: true,          // 启用Toast通知
    urgentOrderModal: true      // 紧急订单使用模态框
  }
}

消息类型常量

import { MESSAGE_TYPES } from '@/utils/websocket.js';

// 可用的消息类型
MESSAGE_TYPES.NEW_ORDER           // 新订单
MESSAGE_TYPES.ORDER_CANCEL        // 订单取消
MESSAGE_TYPES.ORDER_STATUS_UPDATE // 订单状态更新
MESSAGE_TYPES.SYSTEM_MESSAGE      // 系统消息

📡 API参考

WebSocket管理器 (utils/websocket.js)

主要方法

import riderWebSocketManager from '@/utils/websocket.js';

// 连接WebSocket
riderWebSocketManager.connect(userInfo, baseUrl);

// 断开连接
riderWebSocketManager.disconnect();

// 发送消息
riderWebSocketManager.send('message');

// 检查连接状态
riderWebSocketManager.isConnected();

// 注册消息处理器
riderWebSocketManager.onMessage('NEW_ORDER', (message) => {
  console.log('收到新订单:', message);
});

// 注册状态变化处理器
riderWebSocketManager.onStatusChange((status, data) => {
  console.log('状态变化:', status);
});

消息处理器 (utils/messageHandlers.js)

处理器函数

import { 
  handleNewOrderNotification,
  handleOrderCancelNotification,
  handleSystemMessage,
  registerMessageHandlers,
  unregisterMessageHandlers
} from '@/utils/messageHandlers.js';

// 注册所有处理器
registerMessageHandlers(wsManager, this);

// 注销所有处理器
unregisterMessageHandlers(wsManager);

WebSocket混入 (mixins/websocketMixin.js)

提供的方法

// 混入提供的方法
this.initWebSocket()          // 初始化连接
this.disconnectWebSocket()    // 断开连接
this.reconnectWebSocket()     // 重连
this.sendWebSocketMessage()   // 发送消息
this.getWebSocketStatus()     // 获取状态
this.setWebSocketEnabled()    // 启用/禁用

生命周期处理

• onShow: 页面显示时自动检查并重连
• onHide: 页面隐藏时保持连接
• beforeDestroy: 组件销毁前清理资源
• onUnload: 页面卸载时断开连接

🎯 使用场景

场景1: 基础使用

// 只需要基本的WebSocket功能
export default {
  mixins: [websocketMixin]
  // 就这么简单！
}

场景2: 自定义通知

export default {
  mixins: [websocketMixin],
  
  methods: {
    handleNewOrderNotification(message) {
      // 自定义新订单处理逻辑
      if (message.urgencyLevel >= 3) {
        // 特急订单特殊处理
        this.playUrgentSound();
        this.showFullScreenAlert(message);
      } else {
        // 普通订单
        this.showToast(message.orderNo);
      }
    }
  }
}

场景3: 状态监控

export default {
  mixins: [websocketMixin],
  
  data() {
    return {
      wsStatus: '未连接'
    }
  },
  
  methods: {
    handleConnectionStatusChange(status) {
      this.wsStatus = status;
      // 更新UI状态显示
    }
  }
}

🐛 调试和故障排除

1. 启用调试日志

在开发环境中，WebSocket工具会自动输出详细的调试信息到控制台。

2. 常见问题

Q: WebSocket连接失败

// 检查用户状态
if (!this.userInfo || !this.userInfo.state) {
  console.log('用户未通过审核');
}

// 检查网络连接
// 检查服务器地址配置

Q: 消息处理器不工作

// 确保正确注册了处理器
registerMessageHandlers(riderWebSocketManager, this);

// 检查消息类型是否匹配
console.log('消息类型:', message.type);

Q: 自动重连不工作

// 检查重连配置
riderWebSocketManager.reset(); // 重置重连状态
this.reconnectWebSocket();      // 手动重连

3. 性能监控

// 检查连接状态
console.log('连接状态:', this.getWebSocketStatus());

// 查看重连次数
console.log('重连次数:', riderWebSocketManager.reconnectAttempts);

// 监控消息处理性能
performance.mark('message-start');
// 处理消息...
performance.mark('message-end');
performance.measure('message-processing', 'message-start', 'message-end');

📈 最佳实践

1. 使用mixin: 推荐使用websocketMixin，它处理了大部分生命周期管理
2. 自定义处理: 根据业务需求重写消息处理方法
3. 错误处理: 总是处理连接错误和消息解析错误
4. 性能优化: 避免在消息处理中执行耗时操作
5. 用户体验: 合理使用声音、震动等提醒方式
6. 状态管理: 使用Vuex模块管理WebSocket状态（可选）

🔄 版本更新

v1.0.0

• 基础WebSocket连接管理
• 消息处理器系统
• Vue混入支持
• 自动重连机制
• 心跳保活功能