Gin 本身不内置 WebSocket 支持，必须搭配 gorilla/websocket 手动集成；升级连接前需调用 c.Abort() 避免中间件写响应头，鉴权后将用户 ID 与 *websocket.Conn 绑定至 sync.Map，发送消息前校验连接有效性并设写超时，禁用默认 recovery 中间件并在读写循环中手动 recover panic。
如何用 Gin 实现客服消息的实时推送（WebSocket）
直接说结论：Gin 本身不内置 WebSocket 支持，必须搭配 gorilla/websocket 手动集成。别试图用 gin.Context.Writer 直接升级连接——会触发 http: response.WriteHeader on hijacked connection 错误。
典型场景是客服坐席给用户发消息时，前端需要秒级收到通知。HTTP 轮询或 SSE 都不如 WebSocket 稳定低延迟，尤其在长连接复用、心跳保活、多客户端广播等环节。
-
gorilla/websocket是事实标准，Gin 官方示例也推荐它；gobwas/ws虽轻量但文档少、错误处理弱，不建议新项目用 - 升级 WebSocket 连接前，务必调用
c.Abort()，否则 Gin 中间件（比如日志、JWT 验证）可能继续执行并写响应头 - 连接建立后，
http.ResponseWriter和*http.Request就失效了，所有读写必须走*websocket.Conn对象
怎么安全地绑定用户 ID 到 WebSocket 连接
客服系统最怕消息错推——把 A 客服的消息发给了 B 用户。不能只靠 URL 参数传 user_id，必须校验身份合法性，且连接生命周期内绑定唯一标识。
推荐在 WebSocket 升级前完成鉴权，把用户信息存进连接上下文（比如用 context.WithValue），而不是存在全局 map 里靠 ID 查找——后者并发读写需加锁，且容易因连接断开未清理导致内存泄漏。
- URL 中带
?token=xxx，在 Upgrade 前用 JWT 解析出user_id和角色（如role: "customer"或"agent"） - 解析失败立即返回
401，绝不允许升级连接 - 成功后，把
user_id和*websocket.Conn存入线程安全的sync.Map，key 为user_id + role组合（避免客服和用户 ID 冲突） - 不要用 goroutine 持续
conn.ReadMessage()时不检查err == websocket.CloseMessage，否则连接断开后还往 map 里塞脏数据
如何向指定客服坐席推送消息（非广播）
用户提交咨询后，系统要精准推给某位空闲坐席，不是全量广播。这就要求连接管理必须支持“按坐席 ID 查连接”+“单点发送”，且发送失败要降级记录日志，不能阻塞主流程。
关键点在于：发送消息前先从 sync.Map 取连接，取到后立刻 conn.WriteJSON()；如果连接已关闭（websocket.IsClosedError(err)），就从 map 中删除该 entry，并跳过发送。
- 发送前加超时控制：
conn.SetWriteDeadline(time.Now().Add(5 * time.Second))，防止慢连接拖垮整个推送逻辑 - 别用
defer conn.Close()—— 关闭连接的时机应由业务决定（如坐席离线、token 过期），不是每次发完就关 - 若坐席连接不存在，消息应落库标记为“待推送”，等坐席重连后再补发（需额外设计状态机，不在 Gin 接口里硬做）
- 注意 JSON 序列化字段标签：客服端接收的消息结构体必须导出字段，且带
json:"msg_type"这类明确 tag，否则WriteJSON发过去是空对象
为什么要在 Gin 中禁用默认的 recovery 中间件
一旦 WebSocket 连接中发生 panic（比如解码 JSON 失败没 catch、map 并发写），Gin 默认的 recovery 中间件会尝试写 HTTP 响应头——而此时连接已被 hijack，直接 panic 并终止 goroutine，导致连接卡死、内存不释放。
正确做法是在注册 WebSocket 路由前，用 gin.New() 创建引擎，然后只加载必要中间件（如日志、跨域），显式跳过 recovery。连接内的 panic 必须由你手动 recover：
- 在
conn.ReadMessage()的 for 循环外层包一层defer func() { if r := recover(); r != nil { log.Printf("ws panic: %v", r) } }() - 所有对
sync.Map的读写操作，都用if conn, ok := m.Load(userID); ok { ... }判断，避免 nil pointer dereference - 生产环境务必开启
debug.SetGCPercent(-1)配合 pprof，WebSocket 长连接容易因 GC 不及时导致 STW 时间变长，表现为消息延迟突增
真正的难点不在写接口，而在连接生命周期管理——断连重试策略、心跳超时判定、连接数突增时的限流、以及如何让客服端准确感知“已接入坐席”而非“消息已发出”。这些没法靠 Gin 一行配置解决，得在连接建立后的 goroutine 里一一手动控制。
