Gin 无法直接处理 WebSocket，因其基于 HTTP 请求/响应模型，而 WebSocket 需接管 TCP 连接生命周期；必须绕过 Gin 路由，用 net/http + gorilla/websocket 在同一端口显式挂载 /ws 端点，并通过 http.ServeMux 整合 Gin 的 *gin.Engine 作为兜底 handler。
为什么直接用 Gin 的 net/http 基础连接处理不了 WebSocket？
Gin 本身不内置 WebSocket 支持，它的路由和中间件体系面向 HTTP 请求/响应模型，而 WebSocket 是长连接、双向通信，需要底层接管 TCP 连接生命周期。试图用 c.JSON() 或 c.String() 去“返回 WebSocket 协议升级响应”会失败——浏览器发的是 Upgrade: websocket 请求，Gin 默认直接返回 404 或 500，因为没注册对应 handler。
真正可行的路径只有一条：绕过 Gin 路由，用原生 net/http 启一个独立的 WebSocket 端点，再手动集成进 Gin 的服务实例里。
- 不要在 Gin 路由里写
ws.HandleFunc(...)——ws（如 gorilla/websocket）的 handler 和 Gin 的gin.HandlerFunc类型不兼容 - 必须复用 Gin 启动的
*http.Server实例，否则要开两个端口，增加部署复杂度 - 推荐用
gorilla/websocket，它比gobwas/ws更稳定，错误提示更明确，社区维护活跃
如何把 gorilla/websocket 接入 Gin 的 HTTP 服务？
核心是让 Gin 的 *gin.Engine 退化为一个 http.Handler，然后用 http.ServeMux 显式挂载 WebSocket handler 到特定路径（比如 /ws），其余路径仍交给 Gin 处理。
示例关键代码：
立即学习“go语言免费学习笔记（深入）”；
func main() {
r := gin.Default()
// 普通 API
r.GET("/api/messages", getMessages)
r.POST("/api/messages", postMessage)
// WebSocket 端点：不能走 r.GET("/ws", ...)！
mux := http.NewServeMux()
mux.Handle("/ws", &websocketHandler{})
mux.Handle("/", r) // 兜底给 Gin
srv := &http.Server{
Addr: ":8080",
Handler: mux,
}
srv.ListenAndServe()
}
type websocketHandler struct{}
func (h *websocketHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
upgrader := websocket.Upgrader{
CheckOrigin: func(r *http.Request) bool { return true }, // 开发期可放行，生产需校验 Origin
}
conn, err := upgrader.Upgrade(w, r, nil)
if err != nil {
http.Error(w, "Upgrade error", http.StatusBadRequest)
return
}
defer conn.Close()
// 此处开始收发消息逻辑（广播、用户标识、心跳等）
for {
_, msg, err := conn.ReadMessage()
if err != nil {
break
}
// 广播给所有连接（简化版）
broadcastMessage(msg)
}
}
-
upgrader.CheckOrigin默认拒绝非同源请求，开发时设为return true，但上线前必须改成校验r.Header.Get("Origin") - 不要在
ServeHTTP里直接写业务逻辑，应抽成独立管理器（如ClientManager），负责连接注册、广播、超时踢出 - 每个
conn.ReadMessage()都可能阻塞，别把它放在 Gin 中间件里——那是同步调用，会卡死整个 HTTP 处理队列
客户端连不上 /ws？检查这三处硬性限制
90% 的连接失败不是代码问题，而是协议或环境层面被拦截。
- 前端 JS 必须用
new WebSocket("ws://localhost:8080/ws")（ws://，不是http://）；HTTPS 站点必须用wss://，且后端需配 TLS 证书，否则浏览器静默拒绝 - Nginx 反向代理时，必须显式透传 WebSocket 头：
proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade";，缺一不可 - 本地测试若用 Chrome，禁用 “Use hardware acceleration when available” 有时能解决偶发的
WebSocket is closed before the connection is established错误（GPU 进程干扰）
消息广播性能差？别在每次 WriteMessage() 前遍历全部连接
当连接数超过 50，用锁 + 切片遍历所有 *websocket.Conn 并逐个 WriteMessage()，延迟会明显上升，还容易触发 write tcp: broken pipe（客户端已断开但服务端未感知）。
- 改用 channel 集中接收消息，由单个 goroutine 串行广播，避免并发写冲突
- 每个连接启动独立读/写 goroutine：读 goroutine 负责
ReadMessage()并推入全局消息 channel；写 goroutine 从专属 channel 读取消息并WriteMessage()，这样可对不同连接做写速率控制 - 务必设置
conn.SetWriteDeadline()，否则慢客户端会拖垮整个广播循环 - 不要用
time.Now().UnixNano()做消息 ID——高并发下可能重复，改用atomic.AddInt64(&msgID, 1)
真实场景里，连接管理、心跳保活、离线消息、用户身份绑定这些都不是 Gin 能帮你做的，框架只提供 HTTP 容器，WebSocket 的状态和业务逻辑必须自己扛。
