gorilla/websocket是首选，因标准库net/http仅支持HTTP握手，不提供WebSocket帧解码、心跳等完整功能；硬写易出错且难应对生产问题。
为什么 gorilla/websocket 是首选而不是标准库 net/http
Go 标准库的 net/http 本身不提供 WebSocket 协议解析能力，仅能处理 HTTP 握手阶段；真正完成升级（Upgrade）、帧解码、心跳、连接状态管理等，必须依赖成熟实现。官方文档也明确建议使用 gorilla/websocket 或 gobwas/ws 等第三方包。
直接用标准库硬写 WebSocket 会陷入字节流解析、掩码校验、控制帧处理等底层细节，极易出错且无法应对生产环境的连接中断、重连、并发读写冲突等问题。
如何正确初始化 WebSocket 连接并避免 http: response.WriteHeader called multiple times
常见错误是：在调用 upgrader.Upgrade() 前或后，意外触发了 http.ResponseWriter 的其他写操作（如 w.WriteHeader()、w.Write()）。该函数内部已自动完成 HTTP 状态切换和响应头写入，任何前置或后续的显式响应操作都会导致 panic。
- 确保路由 handler 中 **只调用一次**
upgrader.Upgrade()，且它必须是该 handler 中对http.ResponseWriter的唯一写操作 - 升级失败时，应直接 return，不要试图再写错误页或 JSON
- 升级成功后，原
http.ResponseWriter和*http.Request不再可用，后续通信全部通过返回的*websocket.Conn进行
func chatHandler(w http.ResponseWriter, r *http.Request) {
conn, err := upgrader.Upgrade(w, r, nil)
if err != nil {
// 不要在这里调用 http.Error() 或 w.WriteHeader()
return
}
defer conn.Close()
// 后续所有读写都走 conn.ReadMessage() / conn.WriteMessage()
}
如何安全地广播消息而不引发 concurrent write to websocket connection
*websocket.Conn 的读写方法 **不是 goroutine 安全的**。多个 goroutine 同时调用 WriteMessage() 会导致 panic。聊天室典型场景中，一个连接可能同时被“新用户加入通知”“群聊消息”“系统踢出指令”等多个逻辑触发写操作，必须串行化。
立即学习“go语言免费学习笔记（深入）”；
- 为每个连接维护一个专属的写 goroutine + 消息 channel，所有写请求先发到 channel，由单个 goroutine 顺序消费并调用
conn.WriteMessage() - 避免在广播循环中直接调用
conn.WriteMessage()；应把消息推入各连接的写 channel - 写 channel 需设缓冲（如
make(chan []byte, 32)），防止发送方阻塞；但缓冲满时需考虑丢弃或限流，否则内存泄漏
type Client struct {
conn *websocket.Conn
send chan []byte // 所有写操作必须经此 channel
}
func (c *Client) writePump() {
defer c.conn.Close()
for message := range c.send {
if err := c.conn.WriteMessage(websocket.TextMessage, message); err != nil {
break
}
}
}
如何识别连接断开并及时清理客户端状态
WebSocket 连接断开不会立即触发 conn.ReadMessage() 返回 error —— 它可能卡在阻塞读，或返回过期的 pong 响应。仅靠读错误判断不可靠。必须结合 SetReadDeadline()、SetPingHandler() 和主动心跳检测。
- 在连接建立后，立即设置读超时：
conn.SetReadDeadline(time.Now().Add(pingPeriod)) - 注册自定义 ping 处理器：
conn.SetPingHandler(func(appData string) error { conn.SetReadDeadline(time.Now().Add(pingPeriod)); return nil })，确保每次收到 ping 就刷新读超时 - 启动独立 goroutine 定期发送
pong（实际由库自动处理），并监听conn.ReadMessage()的 error；若超时或 EOF，说明连接已失效，应从全局 client map 中删除该连接
漏掉 deadline 设置或 ping handler，会导致僵尸连接长期滞留，内存与 goroutine 泄漏会随时间恶化。
