直接用 Go 的 HTTP handler 做协同编辑会卡死，因其请求-响应模型无法支持服务端主动推送，必须改用 WebSocket 长连接配合 gorilla/websocket 库，结合 sync.Map 管理连接、手动处理 ping/pong、分离读写 goroutine，并手写 OT 变换逻辑。
为什么直接用 Go 的 HTTP handler 做协同编辑会卡死
因为协同编辑本质是双向实时通信，HTTP 的请求-响应模型天然不支持服务端主动推数据。你用 http.HandleFunc 接收编辑操作、再查数据库、再返回 JSON，用户 A 删了一行，用户 B 根本收不到——除非她每秒轮询一次，那延迟高、连接爆炸、服务器扛不住。
真正可行的路径只有一条：用 WebSocket 维持长连接，让所有客户端和服务器之间形成“常开通道”。Go 本身没内置 WebSocket 支持，得靠第三方库，gorilla/websocket 是目前最稳、文档最全、生产环境验证最多的选型。
- 别用
gobuffalo/websocket或centrifugo这类封装过重的方案——协同逻辑必须自己掌控，比如操作合并、冲突检测、光标同步，中间插一层抽象只会让你调试时找不到消息在哪丢的 - WebSocket 连接要绑定用户身份（比如
user_id），但别存在map[string]*websocket.Conn里就完事——没加锁，多 goroutine 并发写会 panic；更糟的是没做连接生命周期管理，断连后残留指针会导致内存泄漏 - 每次收到编辑操作（如 {“op”: “insert”, “pos”: 12, “text”: “hello”}），不能直接广播给所有人。得先走 OT（Operational Transformation）或 CRDT 流程，否则两个用户同时在开头插入，结果顺序错乱
怎么用 gorilla/websocket 管理多人连接并避免 panic
核心是把连接、用户 ID、房间 ID 绑定到一个结构体里，并用 sync.Map 存全局连接池——它比原生 map + mutex 更适合读多写少的场景（比如 95% 消息是广播，只有 5% 是新连接/断开）。
关键代码片段：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
type Client struct {
conn *websocket.Conn
userID string
roomID string
mu sync.RWMutex
}
var clients = sync.Map{} // key: clientID (string), value: *Client
// 注册新连接时：
client := &Client{conn: wsConn, userID: uid, roomID: rid}
clients.Store(generateClientID(), client) // 不用 uid 做 key，防重复登录挤掉旧连接
// 广播前必须检查 conn 是否还活着：
if err := client.conn.WriteMessage(websocket.TextMessage, data); err != nil {
client.conn.Close() // 主动关，触发 defer 里的 cleanup
clients.Delete(clientID)
}
- 永远在
defer client.conn.Close()后立即调用clients.Delete()，不然断连后连接对象还在 map 里挂着，下次广播时WriteMessage直接 panic: “use of closed network connection” - 别在 WebSocket
ReadMessage循环里直接处理 OT —— 解析 JSON、计算变换、查 DB 全部是阻塞操作，会卡住整个 goroutine，导致 ping/pong 超时断连。应该把原始消息塞进 channel，另起 goroutine 消费 - ping/pong 必须手动处理：
conn.SetPingHandler和conn.SetPongHandler都要设，否则 Nginx 或 Cloudflare 默认 60s 断空闲连接，而 gorilla 默认 0 秒超时
OT 变换逻辑必须自己写，别信“协同库自动搞定”
Go 生态几乎没有成熟、可嵌入的 OT 库。像 sharejs（JS）或 ot.js 那种完整实现，在 Go 里要么缺失、要么年久失修。你最终一定得手写核心变换函数，比如 transformInsert 和 transformDelete。
最简但可用的 insert 变换示例（假设操作含 pos 和 text）：
func transformInsert(a, b Operation) (Operation, Operation) {
if b.Pos <= a.Pos {
a.Pos += len(b.Text) // b 插在前面，a 的位置往后挪
}
if a.Pos <= b.Pos {
b.Pos += len(a.Text) // a 插在前面，b 的位置往后挪
}
return a, b
}
- 这个例子只处理 insert，delete 和 retain 必须单独写，且要严格按 OT 论文定义的 3 类操作组合判断——漏一种 case，比如 “A 删除第 5 字符，B 在第 3 位插入”，结果就是两人看到的文档完全对不上
- 所有操作必须带时间戳或序列号（
counter），用于确定执行顺序。别用本地time.Now()，要用服务端统一递增的atomic.Int64，否则分布式部署时多台机器时间不同步，操作重排就乱套 - 操作日志不能只存内存——进程重启后所有状态归零。至少写入 Redis Stream 或 SQLite WAL 模式，保证 crash 后能重放操作流恢复文档状态
光标和选区同步为什么比文档内容还难搞
文档内容最终会收敛，但光标是瞬时状态：用户 A 把光标移到第 10 行，还没来得及输入，网络抖动延迟 800ms，此时用户 B 已经删了前 5 行——A 的光标坐标直接越界。纯靠服务端广播坐标毫无意义。
- 必须把光标当作“操作”来处理：每次移动光标都生成一个
cursor: {userID, pos, timestamp}操作，走和编辑操作一样的 OT 流程，和其他 insert/delete 合并变换 - 客户端不能直接渲染服务端发来的光标位置。得拿当前本地文档快照长度做校验，如果
pos > len(doc)，就自动 fallback 到文档末尾，并上报异常日志——这是唯一能防止白屏或 panic 的兜底方式 - 选区（selection）要拆成两个光标（anchor + focus），各自变换。但注意浏览器 Selection API 返回的 offset 是 DOM 节点内偏移，不是纯文本偏移，和服务端维护的线性 position 不一致，转换时必须用相同的文本 normalization 规则（比如把 \r\n 全转成 \n）
协同编辑最难的从来不是“怎么传数据”，而是“怎么让所有人对‘此刻文档长什么样’达成瞬时共识”。OT 逻辑、连接治理、光标变换，三者只要一环松动，用户就会看到文字跳来跳去、光标消失、甚至整段内容错位。没有银弹，每个点都得亲手压测过。
