gorilla/websocket 是 Go 生态 WebSocket 开发的事实标准，封装了协议升级、帧读写与心跳控制等核心能力，避免手动实现 RFC 6455 的复杂校验逻辑。
gorilla/websocket 是当前 Go 生态中 WebSocket 开发的事实标准，不是“可选方案”，而是绝大多数生产项目的起点。它不提供开箱即用的房间、广播或用户状态管理，但把协议升级、帧读写、心跳控制这些关键能力封装得足够稳定和可控——这意味着你得自己搭骨架，但不用从 TCP 连接开始造轮子。
为什么不能直接用 net/http 自己实现 WebSocket 升级？
WebSocket 握手不是简单返回 101 状态码就行。Sec-WebSocket-Key 必须经 SHA-1 + base64 处理生成 Sec-WebSocket-Accept，且必须严格校验客户端版本（Sec-WebSocket-Version: 13）、拒绝非法 Upgrade 请求。标准库 net/http 完全不处理这些。硬写会重复实现 RFC 6455 第 4.2 节逻辑，极易出错，比如：
- 忘记校验
Connection: Upgrade头，导致普通 GET 请求被误升为 WebSocket - 对
Sec-WebSocket-Key做了错误哈希（漏掉固定字符串"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"） - 未设置
Upgrade头，浏览器报Unexpected response code: 200
而 gorilla/websocket.Upgrader.Upgrade() 内部已完整覆盖这些边界检查，直接复用是最省心的选择。
Upgrader.CheckOrigin 在生产环境必须显式配置
默认情况下，Upgrader 会拒绝所有跨域请求（返回 403），因为浏览器强制要求 Origin 校验。本地开发时设成 func(r *http.Request) bool { return true } 很方便，但上线后等于裸奔：
- 任意网站都能建立连接，可能被用于 CSRF 或连接耗尽攻击
- CDN 或反向代理（如 Nginx）转发时，
r.Header.Get("Origin")可能为空或被篡改，需结合X-Forwarded-For或白名单域名判断 - 若使用子路径路由（如
/api/v1/ws），注意 Origin 是整个域名，不是路径
推荐做法是只放行已知前端域名：
CheckOrigin: func(r *http.Request) bool {
origin := r.Header.Get("Origin")
return origin == "https://your-app.com" || origin == "https://staging.your-app.com"
}
并发安全的连接管理必须用 sync.Map 或带锁 map，不能裸用 map[*websocket.Conn]bool
每个连接通常启动两个 goroutine：readPump（读消息）和 writePump（写消息）。当用户断连、服务重启或主动踢人时，多个 goroutine 可能同时修改连接映射表，导致 panic：fatal error: concurrent map writes。
立即学习“go语言免费学习笔记（深入）”；
-
map本身不是并发安全的，哪怕只读也需加sync.RWMutex -
sync.Map适合读多写少场景（如在线用户列表），但删除操作需注意：它不支持原子性“读+删”，得用LoadAndDelete - 更稳妥的做法是把连接注册/注销逻辑收口到一个中心
Hub结构体里，所有变更走 channel 或方法调用，避免裸露 map 操作
示例错误写法：
clients := make(map[*websocket.Conn]bool) // 多个 goroutine 直接 clients[conn] = true / delete(clients, conn) → crash
心跳超时必须由服务端主动触发，不能只依赖客户端 Ping
浏览器或移动端网络环境复杂，客户端可能卡死、休眠或被系统杀后台，此时它发不出 Ping，但 TCP 连接仍处于 ESTABLISHED 状态。仅靠 SetPingHandler 不足以清理僵尸连接。
- 必须调用
conn.SetPongHandler并在readPump中定期conn.SetReadDeadline，否则 read 阻塞永不返回 - 服务端应另起 goroutine，对每个连接定时发送
Ping（如每 30s 一次），并设置SetWriteDeadline；若连续 2 次失败，直接conn.Close() -
Upgrader的HandshakeTimeout和WriteTimeout是全局设置，无法按连接粒度定制，需手动控制
容易忽略的一点：Ping 帧本身不携带业务数据，但会占用连接带宽和服务器资源。高并发下频繁 Ping 可能引发写竞争，建议用 conn.WriteControl 而非 WriteMessage 发送。
