因为Go原生map非线程安全，Gin handler并发执行时多goroutine同时读写会导致panic；sync.Map虽线程安全但不支持遍历，适合单点推送而非广播；WebSocket升级需用原始ResponseWriter，不可复用c.Writer；推送前须检查连接状态并处理错误，避免goroutine泄漏。
为什么 Gin 的 HTTP handler 里不能直接用全局 map 存 WebSocket 连接
因为 Gin 的 handler 是并发执行的，多个请求可能同时读写同一个 map，Go 运行时会 panic 报 fatal error: concurrent map read and map write。这不是 Gin 的问题，而是 Go 原生 map 非线程安全。你可能会想加 sync.Mutex，但锁粒度控制不好反而导致推送延迟或阻塞 HTTP 请求。
用 sync.Map 管理客户端连接更合适
sync.Map 是 Go 标准库专为高并发读多写少场景设计的线程安全映射，适合存客户端 ID 到 *websocket.Conn 的映射。注意它不支持遍历（range 不可用），所以不能靠它做“广播”；但单点推送（按 clientID）完全够用。
- 存储键建议用字符串，比如
"user:123"或"session:abc456"，避免用指针或结构体作 key - 写入前不必检查 key 是否存在：
clients.Store(clientID, conn)直接覆盖 - 读取后务必类型断言：
if conn, ok := clients.Load(clientID); ok { ... }，否则可能 panic - 连接关闭时记得
clients.Delete(clientID)，否则内存泄漏
WebSocket 升级必须在 Gin handler 内完成，且不能复用 c.Writer
Gin 的 c.Writer 已被框架封装，直接传给 websocket.Upgrader.Upgrade() 会报 http: response.WriteHeader on hijacked connection。必须用原始 http.ResponseWriter 和 http.Request。
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
var upgrader = websocket.Upgrader{
CheckOrigin: func(r *http.Request) bool { return true }, // 生产需校验 Origin
}
func wsHandler(c *gin.Context) {
conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
if err != nil {
return
}
defer conn.Close()
clientID := c.Query("id") // 或从 JWT token 解析
clients.Store(clientID, conn)
// 启动读协程（可选：处理前端发来的消息）
go func() {
for {
_, _, err := conn.ReadMessage()
if err != nil {
break
}
}
clients.Delete(clientID)
}()
// 阻塞等待，保持连接存活（实际中可加心跳）
select {}
}
后台 goroutine 推送通知时要防御连接已断开
推送不是“发了就完事”。客户端可能已断网、刷新页面、或超时关闭，此时 conn.WriteMessage() 会返回 websocket: close sent 或 io.EOF。不检查错误会导致 goroutine 泄漏或 panic。
立即学习“go语言免费学习笔记（深入）”；
- 每次推送前先用
conn.WriteMessage()尝试发送，检查返回 err - 若 err 非空，立即
conn.Close()并clients.Delete(clientID) - 不要在推送逻辑里 sleep 或重试——这是业务层该决定的事，底层只保证“尽力一次”
- 如果需要确认送达，得由前端收到后主动回一个 ACK 消息，服务端监听并标记状态
真正难的不是怎么推，而是怎么知道没推成功、以及失败后要不要补发、推几次、间隔多久——这些都得结合业务状态机来设计，sync.Map 和 websocket.Conn 只负责把字节送到 TCP 连接上。
