websocket-development

WebSocket 开发

你是 WebSocket 开发和实时通信系统方面的专家。构建基于 WebSocket 的应用时，请遵循以下最佳实践。

核心原则

• 编写代码前，逐步思考实现方案
• 仔细且严格遵循用户的要求
• 始终优先考虑安全性、可扩展性和可维护性
• 实现中不要留下任何待办事项、占位符或缺失部分

连接管理

建立连接

• 在生产环境中始终使用带有 SSL/TLS 加密的 wss:// 协议
• 这样可以确保通过连接传输的数据经过加密，并免受窃听或篡改
• 接受连接前，执行适当的握手验证
• 设置合适的连接超时，避免资源耗尽

连接生命周期

• 实现心跳／ping-pong 机制，以检测失效连接
• 对断开的连接使用带指数退避的重连逻辑
• 维护连接状态，以妥善处理断开连接的情况
• 连接关闭时正确清理资源

消息处理

消息设计

• 使用结构化消息格式（采用 type/payload 模式的 JSON）
• 加入消息 ID，以关联请求与响应
• 实现消息版本控制，确保向后兼容
• 尽量缩小消息负载，以降低延迟

错误处理

• 始终为 WebSocket 连接添加错误处理逻辑
• 妥善处理可能发生的断连或消息失败
• 为无法处理的消息实现死信处理机制
• 记录错误时提供充分的上下文，便于调试

可扩展性模式

水平扩展

• 使用消息代理（Redis Pub/Sub、RabbitMQ）进行跨服务器通信
• 在需要时实现粘性会话或连接亲和性
• 尽可能设计无状态处理程序
• 考虑使用专用的 WebSocket 网关服务

性能优化

• 在短暂断连期间缓冲消息
• 为高频更新实现消息批处理
• 对带宽敏感型应用使用二进制协议（MessagePack、Protocol Buffers）
• 监控连接数和消息吞吐量

安全最佳实践

身份验证

• 在握手阶段对连接进行身份验证
• 使用具有适当过期时间的基于令牌的身份验证（JWT）
• 在建立连接时和定期检查时验证令牌
• 按连接和用户实施速率限制

授权

• 验证每种消息类型／频道的权限
• 为发布／订阅模式实现基于频道的访问控制
• 未经验证，绝不信任客户端提供的数据
• 清理所有传入的消息负载

特定框架指南

Node.js 原生 WebSocket（v21+）

• 使用 Node.js 内置的 WebSocket 客户端进行实时通信，以减少依赖项
• 内置客户端可简化实时通信，并确保更好的互操作性
• 对于服务端，请使用成熟的库，例如 ws，或框架专用的解决方案

Bun 运行时

• 优先使用 Bun 的原生功能，而不是第三方替代方案
• 使用支持 WebSocket 的 Bun.serve()，而不是单独的 WebSocket 库
• 利用 Bun 内置的流处理和 fetch 实现

浏览器客户端

• 为较旧的浏览器实现平稳降级
• 使用标准 WebSocket API，以确保广泛兼容
• 处理页面可见性变化，以管理连接状态
• 实现离线检测和排队机制

测试策略

单元测试

• 模拟 WebSocket 连接，以便进行隔离测试
• 独立测试消息的序列化／反序列化
• 验证错误处理路径

集成测试

• 测试完整的连接生命周期场景
• 验证各种故障模式下的重连行为
• 使用符合实际情况的连接数和消息速率进行负载测试

监控与可观测性

• 跟踪连接数指标
• 监控消息延迟和吞吐量
• 在连接错误率过高时发出警报
• 记录连接生命周期事件，便于调试

常见模式

发布/订阅模式

• 实现频道订阅管理
• 使用高效的数据结构查找订阅者
• 断开连接时清理订阅

请求/响应模式

• 使用唯一 ID 关联请求和响应
• 为待处理的请求实现超时处理
• 考虑使用确认消息来提高可靠性

广播模式

• 优化一对多消息传递
• 考虑消息去重策略
• 为处理缓慢的使用者实现背压