starlette 处理 websocket 心跳监测的核心机制是依赖底层的 asgi 服务器(如 uvicorn)在连接空闲时自动发送 ping 帧,并在客户端无响应时主动关闭连接。开发者无需手动编写循环来维持连接,只需确保在 websocket 实例中正确实现 send() 和 receive() 逻辑即可。这种设计将连接保活的复杂性交由高性能的异步服务器处理,应用层代码专注于业务数据交换。

ASGI 服务器如何自动处理 Ping/Pong
Starlette 本身不直接生成心跳包,而是通过 ASGI 规范与服务器交互。当使用 Uvicorn 或 Hypercorn 等主流服务器时,它们会在 WebSocket 连接建立后,定期向客户端发送 WebSocket Ping 帧。如果客户端在规定时间内未回复 Pong 帧,服务器会判定连接失效并触发断开事件。这意味着在 Starlette 应用中,你不需要显式调用任何心跳函数,只要保持连接处于活跃状态,服务器就会负责“存活”检测。

import asyncio
from starlette.applications import Starlette
from starlette.routing import Route
from starlette.websockets import WebSocket
async def websocket_endpoint(websocket: WebSocket):
await websocket.accept()
try:
while True:
# 接收客户端消息,若连接断开此处会抛出异常
data = await websocket.receive_text()
await websocket.send_text(f"Echo: {data}")
except Exception as e:
print(f"Connection closed: {e}")
app = Starlette(routes=[Route("/ws", websocket_endpoint)])
上述代码展示了标准的 WebSocket 端点实现。当服务器检测到心跳超时或网络中断时,receive_text() 会抛出异常,从而跳出循环并执行清理逻辑。开发者应捕获此类异常以记录日志或释放资源,而不是试图在应用层重新发起心跳。
如何处理客户端断连后的资源清理
由于心跳监测由服务器底层完成,应用层的主要任务是响应连接断开事件。当服务器因心跳超时而关闭连接时,Starlette 的 WebSocket 对象会进入已关闭状态。此时,任何后续的 send() 操作都会失败,因此必须在 try...except 块中包裹所有 I/O 操作。此外,如果应用维护了全局的连接池或用户会话状态,需要在捕获到断开异常后,从这些结构中移除对应的 WebSocket 实例,以防止内存泄漏或向无效连接发送消息。
可水平扩展的 WebSocket 中心模式,支持懒加载 Redis 订阅、连接注册表和优雅关闭。适用于构建可跨多实例扩展的实时 WebSocket 服务器。

import asyncio
from starlette.applications import Starlette
from starlette.routing import Route
from starlette.websockets import WebSocket
# 模拟全局连接管理
active_connections = set()
async def websocket_manager(websocket: WebSocket):
await websocket.accept()
active_connections.add(websocket)
try:
while True:
data = await websocket.receive_text()
if data == "quit":
break
# 广播消息给其他连接
for conn in list(active_connections):
if conn != websocket:
await conn.send_text(f"User said: {data}")
except Exception:
pass
finally:
# 确保连接被移除
active_connections.discard(websocket)
await websocket.close()
app = Starlette(routes=[Route("/manager", websocket_manager)])
在这个示例中,finally 块确保了无论是因为正常退出还是心跳超时导致的断开,websocket 都会被从 active_connections 集合中移除。这是处理心跳监测副作用的关键步骤,保证了系统状态的最终一致性。
自定义心跳间隔是否可行
虽然 Starlette 允许开发者完全控制 WebSocket 的生命周期,但自定义心跳间隔通常不是通过 Starlette 本身实现的,而是通过配置 ASGI 服务器来完成。例如,Uvicorn 提供了 --ws-ping-interval 和 --ws-ping-timeout 参数来调整心跳行为。如果在应用层强行实现心跳,会导致双重心跳机制,增加网络开销且可能引发冲突。因此,最佳实践是保持应用层简洁,仅处理业务消息,并将心跳策略的配置留给服务器层。如果必须监控连接状态,可以通过监听断开事件并记录时间戳来实现,但这属于监控范畴,而非保活机制。










