gorilla/websocket 升级必须在 Gin 最外层 handler 直接调用 upgrader.Upgrade()，避免中间件消耗请求 body；连接管理需用 sync.RWMutex 保护 map；多端同步应以 UserID 为键维护 userClients；生产环境须拆分连接层与业务逻辑层。
gorilla/websocket 连接升级必须绕过 Gin 中间件链
直接在 gin.HandlerFunc 里调用 upgrader.Upgrade() 是唯一安全路径。Gin 的中间件（包括日志、JWT 鉴权等）会读取并消耗请求 body，导致升级 handshake 失败，报错 websocket: the response contains no upgrade header 或 http: read on closed response body。
实操建议：
- WebSocket 路由必须注册为 Gin 的最外层 handler，不经过任何中间件；例如：
r.GET("/ws", handleWebSocket)，而非r.Use(authMiddleware).GET("/ws", ...) - 若需鉴权，应在
upgrader.CheckOrigin或Upgrade后立即解析 query 参数或 cookie，失败则手动调用c.AbortWithStatus(http.StatusUnauthorized)并 return - 不要试图在
handleWebSocket函数内调用c.Next()或依赖c.Get()从中间件传参——此时上下文已不可靠
客户端连接管理不能只靠 map[*Client]bool
单机部署时用 map[*Client]bool 管理连接看似简单，但极易引发 panic：goroutine 并发读写未加锁的 map，错误信息是 fatal error: concurrent map writes 或 concurrent map read and map write。
正确做法是封装读写控制：
立即学习“go语言免费学习笔记（深入）”；
- 所有对 clients map 的操作（增、删、遍历）必须包裹在
sync.RWMutex的Lock()/Unlock()或R Lock()/RUnlock()中 - 广播消息时避免在锁内调用
conn.WriteMessage()—— 网络 I/O 可能阻塞，导致锁持有时间过长，拖垮整个 room - 推荐模式：用 channel 触发状态变更（如
register chan *Client），由单一 goroutine 持有锁处理，其他协程只发信号
多端同步的核心矛盾是“状态归属”而非“连接数”
用户从手机、PC、平板三端同时登录，本质不是连接变多，而是同一 UserID 对应多个 *websocket.Conn 实例。如果只按连接 ID 广播，会导致消息重复推送给同一人；如果只保留最新连接，旧端会断连失活。
关键设计点：
- 维护
userClients map[string]map[*Client]bool，以 UserID 为 key，内部再套一层 map 存该用户所有活跃连接 - 发送私聊时，遍历
userClients[recipientID]中每个*Client，逐个写入；不要只选一个 - 用户登出/心跳超时需清理指定 UserID 下的所有连接，而不是只删某个 conn —— 否则残留连接仍能收消息
- 上线通知、离线消息补推等逻辑，必须基于 UserID 统一调度，而非 Conn ID
生产环境必须拆离 WebSocket 连接层与业务逻辑层
把消息存储（MySQL）、在线状态（Redis）、群组关系（Redis Set）、推送限流（令牌桶）全堆在同一个 Gin 进程里，横向扩容时会立刻暴露瓶颈：连接数上不去、广播延迟飙升、Redis 连接打满。
轻量级解法（适合 1w 并发以内）：
- WebSocket server 只做连接维持、消息路由、基础校验；所有持久化、状态查询走 HTTP client 调用独立 service（如
http://msg-svc:8081/api/v1/messages） - 用 Redis Pub/Sub 做跨进程广播：各 WebSocket 实例订阅
chat:room:general频道，收到消息后只推给本机连接的客户端 - 用户登录/登出事件通过 Redis Stream 记录，由单独 consumer 更新全局在线状态，避免各实例自己维护不一致
真正难的不是写通一条连接，而是让十个客户端看到同一句话、同一份未读数、同一个头像更新——这些一致性边界，往往在压测第 3 小时才突然崩掉。
