如何实现FastAPI中的WebSocket长连接与心跳机制，避免填坑？

📌 摘要：本文通过一个真实的上线案例，详细讲解FastAPI与JavaScript实现WebSocket长连接保持的心跳机制。你会了解为什么连接会断、心跳原理是什么、前后端代码怎么写，以及那些文档里没写的调优陷阱。照着做，让你的实时通信稳如老狗。 你是不是也遇到过——WebSocket连接动不动就断开，尤其是在移动端，用户切换个Wi-Fi或者电梯里信号晃一下，消息就收不到了？📱 用户投诉说“APP消息延迟”，你一查日志，满屏都是WebSocket disconnected，然后疯狂重连，服务器压力山大，用户体验稀碎。 有些项目图省事，觉得WebSocket连上就行了，结果线上跑了半天，运维小哥就发来报警：连接数忽高忽低，很多连接存活不到2分钟。查日志，好家伙，Nginx默认proxy_read_timeout 60秒，加上移动网络运营商会掐掉长时间无流量的连接，双向夹击，连接全断了。😭 核心结论：WebSocket长连接保持，不能靠“连上就不管”，必须引入心跳机制——就像两个人打电话，每隔一会儿问一句“喂，还在吗？”。今天我就把FastAPI后端 + JavaScript前端的完整心跳实现，掰开了揉碎了讲给你听，顺便把我踩过的坑标红。 🚦 本文路线图 🔹 为什么WebSocket会断？—— 中间件超时、网络状态变化 🔹 心跳原理：ping-pong 还是 pong-ping？ 🔹 FastAPI后端：接收心跳消息 + 超时管理 🔹 JavaScript前端：定时发送心跳 + 断线重连 🔹 完整可运行代码示例 🔹 那些年我踩过的坑（间隔设置、重复定时器、服务端主动断开） 🧠 第一部分：连接为什么会断？ 把WebSocket想象成一条水管，数据就是水。如果水管一直流水，它就不会堵。但要是你半天不放水，中间的路由器、防火墙就觉得“嘿，这管子是不是废弃了？”——咔嚓一刀给你掐了。尤其是在移动网络下，运营商的NAT网关空闲超时可能只有30秒到几分钟。还有我们常用的Nginx，默认proxy_read_timeout是60秒，一旦60秒内没有数据从后端发到客户端，Nginx就会自作主张断开连接。 所以，要想让连接长存，唯一的方法就是定期发送一些“无用”的数据，告诉中间件：“我还活着，别砍我！”——这就是心跳。 💓 第二部分：心跳机制的两种姿势 心跳本质是一种ping/pong模式。WebSocket协议本身有控制帧Ping和Pong，但浏览器原生JS的WebSocket API并没有直接暴露发送Ping帧的方法，所以我们一般用普通消息模拟： ✨ 方案A：客户端定时发送ping消息，服务器收到后立即回复pong。 ✨ 方案B：服务器定时发送ping，客户端回复pong。但同样，客户端需要能解析并回复。 更常见的做法是客户端主动发心跳，服务器只需响应或记录。为啥？因为客户端更能感知网络变化，且断开后能立即重连。下面我就以客户端发心跳为例，上代码。 ⚙️ 第三部分：FastAPI后端实战 先搭一个最简单的FastAPI WebSocket端点。这里我用了/ws路径，接收心跳消息（约定JSON格式{"type": "ping"}），并回复{"type": "pong"}。同时，为了及时清理死连接，我会记录每个连接的最后心跳时间，启动一个后台任务检查超时（比如60秒没收到心跳就主动close）。